Revisioned delta runtime: character_state_updated

MMO Project supports two delivery modes for character state updates after inventory, equipment, status, and skill mutations. Legacy mode sends a full world_snapshot after every mutation. Delta mode sends lightweight character_state_updated messages that contain only the streams that changed, identified by a monotonically increasing revision number. Both modes can coexist on the same server.

Opting in

The client sends runtime_delta_protocol: 1 as part of login_request to enroll the session in delta mode:

{
  "type": "login_request",
  "payload": {
    "account_name": "player1",
    "password": "hunter2",
    "protocol_version": "v1",
    "runtime_delta_protocol": 1
  }
}

Clients that omit runtime_delta_protocol or send null remain in legacy snapshot-refresh mode for the duration of that session. The mode is fixed at login and cannot change mid-session. Both delta and legacy clients receive one full world_snapshot immediately after enter_world_response. That snapshot seeds the initial revision values for delta clients.

character_state_updated S→C

Sent only to delta clients after a committed inventory, equipment, status, skill, or private-ground-item mutation. Each message contains only the streams that changed; unchanged streams are null.

{
  "type": "character_state_updated",
  "payload": {
    "character_id": "c9d0e1f2-...",
    "character_revision": 6,
    "changes": {
      "inventory": { "slot_count": 28, "columns": 4, "items": [ ] },
      "equipment": null,
      "status": null,
      "skills": null,
      "private_ground_items": null
    }
  }
}

character_id

string

The character whose state changed.

character_revision

integer

Monotonically increasing revision number for this character’s stream. Each committed mutation increments this value by exactly one.

changes

object

An object containing one field per tracked stream. A null value means that stream did not change in this mutation.

Show changes fields

inventory

object | null

Updated inventory snapshot. Present when inventory changed. Same structure as world_snapshot.player.inventory: slot_count, columns, and items array with full item detail including skill_requirements, skill_modifiers, and context_actions.

equipment

object | null

Updated equipment snapshot. Present when any equipment slot changed. Same structure as world_snapshot.player.equipment: a slots array with slot_id, display_name, sort_order, item_id, item_name, icon_texture_path, skill_requirements, and skill_modifiers.

status

object | null

Updated status bars. Present when health, concentration, or special values changed. Same structure as world_snapshot.player.status: character_name, health_current, health_max, concentration_current, concentration_max, special_current, special_max.

skills

object | null

Updated skill snapshot. Present when any skill value changed. Same structure as world_snapshot.player.skills: an items array with skill_id, display_name, category, sort_order, base_value, equipment_modifier, temporary_modifier, effective_value.

private_ground_items

array | null

Updated list of owner-only ground items not yet publicly visible. Present when a private drop or pickup changed the owner’s private item list. Same shape as world_snapshot.ground_items entries.

Revision tracking

Delta clients maintain two revision counters:

Counter	Source messages
`character_revision`	`world_snapshot`, `character_state_updated`
`map_revision`	`world_snapshot`, `movement_applied`, `player_state_update`, `npc_state_update`, `ground_item_spawned`, `ground_item_removed`

On every message that carries a revision, the client checks:

received_revision == last_seen_revision + 1

If this invariant holds, the client updates its stored value and applies the change. If the received revision is not exactly last_seen + 1, a message was lost or delivered out of order. The client must trigger a resync.

Map stream messages

Public ground-item changes are delivered as map stream events to all players on the map — including both delta and legacy clients:

ground_item_spawned — a dropped item has become publicly visible; carries map_revision
ground_item_removed — a ground item was picked up or otherwise removed; carries map_revision

Delta clients track map_revision from these messages the same way they track it from movement_applied, player_state_update, and npc_state_update.

Resync

When a delta client detects a revision gap, it sends world_resync_request with its last-known revision values and a description of the problem:

streams

array

required

The stream names believed to be stale. For example ["inventory"], ["map"], or ["inventory", "map"].

character_revision

integer

required

The last character_revision value the client successfully applied.

map_revision

integer

required

The last map_revision value the client successfully applied.

reason

string

required

A descriptive string identifying the cause, e.g. "character_revision_gap" or "map_revision_gap".

Example:

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

The server responds with a fresh world_snapshot that resets both character_revision and map_revision to their current authoritative values. This is the only recovery mechanism for stale streams in this protocol slice.

Legacy fallback

Legacy clients — those that did not send runtime_delta_protocol: 1 on login_request — continue to receive a full world_snapshot after every inventory, equipment, status, or skill mutation. They do not receive character_state_updated messages. Delta clients never receive mutation-triggered world_snapshot messages. They receive only the initial enter-world snapshot and resync snapshots. All subsequent state changes arrive as character_state_updated deltas or map stream events.

Snapshot fields carrying revisions

The following messages carry revision values that delta clients must track:

Message	Revision field
`world_snapshot`	`character_revision`
`world_snapshot`	`map_revision`
`character_state_updated`	`character_revision`
`movement_applied`	`map_revision`
`player_state_update`	`map_revision`
`npc_state_update`	`map_revision`
`ground_item_spawned`	`map_revision`
`ground_item_removed`	`map_revision`

The temporary_modifier field on skill entries is currently always 0. This field is reserved for future buffs, debuffs, stances, and techniques. Clients should read and store it but must not display non-zero values from it until that system is implemented.

Protocol Overview

Messages

Revisioned delta runtime: character_state_updated

Opting in

character_state_updated S→C

Revision tracking

Map stream messages

Resync

Legacy fallback

Snapshot fields carrying revisions

Build docs developers (and LLMs) love

Protocol Overview

Messages

Documentation Index

​Opting in

​character_state_updated S→C

​Revision tracking

​Map stream messages

​Resync

​Legacy fallback

​Snapshot fields carrying revisions

Build docs developers (and LLMs) love

Opting in

character_state_updated S→C

Revision tracking

Map stream messages

Resync

Legacy fallback

Snapshot fields carrying revisions