Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/benjamin-dobell/ge_tts_demo

ge_tts (Tabletop Simulator) demonstration project.
https://github.com/benjamin-dobell/ge_tts_demo

Last synced: 4 months ago
JSON representation

ge_tts (Tabletop Simulator) demonstration project.

Awesome Lists containing this project

README 

          
= ge_tts Demo Project

:toc:

ifndef::env-github[:icons: font]

ifdef::env-github[]

:tip-caption: :bulb:

:note-caption: :information_source:

:important-caption: :heavy_exclamation_mark:

:caution-caption: :fire:

:warning-caption: :warning:

endif::[]



:toc-placement!:



This is an example demonstrating some basic features of

https://github.com/Benjamin-Dobell/ge_tts[ge_tts], a library for

developing Tabletop Simulator mods.



toc::[]



== Running the Demo



To run this demo, you need a TTS IDE that supports `require()`. It's

suggested you use the official

https://github.com/Berserk-Games/atom-tabletopsimulator-lua[Tabletop

Simulator Atom plugin] to run this mod.



[TIP]

====

Alternatively, you may use

https://github.com/rolandostar/tabletopsimulator-lua-vscode[@rolandostar's

Visual Studio Code plugin].

====



=== Type Annotations



Having said the above…



Through-out this demo there are many comments that look like

`---@shape `, `---@field ` `--[[---@type ]]` 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

https://github.com/Benjamin-Dobell/IntelliJ-Luanalysis[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.



=== Where’s the Steam Workshop link?



There isn’t one.



This demo is _all code_. Read on.



=== Setup



[arabic]

. Install https://atom.io/[Atom].

. Install the

https://github.com/Berserk-Games/atom-tabletopsimulator-lua/wiki/Installation#basic-installation[Tabletop

Simulator Atom plugin].

. (Optional) Install https://www.jetbrains.com/idea/download[IntelliJ

IDEA *Community* (Free) Edition].

. (Optional) Install

https://plugins.jetbrains.com/plugin/14698-luanalysis[Luanalysis].

. Download the `ge_tts_demo_release.zip` (*not source code*) from

https://github.com/Benjamin-Dobell/ge_tts_demo/releases[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.



=== Getting Started



[arabic]

. 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`, press `Get Scripts` when prompted.

. Replace the entire file contents of `Global.-1.ttslua` with just:



[source,lua]

----

require('ge_tts_demo.Main')

----



[arabic, start=8]

. 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.



== Mod Overview



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.



=== Mod Entry-point (Main)



The main Lua file is `ge_tts_demo\Main.ttslua`, and is a good place to

start.



=== Zones



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.



=== Instances



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).



=== Cards



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.



==== Card Types



As mentioned, we have just two types of cards in this example "spell" cards,

and "instant" cards.



==== Card Library



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.



==== Card Utilities



The card utilities just exposes the one method, which creates a TTS "object

state" (or "object data") corresponding with a card from our card library.

An object state is what TTS uses to spawn a TTS object i.e. this mod

includes all the code necessary to dynamically spawn cards.



== Editing / Learning



If you installed Luanalysis, launch it, if not use Atom. In either case,

simply choose `File` -> `Open` and navigate to

`%HOME%\Documents\Tabletop Simulator`.



== Debugging



_So ah... How do you feel about a third IDE?_



Officially, Tabletop Simulator has no support for debugging. Unofficially

there's https://github.com/tts-community/moonsharp[this].