Dynamic Token Rings

Overview

This article is intended to provide guidance to content creators and developers who would like to ensure that tokens that they create are both compatible with the Dynamic Token feature, and also compatible with other products that make use of it.

Understanding and Using Dynamic Token Rings

The Dynamic Token Ring feature allows the appearance of tokens to be modified in real time, instead of being loaded as static assets that do not change. The main benefit of this is allowing filters or shaders to be applied intelligently to specific elements of the ring or artwork, when triggered by in-game events as defined by systems or modules. For example, the token could display a simple animated effect on a creature's subject texture when the creature takes damage, or the ring could glow when the creature is targeted.

By relying on the Dynamic Token Ring feature, content creators can design their assets in a way that will function with shaders and effects from any system defined by any system or module, without the need to define dependencies on third-party Add-on Modules. It also increases the value of the tokens created with it, as they become more useful even outside of the projects they were originally designed for. For example, if a user installed an adventure module that contained a specific token ring that visually reflected the aesthetics of that adventure, they would be able to enable it as the “default” ring for their world, and see it applied automatically to all of their tokens.

Anatomy of a Dynamic Token

In simple terms, a Dynamic Token is composed from the same elements as a 'static' token: a Subject, a Ring, and a Background. Just like a traditional token, these layers are combined to form a single image.

Where they differ is that, while “static” token layers are combined when the file is saved, a “dynamic” token layers are saved separately, and the textures are combined only when the token is rendered within Foundry VTT.

Foundry VTT includes a default Ring and Background asset which will be applied if no ring texture is supplied in the settings menu, and other styles may be provided in the future. Additionally, a module or system can also register their own assets, allowing a custom ring to be applied to all tokens regardless of their source. Changing among available rings can be done from the Game Settings menu.

Dynamic Token Ring Configuration

Using a Dynamic Token Ring

Prototype Token Settings

As with other settings for Tokens, configuration for the Dynamic Token Ring is handled from within an Actor's Prototype Token configuration.

To activate the Dynamic Token Ring, simply check "Ring Enabled". If you have entered a file path in the Subject Texture, the dynamic ring will render using that asset. If you have not, it will assume the provided Token Asset should be rendered instead.

This menu also allows some basic modifications to be made on a per-actor basis, such as tinting the ring or background textures. More advanced functionality, such as interactions with game rules, can also be added at a system level.

Ring Enabled

A simple toggle for whether this token uses the Dynamic Token Ring feature or not.

Ring Color

A color value provided as a hex code. When this is configured, it will overlay that color on the ring texture.

Background Color

A color value provided as a hex code. When this is configured, it will overlay that color on the background texture.

Subject Texture

The file path to the location of the texture that should be used to depict the actor. This texture should be saved with no ring or background as part of its image file.

Subject Scale Correction

In some cases, Overscaled tokens (such as when a token is intended to be unconstrained by the bonds of the grid) may require correction of their scale to allow them to line up with the provided ring. This slider allows for adjusting that scale.

Ring Effects

A simple toggle which applies some example effects. Toggling these options can provide a specific visual effect, or be used by developers and creators to test how the effects provided by systems and modules will look with their provided tokens.

Creating Dynamic Token Subject Artwork

If you're familiar with the token creation process for traditional static tokens, then the process of creating a token to be compatible with the Dynamic Token Ring will be very familiar. The main difference is that rather than exporting the file as one single image asset, you must instead hide the ring and background layers before exporting the final asset.

For those who wish to adapt their token creation workflow to use dynamic tokens, a zip file containing templates (Adobe Photoshop PSD format) to aid in the creation process is available here, in three sizes.

The most important part of ensuring that a subject asset is compatible with the Dynamic Token Ring is understanding where the ring will be placed. If the Subject artwork is too large or too small, it won't line up with the ring properly.

What do I include in the Subject?

Foundry VTT renders the Subject texture above the Ring texture, with the Background rendered below both. This is important to keep in mind since it affects decisions of which elements to include in the Subject asset.

Subject artwork should assume that the ring will start ⅔ from the center of the image, with the remaining ⅓ “padding” being reserved for the ring to use, as illustrated in the examples below.

Any element of the Subject that protrudes into the (highlighted green) padding area will appear to “pop out” over the ring.

Conversely, anything that is intended to be “hidden” by the Ring must be eliminated either by a mask or by deletion. Any elements which should be rendered *over* the Ring and Background - like the drop shadow added to the Subject in our example- should also be baked into the Subject texture.

Subject Artwork Dimensions

While the canvas size for the subject asset can theoretically be of any size, we generally recommend 512px by 512px for a token intended to fill a single grid square. Texture sizes with pixel dimensions in power-of-two figures (512, 1024, etc) are preferred, as they offer minor performance advantages on most modern hardware.

For many game systems, we recommend standardizing your subject art to meet the following dimensions:

Creating Overscaled Tokens

One advantage of the way Foundry VTT renders tokens on the grid is that it allows for particular token art to extend into adjacent spaces in the grid, by increasing the Scale value in the Token Configuration. This overscaled effect is still possible with the Dynamic Token Ring, and the workflow for it is essentially identical, with the exception that you will need to adjust the Subject Scale Correction value to do so.

If you wish to create an Overscaled token, the process is fairly straightforward:

• In the image editor of your choice, increase the canvas size to double your ring template. (example: a ring intended for a 512x512 token remains centered, but the canvas size becomes 1024x1024). This inflates your 'ring padding' area as depicted in the image to the right.
• Compose your Subject artwork without making changes to the ring, using as much of the padding area as you wish. (it is always best to leave some space between your art and the edge of the canvas to allow shadow and glow effects to remain clean).
• Hide the ring and background layers.
• Save your image as a .webp or .png file. (webp at 80% lossy quality tends to provide the best ratio of visual fidelity to file size)
• Add your art to the Foundry VTT userdata folder, and set the path to the subject texture in the token configuration. Don't forget to enable the Dynamic Token Ring.
• Set your Subject Scale Correction to 2. This is because you doubled your canvas size to provide more space for the token to overlap adjacent grid spaces. If you had set it to 2048 instead of 1024, you would set this to 4 instead.
• Lastly, you may need to change the Scale (Ratio) value to ensure the scale lines up correctly to achieve your desired effect.

Including Traditional Tokens

Even when making use of the Dynamic Token Ring feature, module developers may also want their package to include “static” copies of their tokens in order to support Foundry VTT users who are on older versions or who for any other reason might choose not to use the feature. This is fully supported, and there is no major downside to doing so- the file size increase of including a second copy of assets is minimal, and the creation of “combined” tokens can easily be automated so as to not add any extra steps to the token creation process.

Designing Dynamic Rings

Foundry VTT includes a default token ring that will be used if no ring is provided. As such, content developers or users need only provide the corresponding subject texture, and the VTT will do the rest. Many projects may want to provide bespoke rings of their own as part of building a cohesive aesthetic identity for their product. This section explains the format and functionality of the Dynamic Ring assets in a little more detail.

Ring Format

New Token Rings (and their background textures) can be provided in the format of a spritesheet, with an accompanying json file that instructs the software on how to slice it into separate textures. The default ring’s spritesheet is located in Foundry’s source files at /public/canvas/tokens/rings.webp.

If a module provides its own spritesheet and accompanying .json file, there is some flexibility in terms of the appearance and thickness of the token ring, but there are some essential conventions that must be followed, particularly, that the ring be sized in a way that expects the center ⅔ of final token to be the space where the Subject Texture will be rendered.

Dimensions

As you can see, the spritesheet actually includes four versions of the default token ring, with different sizes- 256x256px, 512x512px, 1024x1024px, and 2048x2048px. This allows the software to choose the most efficient ring asset for each token based on their size, avoiding the performance hit of rendering a 2048x2048px texture for every rat or owl on the battlefield.

The size of the ring texture does not need to exactly match the size of the subject artwork that it is being applied to- for instance, a 512x512px Subject asset will work flawlessly with a 1024x1024px ring, so long as the ratios (the ⅔ discussed above) are correct. This is how we can seamlessly swap to a larger ring if a creature is temporarily enlarged by a spell or similar effect.

Ring Thickness

As previously mentioned, the middle ⅔ of the token's canvas is expected to be filled by its Subject artwork. However, the ring is not required or expected to fill the remaining ⅓ by itself. The ring can use as much or as little of that “padding” space as it desires. As this comparison image illustrates, the default token uses less than half of the available space:

All that is needed to ensure that the Subject texture still fits is the ⅔ rule that we discussed earlier. This is what allows Subject assets and Ring assets from different sources to remain compatible.

Ring Bands

One of the key features of the Dynamic Token Ring is the ability to draw solid colors, gradients, or even animations to specific areas of the ring. These areas are defined programmatically, and their sizes can be configured as part of the JSON file used when the software is supplied with a new ring.

The default ring comprises two zones. Below, they are visualized as blue and magenta bands. The magenta area (which is also magenta-coloured in the spritesheet) is where UI-level animations will be applied by Foundry VTT, while the blue area of the ring is expected to be treated as a static asset.

It is suggested that custom rings include similar re-colorable zones for displaying effects. A custom ring could be designed to ensure that its recolorable band is located in the same place as the default ring’s, or it could provide its own band sizes which are tailored to that specific ring asset. Defining custom color bands does require a small amount of custom code, and there are certain limitations on their placement- because they are defined based on their distance from the center, they must be circular, and cannot be irregularly sized or shaped.

Multiple Rings

In order to maintain acceptable performance levels, Foundry VTT will only load one ring spritesheet at a time. This means that it is not currently possible to have two different rings from different sources in use simultaneously. The currently selected ring will be used by all dynamic tokens in that world.

A module can still propose several ring styles, offering user selection for their preference via an in-application setting- but it can’t support (for example) applying a separate ring asset to players vs NPCs.

Due to the existence of the default ring, and in order to avoid conflicts with other modules, it would be best practice for modules providing custom rings to support a workflow that allows disabling their ring to allow users to choose which ring works best for them.