Module API

The API is available from init at game.modules.get('tokenlightcondition').api and at the TLC.api global.

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 a Token placeable or a TokenDocument. A position is a canvas center point { x, y, elevation }.

determineLightLevel

Calculates a token’s light level without applying effects or storing anything. Pass position to test another spot. It ignores HP, so a token at 0 HP still gets a level. The promise rejects if the calculation fails.

getEffectiveLightLevel

Returns the stored level adjusted for vision. When the stored level is dark and the token’s vision mode sees unlit ground, such as darkvision, with a sight range above 0, it returns dim. Otherwise it returns the stored level.

getLightLevel

Returns the level stored on the token, or null when the token has not been calculated or its level was cleared.

recalculate

Recalculates one token and applies the result. A token at 0 HP has its stored level and effect cleared. With position, the token is queued only when the level there differs from its stored level, and the committed level still comes from where the token stands. It does nothing on a client that is not the primary GM, or for an actor that is not a character or NPC.

refreshAllTokenLighting

Recalculates every eligible token on the viewed scene and resolves 'refreshed' once effects and levels are committed. A call made while a refresh is running resolves 'coalesced' immediately, and the running refresh repeats when it finishes. When the viewed scene is not the active scene, nothing is recalculated, a warning is shown once for that scene, and the promise still resolves 'refreshed'. Only the primary GM’s client calculates.

Hooks

tokenlightcondition.lightLevelChanged

Fires on every client for each token whose stored level changes.

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

tokenlightcondition.gatherLightSources

Fires each time the module collects the scene’s light sources, before tokens are scored. Push objects onto sources to add light the scene does not have.

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

Property	Meaning
x, y	Canvas coordinates
elevation	Elevation in scene distance units; defaults to 0
dim, bright	Radii in scene distance units; default to 0
priority	Resolution order against other sources; defaults to 0
darkness	true to lower the level instead of raising it

A contributed source reaches a token inside its radius, measured as a cylinder around its elevation. It ignores walls and emission angles, but light-restricting tiles still block it.