clawgo/docs/unreal-world-sync.md

Unreal World Sync

This document defines the recommended integration contract between clawgo and an Unreal Engine client.

See also:

• Unreal Bridge Example

Authority

• clawgo remains the authoritative world server.
• Unreal is a renderer and input client.
• Web and Unreal should consume the same world APIs and action APIs.

Read Path

Unreal should subscribe to:

• GET /api/world
• runtime websocket snapshots from /api/runtime

Key world payloads to consume:

• world_id
• tick
• locations
• entities
• rooms
• occupancy
• entity_occupancy
• room_occupancy
• npc_states
• recent_events

Write Path

Player-originated actions should map to:

• world_player_action
  • move
  • speak
  • interact
  • quest_accept
  • quest_progress
  • quest_complete

World admin / god-view edits should map to:

• world_entity_update
• world_entity_create
• world_npc_create
• world_quest_create

Placement Contract

Entities expose a stable placement payload:

{
  "id": "bench",
  "location_id": "commons",
  "placement": {
    "model": "entity.table",
    "scale": [1.2, 1.2, 1.2],
    "rotation": [0, 1.57, 0],
    "offset": [0.8, 0, -0.4]
  }
}

Interpretation:

• model: shared logical asset key
• scale: local model scale
• rotation: radians, XYZ order
• offset: local offset inside the owning location

Unreal should treat location_id + offset as the effective placement anchor.

Asset Pipeline

Recommended source workflow:

1. Author in Blender / Maya / DCC source files.
2. Export web assets as GLB.
3. Export Unreal assets as FBX or Unreal-preferred import format.
4. Keep the logical asset key the same across clients.

Example:

• logical key: entity.table
• web asset: /models/furniture/table.glb
• unreal asset: /Game/World/Furniture/SM_Table

Animation Contract

Recommended shared action set for humanoid characters:

• Idle
• Walk
• Talk
• Interact

Unreal should choose animations from world state intent/status:

• idle state -> Idle
• moving between anchors -> Walk
• speaking event -> Talk
• room/task work -> Interact

Rooms

Rooms are task execution spaces created by the world mind.

Unreal should render them as:

• isolated interior pods
• task sub-scenes
• linked challenge spaces

Use:

• rooms
• room_occupancy

to render membership and lifecycle.

Replication Model

Do not replicate game authority into Unreal.

Recommended flow:

1. Unreal receives latest snapshot.
2. Unreal interpolates transforms locally.
3. Unreal submits user actions back to clawgo.
4. clawgo arbitrates and publishes the new truth.

This keeps:

• world logic in one place
• web and Unreal behavior aligned
• NPC autonomy consistent across clients