API - Items¶

Item Tags¶

addItemTag ^async → Item
removeItemTag ^async → Item

await api.addItemTag(item, { id: "tg_heat_self", val: "2" })  // adds or updates tag
await api.removeItemTag(item, "tg_heat_self")                   // removes tag by ID

Param	Type	Description
`item`	`Item`	The item to modify
`tagData`	`Object`	Tag object (e.g. `{ id: "tg_heat_self", val: "2" }`)
`tagId`	`string`	Tag ID to remove

isItemUsable → boolean

api.isItemUsable(item)

Whether the item can be used right now, matching the TAH row state: false when destroyed, disabled, unloaded, uncharged, out of uses or per-round/turn/scene limits, or lock-blocked.

The per-round/turn/scene part only counts when the enablePerRoundTurnTags setting is on. Those three are the perRound / perTurn / perScene resources of Extra Config.

Activated Items¶

setItemAsActivated ^async → Promise<Item>

await api.setItemAsActivated(item, token, endAction, endActionDescription, options)

Marks an item as activated, so it shows as active in the HUD and appears in getActivatedItems. endAction is the action the player spends to end it, surfaced on the end-activation entry. Close it with endItemActivation.

Param	Type	Default	Description
`item`	`Item`	required	The item to mark
`token`	`Token`	required	Owner of the item
`endAction`	`string`	required	Action spent to end it, e.g. `"Quick"` / `"Full"`
`endActionDescription`	`string`	`""`	Text shown when ending the activation
inside `options`
`blockAction`	`boolean`	`true`	Lock the action while the item is active. `false` opts out
`actionName`	`string`	the item name	Which action to lock
`blockReason`	`string`	`"<item> is already active."`	Reason shown on the locked row

By default this also takes an action lock, so the action named after the item cannot be used again while the activation stands. endItemActivation releases that lock. That is why the pairing is mandatory: end the activation any other way and the action stays locked.

await api.setItemAsActivated(item, token, 'Quick', 'Deactivate the shield.');
await api.setItemAsActivated(item, token, 'Quick', 'Deactivate the shield.', { blockAction: false });

getActivatedItems → Array<Item>

api.getActivatedItems(token)

Items on the token carrying lancer-automations.activeStateData.active, the flag setItemAsActivated writes.

Param	Type	Description
`token`	`Token`	The token to inspect

const active = api.getActivatedItems(token);
if (active.some(i => i.name === 'Aegis Shield Generator')) return false;

endItemActivation ^async → Promise<boolean>

await api.endItemActivation(item, token)

Ends an activation started by setItemAsActivated: clears the activated flags, releases the action lock it took, and posts the end-of-activation chat message through SimpleActivationFlow. Resolves whether the flow completed.

Param	Type	Description
`item`	`Item`	The activated item
`token`	`Token`	The token the flow runs for

await api.endItemActivation(item, token);

openEndActivationMenu ^async → Promise<Item | null>

await api.openEndActivationMenu(token)

Prompt listing the token's activated items. The picked one is ended via endItemActivation. Resolves the ended item, or null on cancel.

Params: token Token holder of the activated items

destroyItem ^async → Promise<Item | null>
disableItem ^async → Promise<Item | null>
restoreItem ^async → Promise<Item | null>

await api.destroyItem(item)
await api.disableItem(item)
await api.restoreItem(item)

Params: item Item

destroyItem sets system.destroyed, disableItem sets system.disabled, and restoreItem clears both. Destroyed/disabled items are skipped by the reaction engine and the action-lock system, and Lancer greys them on the sheet. Returns the item, or null if the argument is not an Item.

await api.disableItem(weapon);
await api.restoreItem(weapon);

Resource Management¶

setReaction ^async → void

await api.setReaction(actorOrToken, value)

Sets the reaction availability flag on an actor's action tracker.

Param	Type	Description
`actorOrToken`	`Token\\|Actor`	The token or actor to update
`value`	`boolean`	`true` = reaction available, `false` = reaction spent

await api.setReaction(reactorToken, false);

consumeAction ^async → void
gainAction ^async → void
modifyAction ^async → void

await api.consumeAction(actorOrToken, kind)
await api.gainAction(actorOrToken, kind)
await api.modifyAction(actorOrToken, kind, spend = true)

Param	Type	Default	Description
`actorOrToken`	`Token\\|Actor`	required	Whose tracker to change
`kind`	`'quick'\\|'full'\\|'free'\\|'protocol'\\|'reaction'\\|'move'`	required	Which action
`spend`	`boolean`	`true`	`modifyAction` only. `false` refunds

Writes system.action_tracker, following the same cascade as the sheet: spending quick takes full first when it is still up, spending full takes both, and any spend clears protocol. move goes to 0 on spend and back to the actor's speed on refund.

setReaction is the direct setter for the reaction flag alone, with no cascade.

await api.consumeAction(reactorToken, 'quick');

hasReactionAvailable → boolean

api.hasReactionAvailable(tokenOrActor)

Reads the reaction flag on the actor's action tracker. Always true when the actor has no combatant in the active combat, and when a combat exists but has not been started.

Params: tokenOrActor Token|Actor

if (!api.hasReactionAvailable(reactorToken)) return false;

isCombatant → boolean

api.isCombatant(tokenOrActor)

true when the token has a combatant in the started active combat. false outside combat or before the combat starts.

Params: tokenOrActor Token|Actor

if (!api.isCombatant(reactorToken)) return false;

isCurrentTurnActive → boolean

api.isCurrentTurnActive(tokenOrActor)

true while it is this token's turn in the active combat. false outside combat.

Params: tokenOrActor Token|Actor

if (!api.isCurrentTurnActive(reactorToken)) return false;

hasTurnAvailable → number

api.hasTurnAvailable(tokenOrActor)

Activations the token still has this round, read from its combatant. 0 outside a started combat.

Params: tokenOrActor Token|Actor

if (api.hasTurnAvailable(reactorToken) === 0) return false;

setItemResource ^async → void

await api.setItemResource(item, value, counterIndex)

Auto-detects the resource type.

Detection order: 1. Talent → system.counters[counterIndex].value (clamped to counter min/max) 2. Frame → system.core_system.counters[counterIndex].value (clamped to counter min/max) 3. Uses (uses.max > 0) → system.uses.value (clamped 0..max) 4. Loaded → system.loaded (Boolean(value)) 5. Charged → system.charged (Boolean(value))

Param	Type	Default	Description
`item`	`Item`	required	The item document to update
`value`	`number\\|boolean`	required	Target value. For `loaded`/`charged`: truthy/falsy. For `uses`/counters: number (clamped to valid range).
`counterIndex`	`number`	`0`	For talents and frames: which counter to update.

await api.setItemResource(talentItem, 2, 0);

const frame = actor.system.loadout.frame.value;
await api.setItemResource(frame, frame.system.core_system.counters[0].value + 1, 0);

updateTokenSystem ^async → void

await api.updateTokenSystem(token, data)

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

Param	Type	Description
`token`	`Token`	The token whose actor to update
`data`	`Object`	Update data object (e.g. `{ 'system.burn': 0, 'system.hp.value': 10 }`)

Example:

await api.updateTokenSystem(target, { 'system.burn': 0 });

Extra Config¶

Per-item config controlling Lancer's automation of the item: whether a resource is auto-consumed on activation, and when a per-X counter is spent. Stored at item.flags['lancer-automations'].extraConfig.

Nested actions with their own N/round frequency have a separate counter, addressed by a sub key: a{N} for system.actions[N], p{P}a{N} for a weapon profile action, r{N} for a talent rank.

Resource keys, and which functions take them:

Key	Auto-consume opt-out	Sub / consume-on	Consume / recharge
`uses`	yes	-	yes
`loading`	yes	-	yes
`charged`	yes	-	yes
`perTurn`	yes	yes	yes
`perRound`	yes	yes	yes
`perScene`	yes	yes	yes
`reserveUsed`	yes	-	yes

Auto-consume opt-out: setItemAutoConsumeDisabled, isAutoConsumeDisabled, getAutoConsumeDisabled.
Sub / consume-on: setSubAutoConsumeDisabled, getSubAutoConsumeDisabled, setConsumeOn, getConsumeOn. Only the per-X keys have their own counter to address.
Consume / recharge: consumeItemResource, rechargeItemResource.

setItemAutoConsumeDisabled ^async → string[]

await api.setItemAutoConsumeDisabled(item, 'uses', true);

true = do NOT decrement on activation. false = default behavior.

Param	Type	Description
`item`	`Item`	Owned Lancer item
`type`	`'uses'\\|'loading'\\|'charged'\\|'perTurn'\\|'perRound'\\|'perScene'\\|'reserveUsed'`	Resource key
`disabled`	`boolean`	true = opt out

Returns the updated opt-out array.

setItemAutoConsumeDisabledAll ^async → string[]

await api.setItemAutoConsumeDisabledAll(item, true);

Params: item Item · disabled boolean

Mass-toggle: apply opt-out to every resource type the item has (or clear all), nested action counters included.

setSubAutoConsumeDisabled ^async → string[]

await api.setSubAutoConsumeDisabled(item, 'a0', 'perRound', true);

Params: item Item · subKey string · type 'perTurn'|'perRound'|'perScene' · disabled boolean

Opt-out for one nested action's own counter.

getSubAutoConsumeDisabled → Set<string>

const off = api.getSubAutoConsumeDisabled(item, 'a0');

Params: item Item · subKey string

The opt-out set for one nested action. Empty Set when that action has none.

setConsumeOn ^async → Object

await api.setConsumeOn(item, 'perRound', 'hit');

Params: item Item · type 'perTurn'|'perRound'|'perScene' · mode 'auto'|'activation'|'hit'

When a weapon attack spends the counter. auto detects it from the text (N/round in on_hit / on_crit = on hit).

getConsumeOn → 'auto'|'activation'|'hit'

const mode = api.getConsumeOn(item, 'perRound');

Params: item Item · type 'perTurn'|'perRound'|'perScene'

The mode set by setConsumeOn, or 'auto' when none was set.

isAutoConsumeDisabled → boolean

if (api.isAutoConsumeDisabled(item, 'uses')) { ... }

Params: item Item · type string resource key

getAutoConsumeDisabled → Set<string>

const disabled = api.getAutoConsumeDisabled(item);

Params: item Item

consumeItemResource ^async → number|boolean|null

await api.consumeItemResource(item, 'uses', 2);
await api.consumeItemResource(item, 'loading');

Force a consume regardless of opt-out. Throws if the item does not have the resource type. Booleans set to false.

Only uses clamps to a real ceiling (system.uses.max). perTurn and perRound are floored at 0 with no upper bound, so a recharge past the tag's limit is not caught here.

Param	Type	Default	Description
`item`	`Item`	required	Owned Lancer item
`type`	`string`	required	Resource key, see the table above
`amount`	`number`	`1`	Positive integer for numeric fields, ignored for booleans

rechargeItemResource ^async → number|boolean|null

await api.rechargeItemResource(item, 'uses', 3);
await api.rechargeItemResource(item, 'charged');

Params: item Item · type string resource key · amount number (default 1)

Reverse of consume. Same signature, same validation, same clamping.

configureItemExtraConfig ^async → object

await api.configureItemExtraConfig(item, { autoConsumeDisabled: ['uses', 'loading'] });

Params: item Item · patch Object merged into the stored config

Generic setter for Extra Config fields with no helper. Prefer the explicit setItemAutoConsumeDisabled* helpers for the auto-consume feature.

The patch's top-level keys replace the stored ones, but the write itself goes through setFlag, which merges nested objects recursively. Passing { consumeOn: {} } therefore does not clear the stored consumeOn keys. Arrays are replaced whole.

getExtraConfig → object|null

const cfg = api.getExtraConfig(item);

Params: item Item

Returns the full Extra Config flag object, or null if never configured.

Consume Feedback¶

Any change to an item's consumable field (via API, Lancer flow, sheet click, TAH detail) triggers a floating text label above the actor's token + a generic_stat sound. To suppress for a specific update, pass options.laConsumeFeedback = false to item.update(...).