API Reference

Creating

new TokenMove(options?)
TokenMove.on(token, options?)               // = new TokenMove(options).on(token)
TokenMove.between(source, target, options?) // = new TokenMove(options).between(source, target)

Option	Default	Description
walls	false	Stop movements at walls that block movement
sync	true	Play on every connected client
restore	true	Undo temporary offsets/rotations at the end of play()

The same can be set in the chain with .walls(bool), .sync(bool), .autoRestore(bool).

.between(source?, target?)

Makes two tokens relative to each other and enables on("source") / on("target"). Defaults to the controlled and the targeted token.

.on(token?)

Selects the token for the following steps. Defaults to the controlled token.

.offset(config) — temporary

Property	Type	Default	Description
direction	string | number | array	"forward"	See Directions
relativeTo	string | token | point	"auto"	See Directions
toward / away	token | point	—	Shortcut for reference + direction
tokens / squares / units / px	number | [min, max]	tokens: 0.5	See Distances
duration	number | [min, max]	250	Milliseconds
delay	number | [min, max]	0	Milliseconds before the step
ease	string | function	"easeInOutQuad"	See Easings
face	boolean	false	Turn toward the movement direction (temporary)
repeats	number	0	Additional repetitions; random values are re-rolled each time
yoyo	boolean	false	Return to the step's starting point after each repetition
walls	boolean	chain option	Override wall collision for this step

Accepts an array of configs to add several steps at once.

.restore(config?) — temporary

Animates back to the saved position and rotation (including positions saved earlier in the same chain). duration (400), delay (0), ease ("easeOutQuad").

.moveTo(destination, config?) — saved

Moves to a canvas point (the token's new center, e.g. a Sequencer crosshair result) or to a token. A falsy destination, such as a cancelled crosshair, skips the step.

Property	Default	Description
duration, delay, ease, face, walls	500, 0, "easeInOutQuad", false, chain option	As in offset. face is saved.
snap	true	Snap to the grid (size-aware; ignored on gridless scenes)
adjacent	false	When moving to a token: stop next to it instead of on top of it
action	token's movement action	Movement action recorded for the save, e.g. "displace" for forced movement (knockback, shove) so it isn't counted as the token walking

.moveBy(config) — saved

Moves a distance in a direction. Takes the direction and distance options of offset (a distance is required) plus duration, delay, ease, face, snap, walls, action as in moveTo. Consecutive moveBy steps add up.

.face(what?, config?)

Rotates toward a token or point, or to an absolute rotation in degrees. Defaults to the other between() token, or the targeted token. duration (150), delay, ease ("easeOutQuad"), persist (false: save the rotation).

.wait(ms), .mark(name), .at(time)

See Timelines. wait accepts [min, max].

.playIf(condition)

Plays only if the condition is truthy. A function is called (and awaited) when play() runs, so the same builder can be replayed with a changing condition.

.play(options?)

Compiles and plays the animation. Returns Promise<{completed: boolean, skipped?: boolean}>. completed is false if one of the tokens is no longer on the scene (its steps are skipped), a newer animation took over one of the tokens, the scene changed mid-animation, or a new position couldn't be saved; it never throws for that. A chain that has nothing to do when it runs (e.g. face() toward a token it already faces) resolves with completed: true. play() only throws for mistakes in the chain itself, such as a chain without steps.

Calling play() again replays the chain (random values are re-rolled), also after the scene was redrawn or switched away and back. Option: sync (overrides the chain option).

.stop(options?) / TokenMove.stop(tokens?, options?)

Cancels TokenMove animations and snaps tokens back to their saved position. TokenMove.stop() with no tokens affects every token on the scene. Options: reset (true), sync (true).

Presets

.lunge({ tokens = 0.6, duration = 150, ease = "easeInQuad", mark = "impact", restoreDuration = 350, ...offsetOptions })
.shake({ tokens = 0.06, duration = 40, times = 6, ...offsetOptions })

Register your own (e.g. in a world script or a macro that runs on every client):

TokenMove.register("hop", (tm, { height = 0.3 } = {}) => {
  tm.offset({ relativeTo: "world", direction: 180, tokens: height, duration: 120, ease: "easeOutQuad" })
    .offset({ relativeTo: "world", direction: 0, tokens: height, duration: 120, ease: "easeInQuad" });
});
TokenMove.on(source).hop({ height: 0.5 }).play();

Presets only need to exist on the client that starts the animation.

Module API

const api = game.modules.get("tokenmove").api;
api.TokenMove                 // same as the global TokenMove
api.easings                   // array of easing names
api.registerEasing("snap", t => t < 0.8 ? 0 : (t - 0.8) * 5);