Add autonomous world runtime

docs/unreal-world-sync.md

@@ -0,0 +1,143 @@
+# Unreal World Sync
+
+This document defines the recommended integration contract between `clawgo` and an Unreal Engine client.
+
+See also:
+
+- [Unreal Bridge Example](/Users/lpf/Desktop/project/clawgo/docs/unreal-bridge-example.md)
+
+## 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:
+
+```json
+{
+  "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