Module API

The module publishes its API during Foundry’s init phase; reach it from game.modules.get('tokenlightcondition').api or from the TLC.api global. The module’s active check is a sufficient guard from init onward.

if (game.modules.get('tokenlightcondition')?.active) TLC.api.refreshAllTokenLighting();

Methods

Method	Signature	Returns
determineLightLevel	(token, position?)	Promise<'bright' | 'dim' | 'dark'>
getEffectiveLightLevel	(token)	'bright' | 'dim' | 'dark' | null
getLightLevel	(token)	'bright' | 'dim' | 'dark' | null
recalculate	(token, position?)	Promise<void>
refreshAllTokenLighting	()	Promise<'refreshed' | 'coalesced'>

Every method that takes a token accepts either a Token placeable or a TokenDocument.

determineLightLevel

Calculates the lighting condition for a token against the current scene. Omit position to evaluate the token where it stands, or pass { x, y, elevation } to evaluate a hypothetical position instead. The calculation is read-only: no effect is applied and no flag is written. It does not check the token’s hit points, so a token at 0 HP still returns a level. The call rejects when the calculation fails; no level is returned in its place.

getEffectiveLightLevel

Reads the level the token experiences rather than the level of the ground it stands on. A token whose vision mode sees unlit ground reads dim where getLightLevel reads dark. Every other level is returned unchanged. The value is derived when you read it; nothing is stored.

getLightLevel

Reads the light level stored on the token. It returns null when the token has never been calculated or when its level was cleared.

recalculate

Recalculates one token and commits the result. Omit position to use the token where it stands, or pass { x, y, elevation } to score a hypothetical position instead. Calling it on a client that is not the primary GM resolves immediately without calculating or writing anything. It checks the token’s hit points: a token at 0 HP resolves to no level, and its stored level is cleared.

refreshAllTokenLighting

Recalculates every eligible token on the drawn scene and resolves once the resulting effects and flags have been committed. A call made while a refresh is already running is absorbed into it and resolves with 'coalesced'. Calling it while the canvas shows a scene other than the world’s active scene does nothing. The first such call raises a warning notification for that scene; the promise still resolves 'refreshed'.

Hooks

tokenlightcondition.lightLevelChanged

Fires for each token whose stored level changed. It fires on every connected client, not only the primary GM’s.

Hooks.on('tokenlightcondition.lightLevelChanged', (tokenDocument, newLevel, oldLevel) => {
  console.log(tokenDocument.name, oldLevel, '->', newLevel);
});

Argument	Type	Meaning
tokenDocument	TokenDocument	The token whose level changed
newLevel	'bright' | 'dim' | 'dark' | null	The committed level; null when the token was cleared
oldLevel	'bright' | 'dim' | 'dark' | null	The level stored before the change

The hook is keyed on the flag write, so a client receives it as soon as Foundry replicates the change. A token whose write did not land fires nothing.

tokenlightcondition.gatherLightSources

Fires once per refresh, before any token is scored. Push an object onto the array to contribute a light the scene does not model as a Foundry light.

Hooks.on('tokenlightcondition.gatherLightSources', (sources, scene) => {
  sources.push({ x: 1000, y: 1000, elevation: 0, dim: 40, bright: 20, priority: 0 });
});

Argument	Type	Description
sources	object[]	Mutable array to push contributions onto
scene	Scene	The scene being calculated

A contribution takes x, y, elevation, dim, bright, priority, and darkness. Radii are given in scene distance units and elevation in scene units. Set darkness to true to have the source lower the condition rather than raise it, and priority to place the source against the scene’s own lights.

A contributed source is measured as a cylinder. A token further above or below the source’s elevation than the radius falls outside it.