This guide assumes that you already know the basics of modding from https://kb.tabletopsimulator.com.

The scripting sections will require knowledge and reference from https://api.tabletopsimulator.com

You will see this mentioned a lot in this guide. Explanations for each will be below, but just bear in mind universally that every player-intractable game component (that is, anything that can be picked up), should be entirely (not just the position of said object) at a position of y=1 or higher.

A lot of mods on the workshop, especially those that use tables from the workshop, do not follow this and it causes many strange behaviours in their mod.

• Objects -> Tables -> None

This will remove the in-built table.

The in-built tables have quirky behaviour, so to get the same control you have as every other object, it's best to remove it. Not only are you limited by shape, scale and behaviour of that table, altering the table at a later date (even to None) will force the matching hand layout/colours, undoing any changes you may have made to these.

• Objects -> Components -> Custom -> Custom Model/Tile/AssetBundle
  -or-
  
• Objects -> Components -> Blocks -> Red Square
  -or-
  
• Game -> Workshop/Saves -> Options (three . in corner of thumbnail) -> Search -> drag desired object

Regardless of what type of object you import, you will be importing 1 or more objects. These will initially fall through the world since you removed the table, but you can lock them after importing by hovering and pressing L.

Colour tint the object (if required). I use a standard TTS "Red Square" object on most of my mods, tinted to a neutral colour.


Use the Gizmo Tool (F8) to finely rotate, scale and position your new object to be your play surface.

Important: ensure the top of your play surface is at y=1 or higher, as lower heights will cause a myriad of unexpected behaviours in TTS. You can test this by placing a single card on the surface and using the Gizmo Tool to check its position.

A workshop mod showing the unexpected behaviour of snap points at a height below y=1:
https://gtm.steamproxy.vip/sharedfiles/filedetails/?id=2665170114


Add the following script to your play surface (and any other background objects):


I only set .gizmo_selectable to false when I have finished positioning my surface, else I would not be able to use the Gizmo Tool to be able to position it. If I need to go back later and make changes, I will comment out these lines if I require the functionality back temporarily.

Using an identifier and an onObjectSpawn script to control the behaviour of multiple objects without duplicating scripts:
https://gtm.steamproxy.vip/sharedfiles/filedetails/?id=3015241394

When setting Table to None, this resets the Hand to their default positions and colors. Now we have our table set up we can position our hands. Should we ever need to modify our play surface, this will not reset our hands as long as Table remains set to None.

You can view the basics of creating Hand Zones here: https://kb.tabletopsimulator.com/game-tools/zone-tools/#hand-zone


Hand Zones have some behaviours that are not explained in the Knowledge Base, so I will cover these here:


The scale of a Hand Zone affects the following:

• Whether objects can fit into the Hand Zone. On the y axis, this is significantly smaller than what is shown in-game and indicated by the Gizmo Tool. Typically for a game where players can hold 10 standard scaled cards I would scale my Hand Zones to y=5 and z=5.
  
  The main issue with the default y and z scale of your Hand Zones is objects entering player hands when not desired. This is particularly true in a lot of mods where the hand zone is immediately below the player's play board, but hasn't been scaled with the Gizmo Tool. In trying to play a card in your player zone you will often instead clip your card into your hand zone.
  
  Because of this, I encourage you to experiment with your Hand Zones to figure out a suitable scale and position. Leaving a gap between any play area for hand objects and the Hand Zone itself is highly recommended.
  
  
• How many objects can fit in the Hand Zone. As more objects are added to a Hand Zone they layer over each other. Eventually the part of TTS that regulates this breaks and either starts glitching out (picking up and dropping an object repeatedly), or just drops the object from the hand entirely
  
  Again, experiment with expected hand contents in your mod to decide on a suitable Y scale that allows the hands to hold as many objects as needed, without being so large it picks up objects unexpectedly

The rotation of a Hand Zone affects the following:

• Which rotation objects are given when entering the hand zone
  
  
• The rotation of the player's name (projected below the hand zone)
  
  
• The player's camera rotation when the player presses the space bar to reset their camera, if they have no Camera #0 set.

The position of a Hand Zone affects the following:

• In combination with the scale, this affects where the Hand Zone will pck up objects from. Try to make your Hand Zone's bottom collider slightly embedded in your play surface on the y axis. This will ensure that players with a lift height of 0 will have no issues in putting their cards in their Hand Zone
  
  
• The player's camera position when the player presses the space bar to reset their camera, if they have no Camera #0 set
  
  
• When the Hand Zone is loaded: If there are any locked objects with a collider below the hand, the player's name will be positioned slightly above the topmost that object. If none are found, the player's name is set at y=1 below the Hand Zone's position
  
  
• Hand Zones placed below y=1 will have strange behaviours

Make a save of your Mod. You've probably done a fair amount of work now. Remember to save often and save into multiple files so you have backups.

Set your Background to Museum. This also modifies your Lighting settings to the default that comes with the Museum background.

You might not want to use the Museum background, but I find the Lighting settings that come with it to be the very suitable for every mod I've made, and I rarely tweak this.

Feel free to play around with the Background and Lighting settings as you see fit, but you'll want to have your objects imported first so you can see how they look under different lighting.

Just bear in mind that changing the Background to any non-custom background will also load the Lighting settings that come with that (Similar to how setting a Table will also alter Hands to go with it).

Now you have the play surface and the hands all sorted out, you can import your objects. You may already have imported some to test your Hand Zones, but you can now do so in earnest.

The rest of this guide only covers mods where you will be scripting.

Unless your scripts are only a few lines long, I heavily recommend you use an external editor.

Atom is no longer updated, but neither is TTS. Atom works just fine with TTS, though the instructions on the Knowledge Base are incorrect, follow these instructions instead:

https://github.com/Berserk-Games/atom-tabletopsimulator-lua/releases/tag/13.2.0

Use the extension rolandostar.tabletopsimulator-lua for use with VSCode, with the following bugfix if you are using current versions of VSCode:

1. open the following file for editing: %USERPROFILE%.vscode\extensions\rolandostar.tabletopsimulator-lua-1.1.3\dist\extension.js
   
2. on line 9406 change "node_modules.asar" to "node_modules"
   
3. save and close the file

source: https://github.com/rolandostar/tabletopsimulator-lua-vscode/issues/48

Better extensions may appear in the future.

Other editors have compatibility with TTS, but I have not used them. I encourage you to ask about them in the #scriptng channel of the official TTS Discord server: https://discord.com/invite/tabletopsimulator