WSEvent

One message on the WebSocket connection between the app and its clients.

WSEvent is the app’s whole live protocol. The embedded server pushes game state out to the browser player client and the external display, and those clients send edits back, all as events carrying a name and a data payload.

The payload is deliberately untyped (Any?) because its shape depends entirely on the name — a tokenUpdated carries a Token, a tokenMoved carries a Movement, a messageCreated carries a Message. The Codable conformance is hand-written for exactly this reason: init(from:) switches on the name to decode the right type, and encode(to:) switches again to encode it.

Events pair into requests and responses through requestId and responseId, so a client asking a question — getAttribute, say — can match the answer to its question.

SeeAlso: Game, Map, Token, Message

View JSON Schema

Property	Type	Required	Description
`name`	Name	Yes	What this event reports or requests. Determines how `data` is interpreted.
`data`	`any`	No	The event’s payload. Untyped because its shape depends on `name`; the coding methods narrow it.
`requestId`	`string`	No	The sender’s correlation identifier, set on an incoming request. The app echoes it back as the reply’s `responseId`.
`responseId`	`string`	No	The identifier of the request this event answers. `nil` for events broadcast on the app’s own initiative rather than in reply to anything.

Name

What a WSEvent reports or requests.

The name determines the payload type — see the discussion on WSEvent. Names ending in -Updated, -Created and -Deleted are the app broadcasting a change; names in the imperative (createEntity, updateDoor) are a client asking for one.

Type: string — one of:

gameUpdated
mapUpdated
screenUpdated
combatantsUpdated
mapLoaded
systemPaused
mapFrameUpdated
mapViewportUpdated
mapFitScreen
mapFocus
tokenUpdated
tokensUpdated
markerUpdated
markersUpdated
tileUpdated
tilesUpdated
lightUpdated
lightsUpdated
areaEffectUpdated
areaEffectsUpdated
measurementUpdated
measurementsUpdated
mapMoved
tokenMoved
markerMoved
tileMoved
areaEffectMoved
pointerMoved
fogUpdated
drawingsUpdated
lineOfSightUpdated
pointerUpdated
mapVideoControlUpdated
clientConnected
clientDisconnected
clientUpdated
interactionUpdated
reload
messageCreated
messagesUpdated
messageDeleted
createMessage
command
roll
trackedObjectCreated
trackedObjectUpdated
trackedObjectDeleted
trackedObjectsUpdated
createEntity
updateEntity
deleteEntity
entityCreated
entityUpdated
entityDeleted
createCombatant
updateCombatant
deleteCombatant
combatantCreated
combatantUpdated
combatantDeleted
updateDoor
updateToken
getAttribute
setAttribute
app

Source

Who originated an action, for attributing it back to a client.

Property	Type	Required	Description
`id`	`string`	Yes	The originating client’s identifier.
`name`	`string`	No	The client’s display name.
`color`	`string`	No	The client’s accent color, as an RGB string.

Movement

A drag in progress on a map object.

SeeAlso: ControlState

Property	Type	Required	Description
`id`	`string`	Yes	The identifier of the object being moved.
`x`	`integer`	Yes	The object’s horizontal position in map coordinates.
`y`	`integer`	Yes	The object’s vertical position in map coordinates.
`state`	ControlState	Yes	The phase of the drag — whether this is a live update or the final position.
`polygon`	Array<`number`>	No	The token’s visible area at this position, when line of sight is enabled.
`path`	Array<`integer`>	No	The route taken so far, as a flat list of alternating coordinates.
`distance`	`string`	No	The distance travelled, formatted for display. Examples: `"30 ft"`
`animated`	`boolean`	No	Whether the receiver should animate to the new position rather than jump to it.
`source`	Source	No	The client that initiated the drag.

Frame

A viewport position on a map.

Property	Type	Required	Description
`id`	`string`	Yes	The identifier of the map.
`x`	`integer`	No	The horizontal center of the viewport in map coordinates.
`y`	`integer`	No	The vertical center of the viewport in map coordinates.
`zoom`	`number`	No	The zoom level.

Image

An updated image for a map, such as a redrawn fog-of-war mask.

Property	Type	Required	Description
`id`	`string`	Yes	The identifier of the map the image belongs to.
`image`	`string`	Yes	The image itself, encoded for transport.

VideoControl

Playback state for a map’s background video.

Lets every display stay in sync on an animated map.

Property	Type	Required	Description
`state`	`string`	Yes	The playback state. Examples: `"play"`, `"pause"`
`time`	`number`	Yes	The playback position, in seconds.

Focus

A request to draw the players’ attention to a point on the map.

Property	Type	Required	Description
`x`	`integer`	Yes	The horizontal position in map coordinates.
`y`	`integer`	Yes	The vertical position in map coordinates.
`color`	`string`	Yes	The highlight color, as an RGB string.
`effect`	`boolean`	Yes	Whether to play the attention-drawing animation.
`pan`	`boolean`	Yes	Whether to pan the viewport to the point.
`zoom`	`boolean`	Yes	Whether to zoom in on the point.
`reset`	`boolean`	Yes	Whether to restore the previous viewport instead of moving to the point.

Door

A request to change a door’s state.

Opening a door changes what the party can see, so this is applied to the wall mesh and the resulting vision is rebroadcast.

SeeAlso: Wall/DoorState

Property	Type	Required	Description
`mapId`	`string`	Yes	The identifier of the map the door is on.
`id`	`string`	Yes	The identifier of the wall acting as the door.
`state`	DoorState	Yes	The state to set.

Attribute

A request to read or write an entity’s attributes.

Property	Type	Required	Description
`entityId`	`string`	Yes	The identifier of the entity to read from or write to.
`attributes`	`Object`	No	The attributes to write, or the attributes read back in the reply.

ControlState

The phase of a dragging interaction driven over the WebSocket connection.

A drag on a connected client arrives as a stream of events rather than one message, so the receiving side can animate the movement live and then commit it — or discard it if the host refuses the move.

SeeAlso: WSEvent/Movement

View JSON Schema

Type: string — one of:

start
control
end
block
cancel