Packages

All game content in Tabletop Playground is organized in packages. A package is a collection of Object Templates, Models, Textures, Scripts, and Game States. You can create new packages using the editor and upload them to mod.io.

Playing with packages

When starting a new game, you will usually choose a saved state or a table from a package. This package then becomes active for your game, and all players wanting to join your game need to have the package installed as well. Some packages are included with Tabletop Playground and always active, for example the Dice and Cards packages.

In the game, you can only create objects and load states from active packages. The host can add packages to the active list from the session options or object library if all players have the additional packages installed.

When selecting a game in the server browser, the active packages are displayed. For packages that you don’t have, a button allows you to download them immediately.

In order to get new packages, head over to mod.io and log in with your Steam account. You can then subscribe to any available package. Subscribed packages will be downloaded when you start the game. You will also automatically get updates from packages that you have subscribed to.

Creating packages

When you use the editor, you will always work on a package. If you want to create a new game, you first create a package for it with a suitable name. A new folder will be created in you Tabletop Playground directory (under PersistentDownloadDir). All content for the package will be stored within that folder. For example, when you select a texture for an object in the editor, the texture file gets copied into the Textures folder in the package directory.

Instead of creating a new package from scratch, you can also choose to start by duplicating an existing package. In that case, all content from the source package will get copied to your new package. All object templates will get a new GUID in your new package, and the game states in the copied package will be updated accordingly. But local states or states in other packages will continue to reference the objects from the original package, so you don’t have to worry about breaking anything when working on a duplicated package. If the source package includes scripts that reference template GUIDs from the package in the code, you need to update the copied scripts so they reference templates in the new package instead.

Uploading packages

When you’re ready to share your creation with the world, you can upload the package to mod.io. Just choose a representative image, Tabletop Playground will take care of the rest. After the upload, you can go to the package page and provide additional information such as a description, screenshots, and categories.

You can also set the visibility of the package to hidden if you don’t want people to see it on the mod.io page. Private packages can still be downloaded in-game when selecting a server that uses the package in the server browser. Finally, updating a package works in the same way as the initial upload.

Note that you don’t need to subscribe to your own packages on the computer where you edit them. If you do, the game will find the same package twice and only load the local version that you uploaded.

Folder layout

Each package is stored in a folder. Packages you create in the editor are store in your game folder under TabletopPlayground/PersistentDownloadDir. Packages downloaded from mod.io are in TabletopPlayground/PersistentDownloadDir/.modio/mods.

The main folder of a package contains a manifest.json, the package thumbnail image, a JSON file for each object template in the package, and a few subfolders. The manifest.json contains some information about the package, such as its name and a unique ID. If you want to copy a package, you need to use the editor functionality instead of just copying the folder so that the copied package and its objects get assigned new IDs.

The subfolders contain the resource files used by the package. When you select a resource file from the file system in the editor (for example when you add a texture from your desktop), the files get copied to the appropriate folder:

• Models: All geometry files, both for visual models and for colliders.
• Textures: Any kind of image files, used for regular textures, normal maps, and extra maps.
• Scripts: The script files used in the package. Also contains dependencies installed with npm.
• Thumbnails: Cached thumbnails for every object. The thumbnails are generated and updated automatically and are used to load the object library more quickly.

Recovering your package from mod.io

If you have uploaded a package to mod.io but you have lost your original version or you moved to a new computer and you want to edit your package again, do not copy the package in the editor. That would effectively create a new package, and uploading would not update your old package on mod.io. Instead, download the latest zip file from the mod.io page for your package (no need to subscribe), and unzip it into a new folder in the following location:

• Windows: Right click the game in Steam, select Properties and then Local Files and Browse… From the directory that opens, go to TabletopPlayground\Packages
• Mac: Open the finder and select “Go to Folder…” in the “Go” menu. Enter ~/Library/Application Support/Epic/TabletopPlayground
• Linux: ~/.config/Epic/TabletopPlayground/Packages

Note that you may need to unzip to a different directory if you change the package location in the in-game settings under Game->Package Location. After you unzipped the package into a new directory, you will be able to edit and upload it again.