Hooks

Hooks Table

Starting with v2.9.0, PF2e Animations is adding new hooks to make creating mechanically complex animations easier. Below is a table of such hooks you can use.

All of them start with pf2eAnimations., so ex. pf2eAnimations.equipOrInvestItem

Hook	Args	Info
equipOrInvestItem	string|boolean, object	Returns "invested", "equipped", or false and the item data itself.

Ok, but how do I use them?

How Hooks work in detail are best described here, but to give a quick introduction, hooks allow you to create functions that are ran everytime something happens.

As such, you can create for example: Sequencer animations that run whenever an item is equipped, or a token takes damage. Here I will provide an example on how to do the former. You can copy paste this into a macro and then run it, to see that equipping Chain Mail on a token creates a Shield animation.

// "status" tells us in what state the item is in, such as "equipped", "invested", or simply false, which means neither.
// "data" is the item data, letting us find the actor it belongs to, it's name, it's properties, etc.
async function equipItem(status, data) {
    
    // Here we are grabbing available tokens belonging to the actor who owns the item.
    const token = data.actor.getActiveTokens()[0]
    // ... And checking if a token exists that we can put the animation on. If there is no token available, we will exit early, doing nothing.
    if (!token) return;

    // Change this to whatever item you wish to animate.
    const name = "Chain Mail"
    // ... And then checking if the item we got is the actual one we want to animate. If not, exit early, doing nothing.
    if (data.name !== name) return;

    // Here, we are checking if the item is equipped
    if (status === "equipped") {
        // The Animation Sequence
        new Sequence()
            .effect()
                .file("jb2a.shield.01.complete.01.blue")
                .attachTo(token)
                .persist()
                .scaleToObject(2)
                .origin("shield")
            .play()
    } else {
        // If the item is not equipped or invested, we will end the animation.
        await Sequencer.EffectManager.endEffects({ origin: `shield`, object: token })
    }
}

Hooks.on("pf2eAnimations.equipOrInvestItem", equipItem)
// To disable the hook, replace the above "on" with "off" so it's "Hooks.off"

You need to enable the macro every time you open Foundry, as Hooks get reset everytime you load the page. If you don't want to do that, look into modules such as Hook Macros or similar.