This is an example demonstrating some basic features of ge_tts, a library for developing Tabletop Simulator mods.
To run this demo, you need a TTS IDE that supports require()
. It’s
suggested you use the official
Tabletop
Simulator Atom plugin to run this mod.
💡
|
Alternatively, you may use @rolandostar’s Visual Studio Code plugin. |
Having said the above…
Through-out this demo there are many comments that look like
---@shape <blah>
, ---@field <blah>
--[[---@type <blah>]]
and so on.
These are special type annotations. They have zero impact on how
Tabletop Simulator runs your code. They’re just like regular comments
except they provide useful hints to IDEs that support them. These hints
allow IDEs to not just auto-complete Tabletop Simulator APIs, but also
your own APIs.
They also add static type safety to your project. Which basically means the IDE will catch (and highlight) common mistakes in your code in real-time as you write your code.
Unfortunately, there’s presently also only one IDE that supports these annotations, and it’s not Atom.
If you wish to use these type annotations (and they are optional) then you must install Luanalysis, which is a Lua plugin for Jetbrains IDEA, both of which are also free.
Therefore, if you want to use type annotations (which are great), you must code in Luanalysis, but also have Atom so that you can push your game to Tabletop Simulator. Not ideal, however for now, this is the only solution.
-
Install Atom.
-
Install the Tabletop Simulator Atom plugin.
-
(Optional) Install IntelliJ IDEA Community (Free) Edition.
-
(Optional) Install Luanalysis.
-
Download the
ge_tts_demo_release.zip
(not source code) from latest releases. -
Extract its contents directly into your Tabletop Simulator Atom
#include
directory, by default that’s%HOME%\Documents\Tabletop Simulator
.NOTE: By directly I mean you should end up with multiple directories extracted. If you end up with a single directory titled
ge_tts_demo_release
, open it and move its contents up one level.
-
Launch Atom.
-
Launch Tabletop Simulator.
-
Create a Single Player game in Tabletop Simulator. Dismiss the prompt when it asks you which mod to load.
-
Create a save game with this empty scene. Just call it
ge_tts_demo
. -
Now, strangely enough, TTS and Atom don’t play nice with newly created saves. So please proceed to load the save you just created.
-
Open Atom, and from the menu choose
Packages
→Tabletop Simulator
→Get Lua Scripts
, pressGet Scripts
when prompted. -
Replace the entire file contents of
Global.-1.ttslua
with just:
require('ge_tts_demo.Main')
-
From Atom’s menu choose
Packages
→Tabletop Simulator
→Save and Play
.
Ta-da!
You’re now playing world’s worst card game.
There’s no game mechanics, but you’ll note the cards are separated into two piles, "Spells" and "Instants". If you try drag a card onto the other pile, it will be rejected.
What if you try trick it? Create a deck to the side containing cards from both piles, then try drag it into the drop zone. Give it a go.
Phwoar! It is magic.
The code is heavily documented and should do a good job of explaining what is being done, and why. So please do peruse it. However, what follows is a very quick overview of the mod’s structure.
ge_tts provides a Lua API for TTS' scripting triggers/zones that provides
common functionality. For example, ge_tts includes a DropZone
, which
behaves like a customizable snap point with a customizable size area to
drop objects in.
This mod implements its own CardDropZone
, which inherits all the behavior
of a DropZone
, but has added logic to only accept cards of a certain type,
either "spell" or "instant" cards.
ge_tts has the concept of an "Instance". Unlike TTS objects, which are destroyed when entering a container, instances more closely resemble the concept of a real world game piece, and are only destroyed if you delete the object in TTS.
This mod has just one type of instance, a CardInstance
. As the name would
suggest, it represents a card. It has a reference to a TTS' object, which
may be a TTS card object or a deck object, if the card is presently held
within a deck.
ge_tts Instance
class also provides some convenience methods that help you
interact with TTS objects. reject()
is one such method that is used within
this mod. reject()
knows how to return an object to wherever it previously
came from, its previous zone, or if it has never been in a zone before,
where it was picked up from.
Even if our CardInstance
refers to a card that is within a TTS deck,
reject()
will automatically pull it out of the deck if necessary, and just
reject that individual card (not the entire deck).
This demo mod has an example data model demonstrating how you might represent a card library. If you prefer a different approach, that’s just fine.
As mentioned, we have just two types of cards in this example "spell" cards, and "instant" cards.
As part of the mod we have a card library. There’s just 5 cards in the demo.
However, you could easily edit ge_tts_demo\CardInstace.ttslua
and add
additional cards to the library. If you do the mod will know what to do, and
automatically create TTS objects representing those cards.
If you installed Luanalysis, launch it, if not use Atom. In either case,
simply choose File
→ Open
and navigate to
%HOME%\Documents\Tabletop Simulator
.
So ah… How do you feel about a third IDE?
Officially, Tabletop Simulator has no support for debugging. Unofficially there’s this.