Tools

This post refers to the new-and-improved beta version of Tabletop Playground, and may describe functionality or UX not present in the legacy version. For information about the beta, click here.

The “Tools” package in Object Library contains both functional examples of UI templates, and 3D objects that put them to work. In multiplayer games you’ll only see the objects, but in editor you’ll be able to see both (the objects will be the ones shown at an angle to display their depth).

Working with the UI Templates

You can attach the templates found in the Tools library to objects via the UI tab in Properties, or to the table or screen by choosing “Global UI” in Session settings (see User Interface Basics for details). If the UI has any special options associated with it, you’ll be able to adjust them from the same dialog.

If you’d like to tinker with the templates, you can make copies of them in your package, just as you would with an object template. This will also copy the associated script into your package’s script folder, should you want to get a look at how it works or make adjustments to the functionality.

Even if you don’t know how to script, you can customize how the templates look using the in-game editor. Just be careful about renaming or deleting widgets or options, as the scripts often key off these, and may cease functioning if they can’t find them. Below, we’ve tried to outline the essential widgets for each script’s functionality, but when in doubt, it’s safest to edit the properties of widgets without renaming or deleting them. Adding new widgets is also usually safe.

Notes on Each Tool

Calculator

  • Supports scientific notation
  • If editing the calculator template, do not change the names of any of the widgets or delete any of the widgets; all are referenced in the script.

Collapsible Note

The collapsible note is intended as a way of including rules reminders and other info in your mods that you don’t need to be visible at all times.

  • Clicking the clipboard will open or collapse the note.
  • Clicking the button at the bottom will either switch to edit mode, allowing the user to modify the note’s text, or save the current text and close edit mode.
  • Has a “Starts Open” option, enabled by default.
  • The template’s scripted functionality relies on the following widgets by name: NoteCanvas, Switcher, Text, InputField, HeaderText, HeaderInputField, ShowButton, EditButton, DoneButton

Counter & Flexible Counter

The Tools package contains two new counters, as alternatives to the multi-state object versions found in the General package (“Counter 10” and “Counter 100”). Compared to the older counters, they offer more intuitive controls, the ability to handle negative numbers, and some customization options, but do not respond to hotkeys like the old counters.

  • Users can enter numbers directly into the counters by clicking the display
  • The counters are configured to handle values between 99 and -99. (Users can enter larger numbers than this in the field, but the buttons will not count up or down past this point.)
  • The Flexible Counter offers an “Increment” option, which controls how much the outer buttons add or subtract from the total.
  • The basic Counter’s scripted functionality relies on the following widgets by name: MinusButton, PlusButton, ResetButton, InputField
  • The Flexible Counter’s scripted functionality relies on the following widgets by name: Input Field, PlusButton1, PlusButton2, MinusButton1, MinusButton2

Health Bar

  • The health bar is only available as a UI Template; it is intended to be attached to 3D objects.
  • Hitting the Edit button on the bar will allow you to directly change the current and max health values.
  • For a traditional health bar presentation, you may want to set the bar’s Presentation Style to “View Aligned” or “Screen” under Advanced Options. This will cause it to always face the camera regardless of the angle the attached object is being viewed from.
  • The bar features the following options in settings:
    • Allow Overheal — If disabled, the plus button will not increase current health above maximum health (however, it can still be set above maximum manually).
    • Allow Negatives Values — If disabled, the minus button will not drop the bar below zero (however, it can still be set below 0 manually.
    • Starting Value and Max Value — Set the starting and max value for the bar. Note that once you’ve modified the values on the bar, the bar will cease responding to these options. These options are thus primarily useful when attaching the bar to something at the template level (for example if you want to create a mini that always spawns with a certain amount of health).
  • The bar’s script relies on the following widgets by name: ProgressBar, MinusButton, PlusButton, EditSwitcher, HealthText, EditButton, InputCurrent, InputMax, DoneButton.

Notecard

The notecard is a simpler alternative to the Collapsible Note. It features no scripted functionality, just a couple of Input Fields. Note that there are two separate UI Templates for the notecard; one that is used on the physical object, an another that is better optimized for use as Global UI.

Stopwatch

  • Displays minutes, seconds, and tenths of a second.
  • If the minute count ever exceeds 100, it will reset to 0.
  • Relies on the following widgets by name: CentiSeconds, Seconds, Minutes, StartButton, ResetButton

Tablet

The Tablet is a 3D object allowing users to visit web pages within TTP. It uses scripted UI rather than a UI template, so it cannot be directly edited.

Timer

  • Displays minutes and seconds, both capped at 2 digits.
  • While the timer is not running, it shows input fields to set the desired duration. These convert to non-editable text fields while the counter is running.
  • When the timer elapses, the background will flash red.
    • This tint color is applied to the MainPanel’s Border via script.
  • Relies on the following widgets by name to function: MinutesInput, MinutesText, SecondsInput, SecondsText, StartButton, ResetButton, MainPanel.

Worker Placement Base

When you’re making a worker placement game, it’s common to want a script that brings players’ workers back to them at the end of the round. The Worker Placement Base allows you to quickly implement this without any scripting know-how.

The basics are simple: Give each player a base, and place their starting workers on its circular snap points. Whenever the player hits “Recall,” it will return their workers from wherever they are on the table to their base.

Some additional notes:

  • You can use any objects you like as workers. When you snap an object to the base, the base registers it as one of its workers. When you hit recall, the base returns each thing it’s registered to one of its snap points.
    • This is why we advise only placing a player’s starting workers on the base; if a player acquires more workers later in the game, they can place them on the base to register them then.
  • It is possible to associate the same worker with more than one base (though you’ll usually want to avoid this). When this happens, whenever recall is hit on either base, the worker will return there.
  • To clear all workers associated with a base, click the ? button in the base’s upper right corner to open its help dialogue, then click the “Clear Workers” button.
  • It isn’t necessary to assign a base to a player slot, but doing so will change the color of its slots to match.
  • The scripts for the base are attached to the UI templates for its Recall Button and Info Dialogue. You could easily make a custom base by attaching those templates to your own 3D object, along with snap points for the workers.
    • Your custom base can have as many or few snap points as you wish; the Recall button’s script should adapt accordingly.
  • When modifying the Recall button itself, do not rename its lone widget. The info button meanwhile relies on the widgets DisplayPanel, WorkerInfoButton, ShowButton, and ClearButton by name.

Switcher Object

Switchers are different from other object types: they don’t have their own appearance and instead always look like the currently active switchable object. You don’t create switchable objects in the editor, but in-game: in the context menu for multiple selected objects, click “Create Switcher”. The selected objects will be combined into one switcher object.

The order of states in the new switcher is determined by the order in which you select the object to combine, and which object you right click to create the switcher. If you care about the order of states in the switcher, the easiest way to ensure the order of selected objects is to hold Ctrl and click the objects one by one to add them to the selection. Then make sure that you right click the object which should become the first state to bring up the context menu.

Switcher objects have custom actions to switch to the next or previous state, and to pick a random state. Each state corresponds to one of the objects that the switcher was created with. Finally, there’s the “Remove Switcher” option which will just keep the current state object and remove the switcher along with all other states. If the current state object doesn’t define a primary or secondary action, the respective hotkeys can be used to switch to the next or previous state object.

You can still modify each state object (for example by changing their color) and the modified state will remain when you switch ot another state and back. You can do most actions with objects that are part of a switcher that you could do with regular objects, with a few exceptions: switcher objects can’t become parts of new switchers, and switchable cards can’t go into other card stacks (but other cards can be added to the switchable card stack). Switchable cards in card holders can’t change their state while in the holder.

Multistate objects

Multistate objects are an object type in Tabletop Playground. They work just like generic objects, but have a number of states that can be cycled and alter their appearance. You can switch to the next state by pressing the object action button, or switch to the previous state by pressing the secondary action button.

Multistate objects have two custom context actions:
Next state: Switch the object to the next state.
Previous state: Switch the object to the previous state.

Multistate objects have a custom property:
State: The current state of the object.

Containers

Containers are an object type in Tabletop Playground. You can put other objects into a container by dropping them onto it. You can take objects out of a container by clicking and quickly dragging off the container. If you want to grab a container, click and hold until you pick it up.

The type of a container determines how objects are taken out. There are four variants:
Random: Take out one of the contained objects at random.
Infinite Random: Take out a random object, but keep a copy of it in the container.
Stack: Take the first inserted object out last.
Queue: Take the first inserted object out first.
Infinite queue: Take the first inserted object out first, but keep a copy and move it to the end of the queue.

Containers have two custom context actions:
Empty: Removes (and deletes) all objects from the container.
Container Explorer: Open a new window that allows you to inspect the container’s contents

Containers have custom properties:
Container Type: The type of the container.
Take Rotation: Determines how objects taken from the container should get rotated. Possible values are “Default Rotation” to get objects in their standard orientation, “Container Rotation” to rotate them like the container, and “Flipped” to get objects in their standard orientation but flipped.
Lazy Load: Determine whether objects in the container should only be loaded once they are taken out or viewed in the container explorer. Loading an object may cause a hitch, so in general it is preferrable to leave this off. It can help when you have a large game and containers that include objects which are often not needed during a game.
Max Items: The maximum number of items this container can hold. If there already more items than the maximum, they won’t be removed from the container.
Owner: Allows you to define an owning player for the container. Only the owning player and their team can explore the content of the container. If no player owns the container, all players can use the container explorer.

Tables

Tables are an object type in Tabletop Playground. There is never more than one table in every game. Tables cannot be moved or interacted with by players in any way, but scripts have access to table objects. You can select a table when you start a new game. If you load an existing game state, it determines which table is used.

Older Posts