Automated Animations

Automatically play animations and sounds when items are used, based on their name.

Getting Started

Melee

Install the module with JB2A and you are ready to go: the Global Automatic Recognition menu comes with hundreds of entries for common weapons and spells.

1. Select your token
2. Target a token
3. Use an item (attack, cast a spell...)

If the item name matches an entry, its animation plays. Melee, Range and most On Token animations need a target.

Global Automatic Recognition

Automatic Recognition Menu

Open from Module Settings → Automated Animations → Launch Menu, or with the globe button on any item menu (GM only).

• Search and filter by type with the bar at the top
• Edit, duplicate or delete an entry with the buttons on each row
• Add creates a new entry, Menu Manager imports and exports menus
• The header buttons open the Module Settings and the Diagnostics

Name Matching

An item uses the entry whose name is contained in the item name. Capitals and spaces don't matter.

• Sword matches Longsword, Shortsword, Sword of Wounding...
• Longer names win: Greatsword uses Greatsword before Sword
• Avoid the same name in two types, only the first match is used

Fine tune matching in the Recognition section of an entry.

Animation Types

Each entry has a type that decides how its Primary animation plays.

Melee

Plays from the source to the target. When the target is out of reach, it can switch to a ranged animation (Range Switch in the Primary tab).

Range

Range

Plays from the source to each target: arrows, bolts, rays.

On Token

On Token

Plays on a token: on the source, on the targets, on both, or on the targets falling back to the source when there are none.

Templates

Templates

Plays on the area template (Region) placed by the item. Can be persistent, as a Sequencer effect, attached to the template, or as a tile.

Aura

Aura

A persistent circle around the token that follows it. Set its size with Radius, in grid squares.

Preset

Ready-made sequences:

• Projectile to Template: a projectile flies to the template and explodes, like Fireball
• Teleportation: moves or teleports the token, like Misty Step
• Dual Attach: a beam linking the source and the target, like Witch Bolt
• Thunderwave: the D&D 5e Thunderwave cube

Active Effects

Active Effect

Plays when an Active Effect with a matching name is added to an actor, as On Token or Aura. Persistent animations end when the effect is removed. Works with PF1 buffs and PF2e/SF2e conditions and effects too.

Editing an Entry

General Tab

Every entry, global or on an item, is edited in tabs. The right column shows a live preview of the chosen animations. Hover the ? next to any option for a short explanation.

General

• Name and Type of the entry
• Sound Only: plays a sound, no animation
• Macro: runs a macro with the animation, see Macros

Recognition

• Force Exact Match: only items with exactly this name match
• Excluded Search Words: items containing one of these words don't match. For example, Sword excluding Sword of
• Exclude Item Property: items with this property value don't match, for example path type and property spell

Primary, Secondary, Source, Target

Primary Tab

• Primary: the main animation, required
• Secondary: plays on the targets after the primary, for example an explosion
• Source: plays on the source token
• Target: plays on each target

Each section has:

• Animation: pick it from the Sequencer database (Type, Animation, Variant, Color), or enable Custom to use any file or database path
• Options: elevation, scale or radius, opacity, repeats, delay...
• Color Tint: shift hue, contrast and saturation, or tint with a color. The preview updates live
• Sound: a sound file, with volume, delay and start time

Delay and Wait

• Delay: milliseconds before this part starts. All parts start together, offset by their delay
• Wait: the next part starts when this one ends, plus these milliseconds. Negative values overlap

With persistent effects, Wait on the Primary makes the next part play when the effect is removed.

Motion

Motion Tab

Moves the tokens themselves, no animation file needed.

• Source: Lunge, Recoil, Shake, Flash, Spin, Pulse, Float or Fade
• Target: Shake, Knockback, Flash, Spin, Pulse, Float or Fade. Only on hit skips missed targets
• Screen Shake: shakes the screen of every player

The melee animation at the top uses a source Lunge, a target Knockback and a Screen Shake.

3D Canvas

With 3D Canvas active, Melee, Range and On Token entries get a 3D Canvas tab to use particle effects and token animations instead.

Item Menu

Item Sheet Button

Item Menu

Open from the item sheet header: ⋮ → Automated Animations. Works on Items, Activities and Active Effects.

The Status tab shows what the item will do:

• Animation Enabled: uncheck to never animate this item
• Customize Item: ignore the global menu and set an animation only for this item
• Animation Type: the type of the custom animation
• Recognition: the global match, if any. The ⋮ button copies the global entry into the item, or the item animation into the global menu (GM only)

Customizing an item unlocks the other tabs, the same as in the global menu.

Menu Manager

Menu Manager

Open from the Menu Manager button of the global menu.

• Restore Default Menu: back to the default entries
• Merge Menu: adds the entries of a JSON file, keeping yours
• Overwrite Menu: replaces your entries with the ones of a JSON file
• Export Menu: saves your menu to a JSON file
• Delete Menu: removes every entry of the chosen types

Merge, Overwrite and Delete let you choose which types to change. A backup is exported before anything is erased.

Persistent Effects

Persistent animations stay on the canvas until removed:

• Sequencer effects: remove them with the Sequencer Effect Manager. Players can remove their own with at least Trusted permissions
• Tiles: delete them from the Tiles layer

Persistent animations of Active Effects end on their own when the effect is removed.

Diagnostics

Diagnostics

Animations not playing? Open the Diagnostics from the stethoscope button of the global menu. It checks the settings that most often stop animations, for any connected user, and lists the usual troubleshooting steps.

Settings

• Automated Animations: turn animations off for yourself only
• Disable Automatic Recognition: only customized items animate
• Global Delay: milliseconds before every animation starts
• JB2A Asset Location: only if JB2A is hosted externally, for example on S3
• Hide the Animation Tab from Players: players can't open the item menu
• Disable Melee to Range switch
• Disable Active Effect Animations
• Disable Persistent Effect Tips
• Hide Regions on Token Layer: template regions are visible only on the Regions layer

Some systems add their own settings, for example playing on damage rolls instead of attacks, on misses, or on critical hits (D&D 5e).

Macros

Enable Macro in the General tab to run a macro with the animation.

• Macro: the name of a world macro, Compendium.<scope>.<pack>.<macro name>, or ItemMacro to use the item's Item Macro
• When to Play:
  • Concurrent: macro and animation start together
  • Await Macro: the animation waits for the macro
  • Macro Only: no animation
  • Await Animation: the macro waits for the animation
• Send Args: extra data, as values separated by commas or as an object in braces

The macro receives args:

• args[0]: the workflow that started the animation, usually the chat message
• args[1]: the Automated Animations data: sourceToken, actor, item, allTargets, hitTargets and more
• args[2]: the Send Args data

// Plays a Fire Bolt of the color sent in Send Args, blue by default
const data = args[1];
const color = args[2]?.[0] ?? "blue";
 
const seq = new Sequence();
for (const target of data.allTargets) {
    seq.effect()
        .file(`jb2a.fire_bolt.${color}`)
        .atLocation(data.sourceToken)
        .stretchTo(target);
}
seq.play();

On Active Effects, args[0] is "on" when the effect is added and "off" when it is removed.

API

Play an animation

AutomatedAnimations.playAnimation(sourceToken, item, options);

• sourceToken: the token using the item
• item: the item, or an object with a name for the global menu, like { name: "Dagger" }
• options:
  • targets: array or set of target tokens, defaults to the user's targets
  • hitTargets: tokens that were hit
  • playOnMiss: play the "miss" version for targets not hit
  • templateData: the template Region, for template animations
  • reachCheck: extra reach for melee, in grid squares

Other

AutomatedAnimations.showAutorecMenu();         // Open the global menu
AutomatedAnimations.openAnimationMenu(item);   // Open the menu of an item or effect
 
AutomatedAnimations.AutorecManager.getAutorecEntries(); // All global entries
AutomatedAnimations.AutorecManager.exportMenu();        // Download the global menu
AutomatedAnimations.AutorecManager.mergeMenus(json, { melee: true });     // Merge a menu
AutomatedAnimations.AutorecManager.overwriteMenus(json, { melee: true }); // Overwrite a menu
AutomatedAnimations.AutorecManager.addMetaData(metaData, { melee: true }); // Tag entries

Menu keys are melee, range, ontoken, templatefx, aura, preset and aefx. Leave the options empty to use all of them.

Hooks

• aa.workflow (token, item, options): call it to play an animation, same as playAnimation
• aa.preAnimationStart (data): before an animation starts
• aa.animationStart / aa.animationEnd: when an animation starts or ends

Adding System Support

Automated Animations needs three things from a system when an item is used: the item, the source token and the targets. Most systems provide them with the createChatMessage hook, others with their own hooks.

To add a system, create src/system-support/aa-<system>.js exporting a systemHooks() function (use aa-dnd5e.js as an example) and add it to src/system-support/index.js.

• Run the hook only for the user who rolled: if (msg.user.id !== game.user.id) return;
• If attack and damage are rolled separately, play on only one of them, or animations will play twice
• Pass the data to getRequiredData() and the result to trafficCop()

Systems that already provide the data can skip all this and call AutomatedAnimations.playAnimation directly.