World and movement protocol messages reference

These messages carry world state — the initial snapshot that arrives on session entry, movement requests and authoritative confirmations, player and NPC position broadcasts, and ground item lifecycle events. All field names match the keys in protocol-v1.json and the corresponding C# payload records.

world_snapshot S→C

Sent by the server after enter_world_response and after a successful reconnect_response. Also sent to legacy clients after inventory, equipment, or status mutations. Carries complete authoritative world state for the receiving character’s current map.

{
  "type": "world_snapshot",
  "payload": {
    "session_id": "a1b2c3d4-...",
    "character_id": "c9d0e1f2-...",
    "map_id": "x1000y992",
    "character_revision": 5,
    "map_revision": 18
  }
}

session_id

string

The active session UUID.

character_id

string

The character this snapshot is addressed to.

map_id

string

The map this snapshot covers.

character_revision

integer

The current authoritative character stream revision. Delta clients use this to seed their revision tracking.

map_revision

integer

The current authoritative map stream revision. Delta clients use this to seed their map revision tracking.

player

object

The receiving character’s full local state.

Show player fields

character_id

string

UUID of the local character.

map_id

string

The map the character is on.

tile_x

integer

Current tile X position.

tile_y

integer

Current tile Y position.

facing

string

Facing direction: "north", "south", "east", or "west".

status

object

Character resource bars.

Show status fields

character_name

string

The character’s display name.

health_current

integer

Current health value.

health_max

integer

Maximum health value.

concentration_current

integer

Current concentration value.

concentration_max

integer

Maximum concentration value.

special_current

integer

Current special resource value.

special_max

integer

Maximum special resource value.

skills

object

Skill list with base, modifier, and effective values.

Show skills fields

items

array

Array of skill entries.

Show skill item fields

skill_id

string

Unique skill identifier.

display_name

string

Human-readable skill name for UI.

movement_intent C→S

Sent by the client to request movement to a target tile. The server treats this as world-tile coordinates and resolves the authoritative path using cardinal A* pathing.

{
  "type": "movement_intent",
  "payload": {
    "session_id": "a1b2c3d4-...",
    "character_id": "c9d0e1f2-...",
    "target_tile_x": 15,
    "target_tile_y": 9
  }
}

session_id

string

required

The active session UUID.

character_id

string

required

The UUID of the character requesting movement.

target_tile_x

integer

required

Target world-tile X coordinate. The server resolves the local map/chunk position through the world chunk catalog.

target_tile_y

integer

required

Target world-tile Y coordinate.

movement_applied S→C

Returned by the server after evaluating a movement_intent. Contains the authoritative final position, the movement outcome, and both local-map and world-space coordinates.

{
  "type": "movement_applied",
  "payload": {
    "character_id": "c9d0e1f2-...",
    "map_id": "x1000y992",
    "map_revision": 19,
    "previous_map_id": "x1000y992",
    "tile_x": 15,
    "tile_y": 9,
    "requested_tile_x": 15,
    "requested_tile_y": 9,
    "resolved_target_tile_x": 15,
    "resolved_target_tile_y": 9,
    "previous_tile_x": 12,
    "previous_tile_y": 7,
    "world_tile_x": 1015,
    "world_tile_y": 1001,
    "previous_world_tile_x": 1012,
    "previous_world_tile_y": 999,
    "facing": "east",
    "movement_status": "reached"
  }
}

character_id

string

The character that moved.

map_id

string

The map the character is now on (may differ from previous_map_id on a chunk boundary crossing).

map_revision

integer

Updated map stream revision after this movement is committed.

previous_map_id

string

The map the character was on before this movement step.

tile_x

integer

The character’s authoritative new tile X on map_id.

tile_y

integer

The character’s authoritative new tile Y on map_id.

requested_tile_x

integer

The tile X the client originally requested.

requested_tile_y

integer

The tile Y the client originally requested.

resolved_target_tile_x

integer

The tile X the server resolved as the destination. Differs from requested_tile_x on a "partial" result.

resolved_target_tile_y

integer

The tile Y the server resolved as the destination.

previous_tile_x

integer

The character’s tile X before this movement step.

previous_tile_y

integer

The character’s tile Y before this movement step.

world_tile_x

integer

The character’s new position in world-space tile coordinates.

world_tile_y

integer

The character’s new world-space tile Y.

previous_world_tile_x

integer

The character’s previous world-space tile X.

previous_world_tile_y

integer

The character’s previous world-space tile Y.

facing

string

The character’s facing direction after the move: "north", "south", "east", or "west".

movement_status

string

Authoritative outcome of the movement resolution. One of:

"reached" — the character reached the requested tile
"partial" — the target was clamped to world bounds; the character reached the closest valid tile
"blocked" — no legal path could be found; the character remains at the previous position
"started" — movement toward the target has been queued; further movement_applied messages will follow as the character steps along the path
"stepping" — the character completed one step of a multi-step path; more steps remain

player_state_update S→C

Broadcast to all other players on the same map when a player’s position or state changes. Carries map_revision so delta clients can verify stream continuity.

map_id

string

The map this update applies to.

map_revision

integer

Updated map stream revision.

character_id

string

The player who moved or changed state.

character_name

string

Display name of the player.

tile_x

integer

New tile X position.

tile_y

integer

New tile Y position.

previous_tile_x

integer

Tile X before this update.

previous_tile_y

integer

Tile Y before this update.

facing

string

Facing direction after the update.

current_state

string

Current entity state string, e.g. "idle", "walking".

npc_state_update S→C

Broadcast to all players on the map when an NPC’s position or state changes. Same revision semantics as player_state_update.

map_id

string

The map this update applies to.

map_revision

integer

Updated map stream revision.

npc_id

string

The NPC whose state changed.

display_name

string

NPC display name.

texture_path

string

Asset path for the NPC sprite.

tile_x

integer

New tile X position.

tile_y

integer

New tile Y position.

previous_tile_x

integer

Tile X before this update.

previous_tile_y

integer

Tile Y before this update.

facing

string

Facing direction after the update.

current_state

string

Current NPC state string.

ground_item_spawned S→C

Sent to all players on the map when a ground item becomes publicly visible. Carries map_revision for delta stream continuity.

map_id

string

The map the item spawned on.

map_revision

integer

Updated map stream revision.

ground_item

object

The spawned ground item. Contains: ground_item_id, owner_character_id, map_id, tile_x, tile_y, item_id, item_name, icon_texture_path, stack_count.

ground_item_removed S→C

Sent to all players on the map when a ground item is picked up or otherwise removed from the world.

map_id

string

The map the item was removed from.

map_revision

integer

Updated map stream revision.

ground_item_id

string

The ID of the removed ground item.

world_resync_request C→S

Sent by delta clients when they detect a gap in character_revision or map_revision. The server responds with a fresh world_snapshot.

{
  "type": "world_resync_request",
  "payload": {
    "streams": ["inventory", "map"],
    "character_revision": 14,
    "map_revision": 22,
    "reason": "map_revision_gap"
  }
}

streams

array

required

Names of the streams believed to be stale, e.g. ["inventory"], ["map"], or ["inventory", "map"].

character_revision

integer

required

The last character_revision value the client successfully processed.

map_revision

integer

required

The last map_revision value the client successfully processed.

reason

string

required

A human-readable string describing why the resync was triggered, e.g. "character_revision_gap" or "map_revision_gap".

Protocol Overview

Messages

World and movement protocol messages reference

world_snapshot S→C

movement_intent C→S

movement_applied S→C

player_state_update S→C

npc_state_update S→C

ground_item_spawned S→C

ground_item_removed S→C

world_resync_request C→S

Build docs developers (and LLMs) love

Protocol Overview

Messages

Documentation Index

​world_snapshot S→C

​movement_intent C→S

​movement_applied S→C

​player_state_update S→C

​npc_state_update S→C

​ground_item_spawned S→C

​ground_item_removed S→C

​world_resync_request C→S

Build docs developers (and LLMs) love

world_snapshot S→C

movement_intent C→S

movement_applied S→C

player_state_update S→C

npc_state_update S→C

ground_item_spawned S→C

ground_item_removed S→C

world_resync_request C→S