Class FoundryClient

Connects to FoundryVTT. REST API mode: tests /api/status endpoint. Socket.IO mode: authenticates and loads full worldData.

Reports whether the client currently has a live link to FoundryVTT (#217).

Socket.IO mode answers from the socket itself rather than from a latched flag, so a link that dropped without an explicit disconnect() — server restart, network loss — reads as disconnected immediately, even if the disconnect event has not been delivered yet. It tracks the socket in both directions: an automatic reconnect (onSocketConnect) reads as connected again rather than staying latched off.

REST API mode (FOUNDRY_API_KEY) has no socket to ask, so it answers from the last REST request that actually happened: a request that failed to reach FoundryVTT (connection refused, reset, timed out) reads as disconnected from then on, and the next request that gets through reads as connected again. An HTTP error status does not count as a drop — the server answered. This is a last observed outcome, not a live probe: it cannot notice a server that went away between requests, and it never does I/O of its own, because this accessor is synchronous and widely called.

True when the cached snapshot is no longer being kept live by broadcasts — i.e. the socket dropped after a world load (#217). Reads still answer from the cache; this flags that the answer is a point-in-time copy.

Returns true if worldData is available (Socket.IO mode connected).

Re-emits 'world' on the existing socket to refresh the cached snapshot.

Registers a one-shot 'world' listener and cleans it up on every exit path (success, error, timeout) via socket.off() so that repeated refreshes over a long-running session do not leak listener handles.

Returns the raw WorldActor with the full system data (game-system specific).

Patches attributes on an actor's system object (#143). WRITE — Socket.IO.

patch keys are dot-paths into actor.system (e.g. attributes.hp.value, currency.gp, spells.spell1.value, attributes.exhaustion). Each key is prefixed with system. and sent through the Socket.IO modifyDocument write protocol as an Actor update — matching FoundryVTT's own document model (Actor#update). No REST call and no apiKey are involved.

Client-side validation, using the actor's current data, rejects:

• HP value exceeding max + temp,
• spell-slot value exceeding its max,
• exhaustion outside 0–10 (2024 rules) or 0–6 (2014 rules).

Searches FoundryVTT compendium packs by name and metadata.

Compendium data is not present in the cached worldData snapshot, so this read requires the REST API module (FOUNDRY_API_KEY). When the key is absent it returns a graceful empty result with restAvailable: false rather than throwing, mirroring the no-worldData behaviour of searchItems/searchActors; the handler surfaces a note explaining why no results were returned.

Creates a new item on an actor via the modifyDocument socket protocol.

Inline sources are created directly. Compendium sources are NOT yet supported over Socket.IO — copying a pack entry needs a compendium read that modifyDocument does not provide (tracked in issue #159).

Applies a JSON merge patch to an item owned by an actor.

The patch is merged into the item's system data (recursively, so nested paths like the D&D 5e v4+ activities.{id}.consumption.targets are preserved). Performed via the modifyDocument socket protocol.

Deletes an item owned by an actor via the modifyDocument socket protocol.

Updates the active combat's turn/round pointers (FR-018).

Combat is a top-level document, so the update carries no parentUuid. The patch fields map directly onto the Combat document (turn, round).

Ends (deletes) the active combat encounter (FR-018).

Sets a combatant's initiative (FR-018).

Combatant is an embedded document inside Combat, so the update is sent with parentUuid: "Combat.<combatId>".

Starts a new combat encounter and seeds its combatants (FR-018, #172).

Two-step modifyDocument flow:

1. Create the top-level Combat document (no parentUuid), activated on the given scene, and read its _id from the response.
2. Create the embedded Combatant documents with parentUuid: "Combat.<combatId>" (mirrors the Combatant→Combat embed used by setCombatantInitiative).

The create wire shape is verified against the v13.348 client source per .claude/rules/foundry-write-protocol.md; smoke-test one live round-trip when changing it.

Locates a token (and the scene it lives on) in the cached worldData.

Token is an embedded document of Scene; worldData carries each scene's tokens as raw records. When sceneId is omitted the search spans every scene, so a token can be moved/affected without first resolving its scene.

Moves a token to new x/y coordinates (FR-019).

Token is an embedded document of Scene, so the update is sent with parentUuid: "Scene.<sceneId>" (mirrors the Combatant→Combat embed). The wire shape is verified against the v13.348 client source per .claude/rules/foundry-write-protocol.md.

Creates a status-effect ActiveEffect on a token's actor (FR-019).

ActiveEffect is an embedded document of Actor, so the create is sent with the actor's parent UUID:

• Actor.<id> for a world-linked actor (actorLink: true)
• Scene.<sid>.Token.<tid>.Actor.<aid> for an unlinked token's synthetic actor (the per-token delta).

The effect carries a statuses array, matching how FoundryVTT v11+ models conditions (Actor#toggleStatusEffect toggles by this field).

Deletes an ActiveEffect from a token's actor (FR-019), e.g. to clear a status condition. Accepts the same parent-UUID forms as createActorStatusEffect.

Creates a new JournalEntry with one or more text pages.

JournalEntry is a top-level document (unlike Item/ActiveEffect, which are embedded in an Actor), so the create carries no parentUuid — mirrors startCombat's top-level Combat create. Each entry in pages is mapped to Foundry's native JournalEntryPage text-page shape, with an explicit sort so the pages render in the order supplied.

Rolls a dice formula.

Validation is deliberately per transport, because the two transports are not equally capable (#219):

• REST (FOUNDRY_API_KEY) posts the formula to /api/dice/roll, where FoundryVTT's own Roll engine evaluates it. That engine understands more than this module does — parentheses, for one — so only the DICE_FORMULA_ALPHABET check applies here. Imposing the local parser's narrower grammar would take away a capability the transport has. What the alphabet does refuse is refused by name and position (unexpected "k" at position 3, via alphabetViolation), so the two transports are equally specific about what they would not evaluate.
• Socket.IO / no API key has no remote evaluator: fallbackDiceRoll is the roller, so the grammar its parser can represent is the grammar accepted, and that parser is the only gate. No alphabet pre-check runs ahead of it, so its specific message (unexpected "k" at position 3) reaches the caller instead of a generic Invalid dice formula: 4d6kh3. Nothing is ever dropped from a total in silence.

The length cap is common to both. A REST roll that cannot reach FoundryVTT falls through to the local roller, which then applies the strict grammar — a formula only Foundry could evaluate errors out rather than being mis-totalled locally.