v1.17.00

Roll20 Token

Creating Animations

The "Token Animator" tool can be found in the Tools List ("My Settings" (cog) tab -> "Open Tools List"). From here, you can add or import animations.

Names

Animation (and scene) names should match the following regular expression: ^[_0-9a-zA-Z]+$ (underscores, numbers, and Roman letters only).

Statements

Should one wish to edit an animation directly and avoid using the GUI, the following syntax may be used.

Basic statement layout:

<command> [<start time> [<duration> [<...args>]]]

Comments can be declared using // ....

start time (S) -- The time at which the command should be run, in milis, from when the animation started.

duration (D) -- The duration over which the command should be run, relevant in cases where e.g. a move should be done smoothly over a long period.

args -- All movement values are in pixels, all rotation values are in degrees.

- -- A single dash ("-") represents an nonexistent value.

Commands

Move

Moves a token.

mv S D x y z

x -- Amount to move in the X direction.

y -- Amount to move in the Y direction.

z -- Amount to move in the Z direction; Z movement is marked by updating the "wings" status on a token.

Move Exact

Moves a token to an exact position (arguments as above).

mvx S D x y z

Copy

Duplicates a token. This can optionally trigger an animation on the newly-created child token.

cp S childAnimation

childAnimation -- Name of an animation to trigger on the child.

Rotate

Rotates a token.

rot S D degrees

degrees -- Amount to rotate.

Rotate Exact

Rotates a token to an exact angle (arguments as above).

rotx S D degrees

Flip

Flips a token.

flip S h v

h -- true if the token is to be flipped horizontally, false otherwise.

v -- true if the token is to be flipped vertically, false otherwise.

Flip Exact

Flips a token to an exact orientation (arguments as above).

flipx S h v

Scale

Scales a token.

scale S D scaleX scaleY

scaleX -- scaling factor for the token to be scaled to in the X dimension; initial scale is 1.0 (double size would be 2.0).

scaleY -- scaling factor for the token to be scaled to in the Y dimension; initial scale is 1.0 (double size would be 2.0).

Scale Exact

Scales a token to an exact scale (arguments as above).

scalex S D scaleX scaleY

Layer

Change which layer the token is on.

layer S layerName

layerName -- One of {map, token, gm, foreground, lighting, weather}

Lighting

Change the token's lighting properties.

light S D lightRadius dimStart degrees

lightRadius -- Light radius, in feet.

dimStart -- Start of dim light, in feet.

degrees -- Light angle.

Lighting Exact

Change the token's lighting properties to exact values (arguments as above).

lightx S D lightRadius dimStart degrees

Set Property

Set a property on the token.

prop S propName value

propName -- The property name. See Appendix A for a list of valid properties. Note that the gmnotes and sides properties are automatically URL-escaped to match the format Roll20 expects.

value -- The property value. This is passed to JSON.parse() (assuming a string as a fallback in case of errors). Therefore, any valid JSON can be inserted into this field. Note that this argument can include spaces.

Trigger Macro

Trigger a macro.

macro S <macro name>

Trigger Animation

Trigger an animation. Note that this can be used to cause an animation to loop, by re-triggering the same animation after a set delay.

anim S <animation name>

Running Animations

A single animation can be run via rightclick token -> "Utilities" -> "Animate". A scene can be run via rightclick canvas -> "Utilities" -> "Start Scene".

Rescuing Tokens

The animator tool includes a "Rescue Tokens" button, which opens a browser showing tokens which are deemed worthy of 'rescue.' That is, tokens that are positioned outside the map boundary or scaled extremely small/large. The tool resizes any tokens selected to standard scale, and moves them to the top-left of the map, in the GM layer (as noted in the chat when used).

Appendix A: Token Properties

The following are technically valid token properties, although may produce undesirable effects if changed. Use with caution.

Token Properties
Property	Data Type	Description
`top`
`width`
`height`
`z_index`
`imgsrc`
`rotation`
`type`
`layer`
`locked`
`flipv`
`fliph`
`anim_loop`
`anim_paused_at`
`anim_autoplay`
`name`
`gmnotes`
`controlledby`
`represents`
`bar1_value`
`bar1_max`
`bar1_link`
`bar2_value`
`bar2_max`
`bar2_link`
`bar3_value`
`bar3_max`
`bar3_link`
`aura1_radius`
`aura1_color`
`aura1_square`
`aura2_radius`
`aura2_color`
`aura2_square`
`tint_color`
`status_dead`
`statusmarkers`
`showname`
`showplayers_name`
`showplayers_bar1`
`showplayers_bar2`
`showplayers_bar3`
`showplayers_aura1`
`showplayers_aura2`
`playersedit_name`
`playersedit_bar1`
`playersedit_bar2`
`playersedit_bar3`
`playersedit_aura1`
`playersedit_aura2`
`light_radius`
`light_dimradius`
`light_otherplayers`
`light_hassight`
`light_angle`
`light_losangle`
`light_multiplier`
`adv_fow_view_distance`
`groupwith`
`sides`
`currentSide`

Feature Support

Known Issues/Limitations

Looks like its perfect... (Did we miss anything?)

FAQ

Nothing's here (Do you have any suggestions?)

Best Practices

None as yet (Do you have any suggestions?)

Related Features

Did that answer your question(s)?

If not please check the under Support; Troubleshooting or the Known Issues page for further guidance, or go to the Discord community and leave a comment in the issues channel.

If you enjoy the project, please follow this link to see how you can contribute and help make it even better.

Feature: Animator

Contents