API - Flags & Gates¶

Item, Token & Actor Flags¶

addItemFlags ^async → Item
removeItemFlags ^async → Item
getItemFlags → any

await api.addItemFlags(item, flags)            // set flags under 'lancer-automations'
await api.removeItemFlags(item, flags)         // unset the listed keys
api.getItemFlags(item, flagName?)              // read flags (specific key or all)

Params: item Item · flags Object key/value pairs · flagName string optional single key

Routes through the GM via socket when the calling user does not own the item. Every add / remove helper on this page returns null and posts a ui.notifications.error when the document is missing or flags is not an object.

Known flag keys (the subset meant for you to write, the namespace also holds keys the module manages on its own):

Key	Type	Used by	Description
`deployRange`	`number`	`placeDeployable`	Default placement range
`deployCount`	`number`	`placeDeployable`	Default number to place

Example:

await api.addItemFlags(myItem, { deployRange: 5, deployCount: 2 });

addTokenFlags ^async → TokenDocument
removeTokenFlags ^async → TokenDocument
getTokenFlags → any

await api.addTokenFlags(tokenOrDoc, flags)     // set flags under 'lancer-automations'
await api.removeTokenFlags(tokenOrDoc, flags)  // unset the listed keys
api.getTokenFlags(tokenOrDoc, flagName?)       // read flags (specific key or all)

The token-document counterpart to addItemFlags / removeItemFlags / getItemFlags. Routes through the GM via socket when the calling user does not own the token.

Param	Type	Default	Description
`tokenOrDoc`	`Token\\|TokenDocument`	required	Token to read or stamp
`flags`	`Object`	required	Key/value pairs set under `lancer-automations`. For `removeTokenFlags` only the keys matter
`flagName`	`string`	`null`	Read one key. Omit for the whole namespace object

await api.addTokenFlags(token, { wasArmed: true });
const armed = api.getTokenFlags(token, 'wasArmed');
await api.removeTokenFlags(token, { wasArmed: true });

wasArmed is the module-managed flag the Mine Zone arming reaction stamps to keep a mine from re-arming. Your own keys go in the same namespace.

addActorFlags ^async → Actor
removeActorFlags ^async → Actor
getActorFlags → any

await api.addActorFlags(actor, flags)          // set flags under 'lancer-automations'
await api.removeActorFlags(actor, flags)       // unset the listed keys
api.getActorFlags(actor, flagName?)            // read flags (specific key or all)

Params: actor Actor · flags Object key/value pairs · flagName string optional single key

Routes through the GM via socket when the calling user does not own the actor.

Known flag keys (deployable Mines, read by the Mine Zone general reaction). Same caveat as above: this is the writable subset, not the whole namespace.

Key	Type	Default	Description
`mineDetectionRadius`	`number`	`1`	Aura radius in grid units.
`mineDetectionDisposition`	`"ALL"` \| `"FRIENDLY"` \| `"HOSTILE"` \| `"NEUTRAL"`	`"ALL"`	Which disposition triggers the detonation prompt.
`customMineDetection`	`boolean`	`false`	Skip the default `LA_MineZone` aura entirely. The per-LID handler installs its own detection.

Example:

await api.addActorFlags(mineActor, {
    mineDetectionRadius: 3,
    mineDetectionDisposition: "HOSTILE"
});

getLAFlag → any
setLAFlag → Promise
unsetLAFlag → Promise
getLAFlags → Object

api.getLAFlag(doc, key, fallback?)
await api.setLAFlag(doc, key, value)
await api.unsetLAFlag(doc, key)
api.getLAFlags(source)

Params: doc Document · key string flag key, without the namespace · fallback any returned when the flag is unset · value any · source Object anything carrying a flags bag

Raw access to the lancer-automations flag namespace, the same helpers the module uses internally. All four are safe on a missing document and return undefined instead of throwing. getLAFlags reads the whole bag off plain data, for hook payloads and source objects that have no getFlag.

Example:

const history = api.getLAFlag(token.document, 'moveHistory', []);
await api.setLAFlag(token.document, 'isDead', true);

Gates¶

consumeGate ^async → Promise<boolean>
checkGate → boolean
clearGate ^async → Promise<void>
consumeOncePerRound ^async → Promise<boolean>
consumeOncePerTurn ^async → Promise<boolean>

await api.consumeGate(owner, key, { subject?, rounds?, turn? })  // take the gate → true when it was free
api.checkGate(owner, key, subject?)                              // peek without taking
await api.clearGate(owner, key, subject?)                        // release early (omit subject: whole key)
await api.consumeOncePerRound(owner, key, subject?)              // consumeGate with rounds: 1
await api.consumeOncePerTurn(owner, key, subject?)               // consumeGate with turn: true

Param	Type	Default	Description
`owner`	`Token \\| Actor`	required	Holds the gate, usually the reactor
`key`	`string`	required	Name of the gate, e.g. `'ring_of_fire'`
`subject`	`Token \\| Actor \\| string \\| null`	`null`	Counted separately per subject. Omit for one gate on the owner
inside `consumeGate`'s options
`rounds`	`number \\| null`	`1`	Rounds blocked counting the current one. `null` lasts the whole combat
`turn`	`boolean`	`false`	Block for the current turn instead of a round count

subject is the third positional argument on checkGate, clearGate, consumeOncePerRound and consumeOncePerTurn. On consumeGate it is a key of the options object instead.

Rate limits stored as one actor flag. Expiry is checked on read, nothing ticks, and a gate only lives inside the combat it was taken in. Out of combat every call succeeds. checkGate is sync, safe in evaluate.

rounds stores an absolute expiry round, combat.round + max(1, rounds) - 1, and the gate is blocked while the current round is at or below it. Taken with rounds: 2 on round 5, it expires at the start of round 7.

An owner that resolves to no actor, or a falsy key, makes the whole family inert: consumeGate and checkGate return true (fail open, the gate never blocks) and clearGate does nothing.

if (await api.consumeOncePerRound(reactorToken, 'ring_of_fire', target))
    await api.executeDamageRoll(reactorToken, [target], 2, 'Heat', 'Ring of Fire');

if (!await api.consumeGate(reactorToken, 'flicker_field', { subject: 'standard', rounds: 2 }))
    return;

Flow Flags¶

getFlowFlag → any
setFlowFlag → boolean

api.getFlowFlag(triggerData, key)         // read a la_extraData flag off the flow
api.setFlowFlag(triggerData, key, value?) // stamp it (once-per-flow gates)

Params: triggerData the trigger's data object · key string · value any (default true)

They replace the hand-written flowState.la_extraData stamp and its evaluate read.