Concepts

Temporary vs. saved

	Methods	Saved to the world?	At the end of play()
Temporary	offset(), face(), restore()	Never	Tokens return to their saved position and rotation (turn off with autoRestore(false))
Saved	moveTo(), moveBy(), face(x, {persist: true})	Once, after the token's last step	The new position/rotation becomes the saved one

Use offset for anything that should snap back (attacks, recoils, dodges, shakes) and moveBy/moveTo for anything that should stay (knockback, shove, dash, click-to-move).

Timelines

Every token has its own timeline. Each step starts where the previous step of the same token ended, and coming back to a token with on() continues its timeline. Different tokens start at 0 and run in parallel.

• wait(ms) pauses the current token.
• mark("name") remembers the current token's time.
• at("name"), at(ms), at("start"), at("end") move the current token's cursor. "end" is the latest point any token has reached so far.

TokenMove.between(source, target)
  .on("source").offset({ tokens: 0.8, duration: 200 }).mark("hit").restore()
  .on("target").at("hit").offset({ direction: "backward", tokens: 0.3 })   // starts exactly at 200 ms
  .play();

Directions

Value	Meaning
"forward" / "toward"	Toward the reference
"backward" / "back" / "away"	Away from the reference
"right", "left"	90° clockwise / counter-clockwise from forward (as seen on screen)
"random"	Any angle
number	Degrees clockwise from forward
array	One entry picked at random, e.g. ["left", "right"]

The reference ("forward") is chosen by relativeTo:

relativeTo	Forward is
"auto" (default)	Toward the other token if this token is part of between(), otherwise the token's facing
"facing"	The token's current rotation (rotation 0 faces down)
"world"	Down the screen (south); 90 = west, 180 = north, 270 = east
token / {x, y}	Toward that token or point

Shortcuts: toward: ref and away: ref set the reference and point toward/away from it, e.g. moveBy({ away: source, squares: 2 }). Tokens used as references always use their saved position at the moment play() is called.

Distances

Give exactly one of these (each accepts a number or a [min, max] range):

Key	Unit
tokens	Widths of the moving token (offset default: 0.5)
squares	Grid spaces
units	Scene units (e.g. feet, as set in the scene's grid settings)
px	Canvas pixels

Token references

Anywhere a token is expected you can pass a Token, TokenDocument, Actor (its first active token on the scene), "source" / "target" (the between() pair, falling back to controlled/targeted), "controlled", "targeted", a token id, or a UUID.

References are checked when the chain is built, so a wrong id throws right away. "source", "target", "controlled" and "targeted" outside a between() pair are looked up when play() runs, so a stored chain follows the current selection.