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.

UI Switchers

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.

Switchers are a type of container widget that allows switching between two different UIs.

For an example of how this works, let’s set up a Switcher, then add a Text Widget to it. Here I’ve written the text “State A” and applied a colored background to it:

I then click “Add to Switcher” and add a second Text object, Text B. I give it a red background. But as you can see it doesn’t show up:

That’s because the Switcher is still set to show Text A. If we click on the Switcher in Hierarchy, we can see that its Active Widget is set to 0 (the first Widget beneath it).

If we change that to “1,” we’ll switch to Text B.

If you add Panels or Canvases under the Switcher, then toggling the switcher will toggle between everything within those panels or canvases.

For a practical example, this Health Bar has a switcher to toggle between Text widgets showing the current and max health, to Input fields the user can use to manually input those numbers. The “Active Widget” number in the Edit Switcher refers to the Text Shown Panel and the Edit Panel – so that one toggle will also toggle everything within those panels

Scripting Your Switcher

To actually accomplish this switch, you’ll need to apply a script to the widget, using the setActiveIndex method. Here’s an example of what that might look like:

For details, see Adding Scripts to UI.

Progress Bar

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 Progress Bar widget is useful for creating health bars, progress towards goals, and so on.

The “Progress” control determines how full the bar is, where 0.0 is empty, and 1.0 is full; in the example image above, Progress is set to 0.25 and the Bar Color is set to blue, so 25% of the bar is blue. Standard text controls are provided to add text over the bar.

By default, the size of the bar will be determined by its text. If you’d like your bar to extend past the text, you will likely want to add a layout box and set an “Override Width” value, as shown in the screenshot above. (See: Borders and Layout Boxes).

Scripting a Progress Bar

To set the value of your progress bar, you’ll want to use the .setProgress() method, specifying a value between 0 and 1 within the parentheses, as shown in this simple script example:

For another example, you can take a look at the Health Bar in the UI Library.

For details on how to script UI, see Adding Scripts to UI.

Checkbox

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.

Checkbox Widgets let you add simple binary options to your UI.

The Widget consists of a box and some accompanying text. In the options, you’ll see the standard font, color, and size options for the text. The size of the box is not directly configurable, but it will automatically grow or shrink at certain text sizes.

The “Start Checked” option determines if this box is checked or not by default when the UI is instantiated.

The controls below that allow you to change the color of the box in its unchecked (Regular) and checked states, as well as when it is moused over in each of those situations.

Scripting a Checkbox

To check whether a checkbox is checked in a script, use the “.isChecked,” as shown in the following example:

For more info, see Adding Scripts to UI.

Buttons

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.

At the top of the Button panel, you’ll see controls for your button’s type and contents. You can choose between Text, which will give you the same options as seen in text above:

Or Image, which will let you make icon-based buttons:

Below this, you’ll find controls for the button’s regular, highlighted, and pressed states:

For each, you can define either or both of a color and a texture (image). These determine what will be shown behind the button contents defined above. If you choose both a Color and a Texture, the Color will tint the texture. Note that you can use an Image backer even if you’re using a Text button type.

Tips and Tricks for Using Texture Backers

Using images for your button backgrounds can be a powerful tool to make buttons that look great, but you’ll want to be aware of a few things:

  • If you want your backer image to display at a specific size, the easiest way to do that is to add a Layout Box on the button. (See Borders and Layout Boxes)
  • There’s a Texture entry for each state to give you maximum control over the appearance of your button; often you can produce really nice-looking rollover states this way. However, if you only have one button image, and wish to rely on color tinting to indicate its Highlighted and Pressed states, you’ll need to input your image into all three fields; otherwise it’ll revert to a simple color backer on rollover.
  • If you’ve created a button image that stands alone (ie, that has the text and/or image you want to display baked into the image), you’ll want to make the Button type Text, and then just leave the text field blank.

Example

In Photoshop, I’ve created a Setup button image and a Setup Highlighted rollover state. I rendered the text in Photoshop so I could get the specific effects on it I was looking for.

In TTP, I set my Button Type to “Text” and clear the Text field, then import my base button in the Image field for “Regular.” At first, my button looks scrunched and weird (it’s in the top-right of the image below), because it’s defining its size based on the empty Text field.

To fix this, we add a Layout box to the button, and set its width and height to the image’s native dimensions (which you can see me verifying via the Windows “Properties” dialogue in this screenshot). Voila, our button looks correct:

Now we can add our second image in the “Highlighted” field, and voila: On mouseover, our button switches to the Highlight image, thus appearing to light up:

We’re not done though, because if we don’t edit the “Pressed” field, then when someone clicks the button it’ll look like this:

So we’ll just add our base button texture in there again. If we want, we can even apply a color tint to it to change it up a little:

Scripting Your Button

To make your button do something, you’ll need to add a script to it. Below is a simple example script to get you started. For details see Adding Scripts to UIs.

Older Posts