Active Effects

Effects applied

When a token’s condition resolves to dark or dim, the module applies an active effect to the actor. The Bright condition applies no effect (it is the absence of the others).

Effect	Icon	Statuses
Dark Lighting	icons/skills/melee/weapons-crossed-swords-black.webp	['dark']
Dim Lighting	icons/skills/melee/weapons-crossed-swords-black-gray.webp	['dim']

Both effects are created with transfer: false and disabled: false. They live on the actor directly, never on items. The module does not assign a stable document ID to created effects; Foundry generates a random ID at creation time. The module identifies its own effects by flags.tokenlightcondition.type, not by document ID.

In the generic path, names and descriptions are hardcoded English strings. The PF2e path resolves names via TOKENLIGHTCONDITION.Effects.Dark.Name / TOKENLIGHTCONDITION.Effects.Dim.Name from lang/en.json.

Flag schema on effects

Each effect carries this flag block so the module can identify its own effects when clearing:

{
  "tokenlightcondition": {
    "type": "dark | dim",
    "lightLevel": "dark | dim",
    "timestamp": 1700000000000
  }
}

When clearing, the module deletes any ActiveEffect on the actor whose flags.tokenlightcondition.type is set. Effects added by other modules are not touched.

Flag schema on actors

Flag	Type	Set when
tokenlightcondition.initialized	Boolean	First time the module sees the token; persists across reloads
tokenlightcondition.lightLevel	'bright' | 'dim' | 'dark'	After every successful calculation; cleared when the token loses HP or is otherwise made ineligible

The lightLevel flag is what the Token HUD Indicator reads.

Tracking-only mode

Setting Add Token Effects to off changes module behaviour:

• The actor flag (lightLevel) continues to be written on every calculation.
• The HUD indicator continues to render from that flag.
• No ActiveEffect is created on the actor.
• Existing effects from a prior run are cleared the next time the calculation pipeline runs against that token.

This is useful when another module or macro consumes flags.tokenlightcondition.lightLevel and you do not want the visible status effect on the token.

When effects are cleared

Effects are removed in three cases:

1. The token’s calculated condition is bright: any prior Dark / Dim effect is cleared first, then nothing is added.
2. The token loses HP and falls to 0 or below: the queue applies clear, which removes module effects and unsets the lightLevel flag.
3. The lighting toolbar is toggled off: all eligible tokens on the active scene have their module effects cleared.

Disabling the world enable setting via macro or settings UI also fires the same all-tokens clear path through EffectsManager.clearEffects.