update-token
Edit placed tokens on a scene: adjust rotation, scale, elevation, hit points, name, visibility, and more for one or multiple tokens by id or actor name. Updates applied in batch, with auto-unlock for rotated locked tokens.
Instructions
Edit one or more PLACED tokens on a scene — a token INSTANCE already dropped on the map, NOT the actor's prototype token (that's update-actor). Resolve the scene by id/exact name (default: the ACTIVE scene), then target tokens by tokenIds and/or actorIds (an actor id OR exact name — updates EVERY placed copy of that actor, e.g. all "Dead Guard" corpses). Patch any of: rotation (or randomizeRotation for an independent per-token angle), scale (token art size — sets texture.scaleX/scaleY together), elevation, hidden, lockRotation, x/y, name, displayName (nameplate visibility), displayBars (resource-bar visibility), bar1/bar2 (which resource each bar tracks — the health bar is bar1 = attributes.hp), ring (dynamic token ring on/off), and hp (this token's CURRENT hit points, per-token on its own delta — so two copies of one actor can be wounded differently, which update-actor cannot do) — all matched tokens update in one batch. GOTCHA handled for you: a token whose actor had auto-rotate OFF carries lockRotation:true, which HIDES a set rotation — so when you rotate a locked token the tool auto-unlocks it and warns. Reports matched/updated counts + any unresolved ids. GM-only.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | New token X in absolute canvas pixels. | |
| y | No | New token Y in absolute canvas pixels. | |
| hp | No | Set THIS placed token's hit points on its own actor — PER-TOKEN, so two copies of the same actor can differ (e.g. a band wounded to different HP). Writes system.attributes.hp.* on the token's (unlinked) delta, NOT the prototype/statblock — the right home for a token's current HP. For a linked token it writes the shared base actor. Only the sub-fields you pass change; 0 is valid (a downed creature). | |
| bar1 | No | Bar 1 resource attribute path (health bar is "attributes.hp"); "" clears it. | |
| bar2 | No | Bar 2 resource attribute path (e.g. "attributes.hp"); "" clears it. | |
| name | No | Rename the placed token (its nameplate). | |
| ring | No | Dynamic token ring: false = plain token (the house default), true = ring on. Sets ring.enabled on the placed token. | |
| scale | No | Token ART scale (sets texture.scaleX and scaleY together). 1 = normal, 1.5 = 50% larger. | |
| hidden | No | Hide (true) or reveal (false) the token from players. | |
| actorIds | No | Actor id OR exact actor name — updates ALL placed copies of each (e.g. every "Dead Guard" token on the map). Combined (union) with tokenIds. | |
| rotation | No | Facing in degrees (0–359), applied to every matched token. | |
| tokenIds | No | Placed-token ids to update (from list-tokens). Combined (union) with actorIds. | |
| elevation | No | Token elevation in grid-distance units (e.g. feet). | |
| displayBars | No | Resource (health) bar visibility, same modes as displayName: none | control | owner-hover | hover | owner | always. | |
| displayName | No | Nameplate visibility: none | control (only when selected) | owner-hover | hover | owner (always, to owners) | always (always, to everyone). | |
| lockRotation | No | Lock the token art from rotating. NOTE: lockRotation:true HIDES any `rotation` you set, so when you rotate a locked token and omit this, the tool AUTO-UNLOCKS it (and warns) so the angle is visible. | |
| sceneIdentifier | No | Scene id or exact name holding the token(s). Omit to use the ACTIVE scene. | |
| randomizeRotation | No | Give each matched token its OWN random angle (0–359) instead of one shared `rotation` — e.g. to strew corpses naturally. Overrides `rotation` when true. |