Protocol messages

Client and server messages generated from protocol version 43.

12 minute read

The current wire contract is PROTOCOL_VERSION 43. The handshake negotiates this integer independently from the Aether release and package versions. Message ids and fields come from packages/protocol/src/index.ts; internal parsing helpers are not listed. The purpose catalog is exhaustive, so adding or removing a public message fails generation until its reader-facing purpose is recorded.

#Client to server

Message	Purpose	Fields
`addContentPack`	Add a content pack to the world's available pack list.	`pack`: object `worldId`: string
`addMember`	Add an existing user to a world with a role.	`role`: `gm` or `player` `username`: string `worldId`: string
`assignCharacter`	Assign or unassign a projected actor document for a member.	`actorId`: string or null `userId`: string `worldId`: string
`audioControl`	Adjust or stop authoritative table-audio playback.	`command`: one of several defined shapes `requestId`: string `sourceModId`: string (optional) `worldId`: string
`audioCreateBinding`	Create a validated scene or handout audio binding.	`binding`: object `name`: string `requestId`: string `sourceModId`: string (optional) `worldId`: string
`audioCreateDefinition`	Create a validated persistent audio definition.	`definition`: one of several defined shapes `name`: string `requestId`: string `sourceModId`: string (optional) `worldId`: string
`audioDeleteBinding`	Delete an audio binding when the caller may manage audio.	`documentId`: string `requestId`: string `sourceModId`: string (optional) `worldId`: string
`audioDeleteDefinition`	Delete an audio definition when the caller may manage audio.	`documentId`: string `requestId`: string `sourceModId`: string (optional) `worldId`: string
`audioParticipation`	Record whether this member joined or declined table audio.	`state`: `joined` or `declined` or `unavailable` `worldId`: string
`audioPlay`	Start one server-resolved audio definition for an authorized audience.	`audience`: object `definitionId`: string `fadeMs`: number `mode`: `start` or `resume` or `restart` or `crossfade` `requestId`: string `sourceModId`: string (optional) `worldId`: string
`audioUpdateBinding`	Replace a validated audio binding at an expected revision.	`baseRev`: number `binding`: object `documentId`: string `name`: string (optional) `requestId`: string `sourceModId`: string (optional) `worldId`: string
`audioUpdateDefinition`	Replace a validated audio definition at an expected revision.	`baseRev`: number `definition`: one of several defined shapes `documentId`: string `name`: string (optional) `requestId`: string `sourceModId`: string (optional) `worldId`: string
`cardAction`	Invoke one server-owned action attached to a chat card.	`buttonId`: string `cardId`: string `worldId`: string
`chat`	Post a chat message to its declared audience.	`emote`: boolean (optional) `quotes`: string (optional) `text`: one of several defined shapes `to`: array of string (optional)
`chatHistory`	Request an older page of projected chat entries.	`before`: string (optional) `limit`: number (optional) `worldId`: string
`commitSystemGenerator`	Re-run an approved generator preview and create its document idempotently.	`request`: object
`create`	Create a document from a registered type and its validated defaults.	`data`: unknown value (optional) `documentType`: string `history`: object (optional) `mutationId`: string (optional) `name`: string `packageSource`: object (optional)
`createWorld`	Create a world using a system available in the server registry.	`name`: string `systemId`: string
`delete`	Delete a document when the caller has authority.	`documentId`: string `history`: object (optional) `mutationId`: string (optional) `permanent`: boolean (optional)
`dismissPresentation`	Dismiss a current table presentation for this reader.	`id`: string `worldId`: string
`enableMod`	Enable or disable an installed mod for the world.	`enabled`: boolean `modId`: string `worldId`: string
`endPresentation`	End the GM's current presentation for the table.	`id`: string `worldId`: string
`executeGameAction`	Execute one installed action as an atomic actor, target, roll and chat transaction.	`invocation`: one of several defined shapes
`forgetHistory`	Remove a History entry from the caller's undo and redo projection.	`entryId`: string `worldId`: string
`forkPackageLibraryEntry`	Create an editable world definition from one exact mounted library entry.	`name`: string (optional) `ref`: object `requestId`: string `worldId`: string
`getLayout`	Read this member's saved dock layout for a world.	`worldId`: string
`getPackageLibraryEntry`	Hydrate one exact immutable entry from a mounted package library.	`ref`: object `requestId`: string `worldId`: string
`getTourProgress`	Read this member's authenticated guided-tour progress and offer preference.	`requestId`: string `worldId`: string
`hello`	Authenticate and negotiate the protocol version.	`protocolVersion`: number `token`: string
`historyBoundary`	Mark the start or end of one user-visible History operation.	`groupId`: string (optional) `worldId`: string
`inspectHistory`	Read the caller's projected History entries.	`userId`: string `worldId`: string
`installMod`	Install a validated mod manifest for the world.	`mod`: object `worldId`: string
`joinWorld`	Join a world lobby connection to one world session.	`worldId`: string
`leaveWorld`	Leave the active world session while keeping the connection.	None
`listWorlds`	List worlds available to the authenticated user.	None
`markContentPackImported`	Record that a listed content pack was imported into this world.	`importedVersion`: string `packId`: string `worldId`: string
`mutateSceneEntries`	Apply one validated batch to drawings, images, walls, lights, or tokens.	`batch`: object
`packageServiceCall`	Call one graph-pinned, typed package service endpoint as the current user.	`callerPackageId`: string `endpoint`: string `kind`: `action` or `query` `payload`: unknown value `requestId`: string `serviceId`: string `worldId`: string
`patch`	Apply validated document patch operations at an expected revision.	`patch`: object
`postCard`	Post a validated rich card while retaining its actions on the server.	`lead`: string (optional) `modId`: string `spec`: unknown value `worldId`: string
`postTablePreview`	Post a previously authorized Roll Table preview result to Chat.	`previewId`: string
`present`	Present projected Library material to the table.	`documentId`: string `pageId`: string or null `to`: array of string or null `worldId`: string
`previewAs`	Ask the server for a world snapshot projected as another member.	`userId`: string `worldId`: string
`previewSystemGenerator`	Run one installed seeded generator without changing world state.	`request`: object
`previewTable`	Draw a private, server-authoritative Roll Table preview.	`requestId`: string `tableId`: string
`queryPackageLibrary`	Search or page the bounded index of a mounted package library.	`query`: object `requestId`: string `worldId`: string
`redo`	Replay one eligible operation from the caller's redo stack.	`worldId`: string
`removeContentPack`	Remove a content pack from the world's available pack list.	`packId`: string `worldId`: string
`removeMember`	Remove a member from a world.	`userId`: string `worldId`: string
`resetExploredFog`	Clear persisted exploration memory for the selected scope.	`sceneId`: string `userId`: string (optional)
`resolveDefinition`	Hydrate one exact installed or projected-world content reference.	`ref`: one of several defined shapes `requestId`: string `worldId`: string
`roll`	Request a server-authoritative dice result for a declared audience.	`context`: keyed object (optional) `formula`: string `label`: string (optional) `to`: array of string (optional)
`runModAction`	Invoke a validated semantic action contributed by an enabled mod.	`actionId`: string `documentId`: string (optional) `modId`: string `worldId`: string
`runScript`	Run a named active-system automation script for a document.	`args`: unknown value (optional) `documentId`: string `scriptId`: string
`searchDefinitions`	Search exact installed libraries and their visible world definition types through one paged result.	`query`: object `requestId`: string `worldId`: string
`setAccess`	Change document grants, defaults, or page visibility.	`defaultPermission`: number (optional) `documentId`: string `grants`: keyed object (optional) `history`: object (optional) `mutationId`: string (optional) `pageVisibility`: array of object (optional) `worldId`: string
`setActiveScene`	Select the world's active scene.	`sceneId`: string `worldId`: string
`setChatClosed`	Open or close Chat for players at the world level.	`closed`: boolean `worldId`: string
`setLayout`	Persist this member's dock layout for a world.	`layout`: string or null `worldId`: string
`setModGrants`	Replace the GM-approved bridge capabilities for an installed mod.	`grants`: array of string `modId`: string `worldId`: string
`setModSetting`	Write one validated user- or world-scoped mod setting.	`key`: string `modId`: string `value`: one of several defined shapes or null `worldId`: string
`setPolicy`	Change a world action policy when the caller is a GM.	`action`: string `role`: `gm` or `player` `worldId`: string
`setSceneState`	Change authoritative scene navigation or presentation state.	`capability`: string `documentId`: string `history`: object (optional) `modId`: string `mutationId`: string (optional) `permanent`: boolean (optional) `value`: unknown value
`setTourPreferences`	Enable or disable automatic first-party tutorial offers for this member.	`automaticOffers`: boolean `requestId`: string `worldId`: string
`setTourProgress`	Monotonically persist one authenticated guided-tour progress record.	`progress`: object `requestId`: string `worldId`: string
`shareMeasurement`	Broadcast or clear the caller's temporary map measurement.	`path`: array of object or null `sceneId`: string
`undo`	Revert one eligible operation from the caller's undo stack.	`worldId`: string
`uninstallMod`	Remove an installed mod and its active grants from the world.	`modId`: string `worldId`: string
`unsend`	Remove one eligible chat entry authored by the caller.	`entryId`: string `worldId`: string
`updateDiceProfile`	Replace this connection's per-die selections with a fresh signed world token.	`token`: string

#Server to client

Message	Purpose	Fields
`activeScene`	Broadcast the selected active scene id.	`sceneId`: string or null `worldId`: string
`assignedCharacters`	Deliver the member-to-character assignments visible to this reader.	`assignments`: keyed object `worldId`: string
`audioCommandResult`	Acknowledge or refuse one correlated audio management or playback command.	`error`: string (optional) `ok`: boolean `requestId`: string `worldId`: string
`audioParticipants`	Deliver table members' joined, declined, or unavailable audio state without local volume.	`participants`: array of object `worldId`: string
`audioState`	Deliver authoritative playback instances projected for this reader.	`instances`: array of object `worldId`: string
`chat`	Deliver a projected legacy chat message.	`at`: number `from`: string `text`: string
`chatClosed`	Broadcast whether players may currently use Chat.	`closed`: boolean `worldId`: string
`contentPacks`	Deliver the world's available content-pack records.	`contentPacks`: array of object `worldId`: string
`created`	Deliver a newly created document projected for this reader.	`document`: unknown value `mutationId`: string (optional) `source`: `local` or `remote` or `undo` or `redo` (optional)
`definitionResult`	Return or refuse one correlated additive definition search or hydration.	`error`: string (optional) `ok`: boolean `requestId`: string `result`: one of several defined shapes (optional) `worldId`: string
`deleted`	Confirm that a document was removed.	`documentId`: string `mutationId`: string (optional) `source`: `local` or `remote` or `undo` or `redo` (optional)
`diceProfileUpdated`	Confirm the signed per-die profile now active on this connection.	`revision`: number `selections`: object
`entries`	Deliver a page of projected event-stream entries.	`entries`: array of object `more`: boolean `worldId`: string
`entry`	Deliver one new projected event-stream entry.	`entry`: object `worldId`: string
`error`	Report a connection or request error that has no optimistic mutation id.	`message`: string
`gameActionResult`	Return the committed or refused result of one idempotent game action.	`duplicate`: boolean (optional) `error`: string (optional) `mutationId`: string `ok`: boolean `outcome`: object (optional) `worldId`: string
`history`	Deliver this member's projected undo and redo history.	`snapshot`: object `worldId`: string
`joined`	Confirm the active world and deliver its initial projected state.	`activeSceneId`: string or null `assignedCharacters`: keyed object `audio`: array of object `audioParticipants`: array of object `chatClosed`: boolean `contentPacks`: array of object `diceProfileRevision`: number (optional) `diceSkinIds`: object (optional) `entries`: array of object `history`: object (optional) `members`: array of object `modSettings`: keyed object `modules`: array of object `moreEntries`: boolean `policy`: keyed object `presentations`: array of object `role`: `gm` or `player` `system`: object `testWorld`: object or null `worldId`: string `worldName`: string
`layout`	Deliver this member's saved dock layout.	`layout`: string or null `worldId`: string
`members`	Deliver the current world member list.	`members`: array of object `worldId`: string
`modActionAccepted`	Acknowledge an accepted semantic mod action.	`actionId`: string `documentId`: string (optional) `modId`: string `worldId`: string
`modSettings`	Deliver projected mod settings for this user and world.	`values`: keyed object `worldId`: string
`modules`	Deliver the active system contract and enabled module summaries.	`modules`: array of object `worldId`: string
`packageLibraryResult`	Return or refuse one correlated package-library query or entry read.	`error`: string (optional) `ok`: boolean `requestId`: string `result`: one of several defined shapes (optional) `worldId`: string
`packageServiceResult`	Return or refuse one correlated package service call.	`error`: object (optional) `ok`: boolean `requestId`: string `value`: unknown value (optional) `worldId`: string
`patched`	Broadcast projected document patch operations and the new revision.	`documentId`: string `mutationId`: string (optional) `ops`: array of one of several defined shapes `rev`: number `source`: `local` or `remote` or `undo` or `redo` (optional)
`policy`	Deliver the current world action policy.	`policy`: keyed object `worldId`: string
`presentations`	Deliver table presentations visible to this reader.	`presentations`: array of object `worldId`: string
`previewSnapshot`	Deliver a temporary world snapshot projected as the requested member.	`documents`: array of unknown value `exploredRegion`: array of array of array of [unknown, unknown] `region`: array of array of object `userId`: string `visionActive`: boolean
`rejected`	Reject an optimistic mutation with its correlation id and reason.	`documentId`: string `mutationId`: string (optional) `reason`: string
`rolled`	Deliver a projected server-authoritative dice result.	`result`: intersection
`sceneEntriesMutated`	Broadcast a validated scene-entry batch and resulting revision.	`capability`: string `collection`: string `documentId`: string `history`: object (optional) `mutationId`: string `mutations`: array of one of several defined shapes `related`: array of object (optional) `rev`: number
`sharedMeasurement`	Broadcast or clear one member's temporary map measurement.	`gmUserId`: string `path`: array of object or null `sceneId`: string `worldId`: string
`snapshot`	Deliver the current projected document snapshot for the joined world.	`documents`: array of unknown value
`systemGeneratorCommitResult`	Return or refuse one idempotent generated-document commit.	`document`: unknown value (optional) `duplicate`: boolean (optional) `error`: string (optional) `mutationId`: string `ok`: boolean `preview`: object (optional) `worldId`: string
`systemGeneratorPreviewResult`	Return or refuse one correlated deterministic generator preview.	`error`: string (optional) `ok`: boolean `preview`: object (optional) `requestId`: string `worldId`: string
`tablePreviewed`	Return a private authoritative Roll Table preview to its requester.	`preview`: object `requestId`: string
`testWorld`	Deliver the durable private test-world marker and its exact candidate package graph.	`testWorld`: object or null `worldId`: string
`tourPreferencesSaved`	Acknowledge or refuse one guided-tour offer-preference write.	`automaticOffers`: boolean (optional) `error`: string (optional) `ok`: boolean `requestId`: string
`tourProgress`	Deliver this member's guided-tour progress and offer preference.	`automaticOffers`: boolean (optional) `error`: string (optional) `ok`: boolean `records`: array of object (optional) `requestId`: string `worldId`: string
`tourProgressSaved`	Acknowledge or refuse one monotonic guided-tour progress write.	`error`: string (optional) `ok`: boolean `record`: object (optional) `requestId`: string
`undoable`	Report whether this member currently has an operation to undo or redo.	`label`: string or null `worldId`: string
`unsent`	Confirm that an event-stream entry was removed.	`entryId`: string `worldId`: string
`vision`	Deliver server-computed visible and explored map regions for this reader.	`active`: boolean `conceal`: array of string `exploredRegion`: array of array of array of [unknown, unknown] `region`: array of array of object `reveal`: array of unknown value `sceneId`: string or null `visibleTokenIds`: array of string `worldId`: string
`welcome`	Confirm authentication, protocol negotiation, and lobby state.	`protocolVersion`: number `systems`: array of object `userId`: string `worlds`: array of object
`worlds`	Deliver worlds available to the authenticated user.	`systems`: array of object `worlds`: array of object

Was this page helpful?