Importing from Tabletop Simulator

If you have already created your game in Tabletop Simulator and want to port it to Tabletop Playground, you can use the TTS Importer application to make the process much easier. It will quickly import objects that can be converted to Tabletop Playground. Not everything can be imported automatically though, see Limitations and Notes.

You can find TTS Importer in the Tools folder within the Tabletop Playground directory. Here’s how to find the game directory:

  1. Right click the game in your Steam Library.
  2. Go to Properties then the Local Files tab.
  3. Click Browse Local Files.

Using TTS Importer

TTS Importer can be used with Workshop items, local save games, and stored objects from TTS. It creates object templates in a Tabletop Playground package for each type of object in the TTS source file and copies the required resource files (models, images, and PDF files) to the package.

When you start TTS Importer, you first have to select a target package at the top. If you don’t have a package yet, create it in the Editor first. The new objects will be added to the package, already existing objects and resources will remain.

Next, you need to choose a source file. By default, the importer looks for a TTS folder in your Documents and shows all workshop items installed there. Simply select an item from the list and you’re ready to go! If you have configured your mod save location in TTS as “Game Data”, you can select that as the TTS save location instead. In order to import a local save game, select “Saves” instead of “Workshop” on the right. To import stored objects, you need to select the respective file directly.

Once you have selected a target package and a source file, click the Import button to start the conversion. Resource files will be loaded from your local disk if they exist (when you’ve loaded the game in TTS with mod caching disabled). If the importer can’t find files locally, it will try to download them. In the black console window, it will output status messages about the import process, for example if a file can’t be downloaded. Once the import has finished, you can open the package in the Tabletop Playground editor to find all your new game objects!

Limitations and notes

Some things can’t be imported automatically: custom asset bundles, the layout of objects on the table, and scripts have to be done manually. Custom dice can’t be converted directly, because the texture layout is different. The importer will copy the custom texture to the target package, and you can adapt it to the right layout with an image manipulation program. You can find the dice texture layouts at Dice.

Opening a large imported package for the first time can be slow, because every object needs to be loaded once in order to create the preview image in the object list. After you’ve opened the package for the first time in the editor, the preview images are cached and loading will be fast.

Colliders

A collider is a 3D model that is used in-game to determine how objects collide with each other. Each object has at least one collider. If you don’t specify one, a box that covers the whole visible object is generated automatically. In many cases, that will be enough and you don’t need to worry about colliders. But if your object shape isn’t represented well by a box, read on to find out how to work with colliders.

Creating colliders

Collider in the editor

In the editor, you can add two types of colliders: Spheres and models. Use a sphere for perfectly round objects, you only have to set the center of the sphere and its radius.

Collider models are more flexible: you can load any 3D model and a collider will be created from it. You can then set its position, rotation, and scale in the same way as for visible models. Click on the eye icon on top of the collider pane to visualize your colliders.

There are some important differences between collider models and regular visual models, though: colliders are always convex (they can’t have holes or dents), and they should not have complex geometry or performance will suffer. When you try to use a non-convex model as a collider, its convex hull will be used instead. Calculating the convex hull can take quite some time for complex models, which is another reason to only use simple geometry as colliders.

Examples for convex and concave shapes

If your object needs a collision shape that is not convex, you can combine multiple colliders to create it. As long as each single collider is concave, the collision shape of the whole object can be anything you want. You should still try to keep it as simple as possible and use as few colliders as you can get away with to keep performance high!

Table colliders

Collision for tables works differently from other objects: You can also provide your own colliders own colliders if you want, but if you don’t add any colliders you don’t get a box around the table. Instead, the actual visible geometry is used for collision, even if it is complex and has holes and dents! This works because tables never move in the game.

Creating a card deck

If you want to add cards to your game, you first need a picture of each card you want to add, arranged in a grid in one image file. You may have a number of image files, each containing a single card. You can use the free Image Grid software to arrange the pictures in a grid – simply start the program, drag your files onto the window, and press Save. If Image Grid can’t arrange your image in a regular grid, make sure that each file has the same dimensions.

For this tutorial, let’s say you want to create a card deck from a bunch of Phylo cards. Download and extract the zip archive with an image containing a grid of cards and a card back image here.

Now go to the editor, create a new package, and in the new package create a new object template of the type “Card / Token / Tile”. The template editor will open, showing a card with a big red X indicating that it does not have a valid image selected – let’s change that.

Click on the Front Image button on the upper right, then Browse, and select the “PhyloCards.png” from the archive you downloaded. You’ll see the card change, but it will show the whole image with all card pictures. You have to specify how many card pictures are in the grid, which you can do using the “Cards in Image” fields. Enter 3 for horizontal and 4 for vertical.

Now you should see the card clearly showing the first card image, but it’s just a single card and not a stack yet. To add the remaining cards, press the “+” button next to “Card 1/1” eleven times. Each card in the stack has its own index that determines what part of the image grid is used. You can have multiple cards with the same index, so you don’t have to repeat a card picture in your image in order to use it multiple times in the same stack. When you add a card, the current index is automatically increased by one, so pressing “+” as long as there are more pictures available produces a deck in which each card occurs once. You can click on cards in the list and change their image using the “Image Index” slider below. Try creating a deck that includes some of the cards two or three times!

Finally, we can add a separate card back. Currently, your deck uses the first of the card pictures as the back image. Note that the standard 3D view shows you the back of the card stack (that’s why you see the whale). In the upper right, select “Separate file” as Back Image Type. A Back Image button will appear below, click it and select the “PhyloBack.png” file from the archive.

That’s it, you’ve created a new card deck! Give your new template a name (in the upper left), save it, and go back. You will now see your card deck in the list. When you create games with a lot of cards, you may not be able to fit all of them on one image. In this case, you can just create multiple images and make a card stack for each of them. In the game or when creating a game state, you can combine cards from multiple stacks with the same dimensions!

Creating a simple board game

This tutorial will walk you through the process of creating a variant of Pachisi with in Tabletop Playground. When creating a new game, we first have to think about what kind of objects are used when playing the game. Pachisi involves a game board and some game pieces for each player. Traditionally, players use sea shells for randomness, but we’ll just stick to dice here for simplicity. You can download a zip file containing the image and model used in this tutorial here.

First, we’ll create the game board. We need an image of the board, so unzip the tutorial archive. Now start the Editor and create a new package. In your new package, create a new object template and choose Board. A dialog will pop up that asks you to select an image. Click on the button and choose the image from the archive, then press Ok. You will now see your new board in the object template editor.

Adding a snap point grid

You already have a Pachisi board now, but you can add some snap points to make playing the game more convenient. In the header of the snap point pane on the right, there are different ways to create snap points. By clicking +, you can create a single new snap point and then edit its properties below. By clicking on the arrow button, you can activate placing snap points by clicking on the board with your mouse. Or you can add a whole grid of snap points at once by clicking the grid button. Try adding snap points to each field on the board!

When you’re done, click on Save and the go back to the object template selection. You’ll see that your new Pachisi board has appeared in the list. Now we need game pieces. You could use the included pawns or meeples, but here we’ll import a new 3D model.

Create another object template with the type Generic. You’ll see an empty template editor. In the model pane on the left, click on the model, then Browse, and choose the model file from the archive. That’s all you need to do in order to create a new game object from a model file.

By default, game objects get a collider box around the whole object. If you want a more precise collision, you can add colliders in the pane on the right. For this object, you can add a new collider by pressing +. Then click the model button and choose the same file from the archive again that you chose as visible model. Colliders models have to be convex: they can’t have any holes or dents. If you try to use a concave collider, its convex hull will be used instead. Complex collider models can hurt performance in-game, so you should only use them if you really need precise collisions and fall back to simpler colliders or the default box where possible.

Adding a model collider

Now give your new object a name in the object properties on the left, save, and go back. The final element we need are dice, but Tabletop Playground already comes with suitable dice included, so we don’t need to create another object template. Instead, we can go ahead and create a starting state for our Pachisi game.

Click on “Preview package or create start states”, then “Start with empty table”. Select a table you like and click start. You are now in-game with an empty table and your new package is already activated. Open the object library from the context menu and create a Pachisi board, 16 game pieces, and a D6 (from the dice package). Place the game pieces on the triangles on the center of the board and color them accordingly. Finally, save the state to your new package: click Save State in the context menu and selecting your package in the destination list. Then enter a name for your new state and click Save.

Note that you have to be in the editor, using the “Preview package or create start states” button in order to save states to your package. When you start a regular game from the main menu, you can save to your local states, but those won’t be available to others who download your package!

That’s it, you have created a new board game with a custom board, a new 3D model, and a starting state! You can now quickly play a game of Pachisi by selecting your package and state when starting a new game.

Object templates

An object template specifies an object that can be used in games. Each template has a name, an object type (for example a generic object, a card, or even a table), and various properties that depend on its type. The object library shows available object templates and is used to create objects from templates while playing.

You can use the Editor to create object templates in your packages for each kind of object that you want. Object templates are stored as JSON files in the package folder.

Each object template can be identified by a GUID. When you create objects and store them in a game state, they refer to the object template by its GUID. So when you later change the object template, all objects in game states are automatically updated. Properties that you can change during the game (in the Properties and Appearance windows in game, int the Object Properties panel in the editor) are stored for each object separately and do not get updated when you change the template.

If you want to create object templates without using the editor, you can find the format definition of the JSON files for each object types here: https://github.com/plasticity-studios/tabletop-playground-schemas