Persistent Interactive World Objects

What This System Is

Persistent world objects are data-driven state machines for chests, resource nodes, doors, switches, destructibles, and quest props. A scene still owns placement and interaction targeting; assets/gameplay/world_object_catalog.json owns state, visual variant, collision intent, transitions, rewards, events, respawn timing, and persistence scope.

How Authors Use It

1. Add a definition to the world-object catalog. Choose per_player, per_party, per_instance, or global scope and define an initial state.
2. Give each state a stable id, renderer-facing visual_variant, contextual prompt, collision_enabled, and interactable flag.
3. Add transitions with from_state_id, to_state_id, optional shared gameplay conditions, item grants, runtime events, cooldown, and optional respawn_after_ms.
4. Add a world interaction whose action is {"kind":"world_object","definition_id":"<id>"}.
5. In the scene trigger workbench choose Persistent Chest, Resource Node, Stateful Door, or Stateful Switch and place the interaction target on the object.

The shipped examples cover a one-time per-player starter cache, a per-player iron node with a 30-second respawn, and instance-scoped door and switch toggles.

Rules And Invariants

The server resolves the scene trigger and world-interaction range/conditions first. It then derives a scope key from the placed trigger id plus player, party, hosted instance, or global owner. Per-player records live in the durable authoritative character state. Shared records are serialized through the realtime scoped registry and copied into each matching character's durable state, allowing a returning participant to restore the latest known shared revision after a host restart.

After a transition is accepted, item grants use the existing idempotent inventory transaction path. Only then does authority commit the new object record, advance its revision, record transition events, and replicate the state id, revision, and optional respawn deadline in the gameplay-condition snapshot. The client uses those fields to select the authored prompt and visual/collision projection, including locally materializing the initial presentation when a respawn deadline elapses. Authority performs the same materialization before the next interaction.

Validation And Debugging

Validate the world-object catalog whenever definitions, states, transitions, grants, or scopes change. Check that trigger ids, persistence scope, grants, event ids, and respawn timing match the intended authority behavior before testing client presentation.

Examples

{
  "id": "node.iron_outcrop",
  "label": "Iron Outcrop",
  "kind": "resource_node",
  "scope": "per_player",
  "initial_state_id": "available",
  "states": [
    {"id":"available","visual_variant":"iron_outcrop.full","prompt":"Mine iron","collision_enabled":true,"interactable":true},
    {"id":"depleted","visual_variant":"iron_outcrop.depleted","prompt":"Iron regrowing","collision_enabled":false,"interactable":false}
  ],
  "transitions": [
    {
      "id": "harvest",
      "from_state_id": "available",
      "to_state_id": "depleted",
      "respawn_after_ms": 30000,
      "grants": [{"item_id":"iron_ore","quantity":2}],
      "event_ids": ["world_object.iron_harvested"]
    }
  ]
}

Transition conditions use the same authored condition language as quests, dialogue, services, events, and world interactions.

Related Systems

• World Interactions And Activity Boards
• World Mechanism And Puzzle Graphs
• Trigger Permissions, Targeting, And Action Pipelines