cyberia 3.2.9 → 3.2.22

package/src/client/public/cyberia-docs/ARCHITECTURE.md

@@ -1,443 +1,305 @@
-# Cyberia Online — System Architecture
+# Cyberia — Architecture
 
-**Version:** 3.0.3 | **Status:** Current
+Cyberia is the real-time MMO extension that runs on Underpost Platform. This document describes the three Cyberia processes, their boundaries, the data flow between them, and the canonical model for tick, snapshot, prediction, reconciliation, interpolation, and replication.
+
+Underpost Platform provides the toolchain, deployment surface, PWA delivery, and base infrastructure. The three Cyberia processes operate on top of it.
 
 ---
 
-## Overview
+## Process model
 
-Cyberia Online is a real-time tap-based sandbox MMORPG built on three independent service layers communicating through well-defined binary and gRPC protocols. The system separates concerns across:
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  UNDERPOST PLATFORM (infra · toolchain · deploy · PWA/Workbox)          │
+│                                                                          │
+│  ┌─────────────────────┐                                                 │
+│  │ Persistent backend  │   ← Cyberia content authority + asset backend   │
+│  │ ──────────────────  │                                                 │
+│  │  engine-cyberia     │     Node.js                                     │
+│  │  MongoDB            │                                                 │
+│  │  IPFS / Cloudinary  │                                                 │
+│  │  ObjectLayerToken   │     Hyperledger Besu (off-line dependency)      │
+│  └─────────┬───────────┘                                                 │
+│            │ gRPC (world load, hot reload)                               │
+│            ▼                                                             │
+│  ┌─────────────────────┐                                                 │
+│  │ Authoritative       │   ← Cyberia simulation authority                │
+│  │ simulation runtime  │                                                 │
+│  │ ──────────────────  │                                                 │
+│  │  cyberia-server     │     Go                                          │
+│  └─────────┬───────────┘                                                 │
+│            │ WebSocket (binary AOI snapshots, typed input commands)      │
+│            ▼                                                             │
+│  ┌─────────────────────┐                                                 │
+│  │ Presentation        │   ← Cyberia render + prediction client          │
+│  │ runtime             │                                                 │
+│  │ ──────────────────  │                                                 │
+│  │  cyberia-client     │     C / WebAssembly (Raylib · Emscripten)       │
+│  └─────────────────────┘                                                 │
+│            │                                                             │
+│            │ REST (atlas frames, asset metadata, optional client hints)  │
+│            └──→ engine-cyberia                                           │
+└─────────────────────────────────────────────────────────────────────────┘
+```
 
-1. **Engine-Cyberia** (Node.js) — data persistence, gRPC data service, REST API, CI/CD tooling.
-2. **cyberia-server** (Go) — real-time multiplayer game logic, binary WebSocket AOI protocol.
-3. **cyberia-client** (C/WASM) — game rendering client compiled to WebAssembly.
+Three processes, strict role separation. The ecosystem is fully operational only when all three are running and healthy at the same time.
 
 ---
 
-## High-Level System Diagram
-
-```mermaid
-graph TB
-    subgraph Client["cyberia-client (C/WASM)"]
-        SDL["SDL2 + OpenGL ES2\nRendering Pipeline"]
-        BinDecoder["Binary AOI Decoder"]
-        OLEngine["Object Layer Engine\nAtlas Sprite Compositor"]
-        Input["Tap/Click Input Handler"]
-    end
-
-    subgraph GoServer["cyberia-server (Go)"]
-        WS["WebSocket Server :8081\nBinary AOI Protocol"]
-        AOI["Area of Interest (AOI)\nSpatial Filtering"]
-        PathFinding["A* Pathfinding\n(Bot Navigation)"]
-        Skills["Skill Dispatcher\nProjectile · Doppelganger"]
-        Economy["Economy Module\nFountain & Sink"]
-        gRPCClient["gRPC Client\nWorld Builder"]
-    end
-
-    subgraph Engine["engine-cyberia (Node.js)"]
-        Express["Express REST API\n:4005–4014"]
-        gRPCServer["gRPC Server :50051\nCyberiaDataService"]
-        MongoDB["MongoDB\nMongoose ORM"]
-        Valkey["Valkey\n(Redis-compatible)"]
-        IPFS["IPFS Cluster + Kubo\nAsset Pinning"]
-    end
-
-    subgraph Blockchain["Hyperledger Besu :8545"]
-        OLT["ObjectLayerToken\nERC-1155 Contract"]
-    end
-
-    Client <-->|"WS binary messages\n(little-endian)"| GoServer
-    Client <-->|"REST: atlas PNG\nmetadata JSON"| Engine
-    GoServer <-->|"gRPC :50051\nGetFullInstance\nGetObjectLayerBatch\nGetMapData · Ping"| Engine
-    Engine <-->|"ethers.js\nEIP-712 + ERC-1155"| Blockchain
-    Engine <-->|"IPFS API"| IPFS
-    Engine <-->|"mongoose"| MongoDB
-```
+## Role definitions
 
----
+### engine-cyberia (Node.js) — content authority
 
-## Component Details
+The content-authoring backend and persistence layer for Cyberia. Owns persisted data and exposes it through two transports: gRPC (consumed by `cyberia-server` at boot and during hot reload) and REST (consumed by `cyberia-client` for asset distribution and optional presentation overrides).
 
-### Engine-Cyberia (Node.js)
+What it owns:
 
-The authoritative backend providing all persistent game data through two transport layers:
+- Content generation, validation, and persistence.
+- Maps, portals, object layers, atlas/sprite-sheet metadata.
+- World configuration: AOI radius, economy rules, skill rules, equipment rules, entity gameplay defaults.
+- Persisted character/quest/dialogue/action data.
+- gRPC `CyberiaDataService` for world load and content streaming.
+- REST APIs for assets and the optional client-hints overrides.
+- Static content distribution + Cloudinary-backed asset flow.
+- Editor and CLI integration for content workflows.
 
-**REST APIs (Express):**
+What it does NOT own:
 
-| API                          | Description                                         |
-| ---------------------------- | --------------------------------------------------- |
-| `object-layer`               | CRUD for ObjectLayer documents (AtomicPrefab)       |
-| `object-layer-render-frames` | Atlas frame matrix and color palette documents      |
-| `atlas-sprite-sheet`         | Consolidated atlas PNG + metadata                   |
-| `cyberia-instance`           | Instance graph (maps + portal topology)             |
-| `cyberia-map`                | Map grid, entity placements, metadata               |
-| `cyberia-entity`             | Entity definitions                                  |
-| `cyberia-instance-conf`      | Instance configuration (skills, economy, equipment) |
-| `cyberia-quest`              | Quest definitions                                   |
-| `cyberia-quest-progress`     | Per-player quest progress                           |
-| `cyberia-action`             | NPC action definitions                              |
-| `cyberia-dialogue`           | Dialogue lines                                      |
+- Real-time simulation. It is not a gameplay runtime.
+- Per-tick state advancement.
+- Client presentation policy (palette, camera, dev overlay, icon visuals).
+- World mutation during gameplay.
 
-**gRPC Service (`CyberiaDataService`):**
+### cyberia-server (Go) — authoritative simulation runtime
 
-| RPC                             | Description                                                      |
-| ------------------------------- | ---------------------------------------------------------------- |
-| `GetFullInstance(instanceCode)` | Instance graph + maps + entities + ObjectLayers + InstanceConfig |
-| `GetMapData(mapCode)`           | Single map grid and entity data                                  |
-| `GetObjectLayerBatch()`         | Stream all ObjectLayers (cache warm-up)                          |
-| `GetObjectLayer(itemId)`        | Single ObjectLayer by item ID                                    |
-| `GetObjectLayerManifest()`      | All `itemId + sha256` pairs (hot-reload diff)                    |
-| `Ping()`                        | Engine liveness check                                            |
+The tick-based authoritative simulation. Owns world state and the gameplay rules that mutate it.
 
-**Fallback Instance:** When `GetFullInstance` is called with an unknown instance code, the Engine returns a minimal playable fallback (1 empty 64×64 map, no bots, no ObjectLayers) instead of `NOT_FOUND`.
+What it owns:
 
----
+- Authoritative world state.
+- The tick: a `uint32` advanced once per simulation step at a fixed `tickRate`.
+- Simulation phases — the only allowed mutators of world state.
+- AOI replication: per-player interest filtering and snapshot emission.
+- Input command processing: typed input commands drained from per-player queues each tick.
+- Snapshot generation and delivery via WebSocket.
 
-### cyberia-server (Go)
+What it does NOT own:
 
-Real-time multiplayer game server. Consumes gRPC data at startup, then runs independently:
+- Persistence (loaded once at boot from engine-cyberia).
+- Client presentation. The server holds no palette, no camera knobs, no dev-overlay flag, no status-icon visuals.
 
-```mermaid
-graph LR
-    A["gRPC\nGetFullInstance"] --> B["BuildWorldFromInstance\ninstance_loader.go"]
-    B --> C["Maps + Portals\n+ Entity Registry"]
-    C --> D["Game Loop\nserver.go"]
-    D --> E["AOI Ticks\naoi_binary.go"]
-    E --> F["Binary WS Messages\nto C clients"]
-```
+### cyberia-client (C / WebAssembly) — presentation runtime
 
-**Key source files:**
-
-| File                    | Responsibility                                        |
-| ----------------------- | ----------------------------------------------------- |
-| `server.go`             | WebSocket lifecycle, game loop, player registry       |
-| `aoi_binary.go`         | Binary AOI wire format encoder/decoder                |
-| `object_layer.go`       | ObjectLayer Go types mirroring the MongoDB schema     |
-| `collision.go`          | Grid collision detection, portal transitions          |
-| `pathfinding.go`        | A\* pathfinding for bot navigation                    |
-| `skill.go`              | Skill entry points: tap action trigger, on-kill hooks |
-| `skill_dispatcher.go`   | Skill registry: `InitSkills`, `DispatchSkill`         |
-| `skill_projectile.go`   | Projectile skill handler                              |
-| `skill_doppelganger.go` | Doppelganger skill handler                            |
-| `economy.go`            | Fountain & Sink coin economy                          |
-| `frozen_state.go`       | FrozenInteractionState (modal protection)             |
-| `entity_status.go`      | Entity Status Indicator (ESI) computation             |
-| `life_regen.go`         | HP regeneration loop                                  |
-| `ai.go`                 | Bot AI behavior (hostile/passive)                     |
-| `stats.go`              | Stat aggregation and sum-stats limit enforcement      |
-| `instance_loader.go`    | World reconstruction from gRPC data                   |
-| `handlers.go`           | WebSocket message handlers                            |
-| `grpcclient/`           | gRPC client implementation                            |
+The render and interactive runtime. Compiled to WASM via Emscripten and served as a Progressive Web App through the Underpost Platform delivery pipeline.
 
----
+What it owns:
 
-### cyberia-client (C/WASM)
-
-Game client compiled to WebAssembly with Emscripten. Runs in the browser.
-
-**Key source files:**
-
-| File                         | Responsibility                          |
-| ---------------------------- | --------------------------------------- |
-| `main.c`                     | Entry point, game loop                  |
-| `game_render.c`              | Main rendering pipeline                 |
-| `game_state.c`               | Client-side game state management       |
-| `network.c`                  | WebSocket connection + message dispatch |
-| `binary_aoi_decoder.c`       | Binary AOI message parser               |
-| `object_layer.c`             | ObjectLayer metadata store              |
-| `object_layers_management.c` | Multi-layer management per entity       |
-| `entity_render.c`            | Per-entity layer compositing            |
-| `layer_z_order.c`            | Z-order sorting for rendering           |
-| `ol_as_animated_ico.c`       | Animated Object Layer rendering         |
-| `ol_stack_ico.c`             | Stacked icon rendering                  |
-| `texture_manager.c`          | Atlas texture loading and caching       |
-| `input.c`                    | Tap/click input handling                |
-| `floating_combat_text.c`     | FCT event rendering                     |
-| `inventory_bar.c`            | Bottom inventory bar UI                 |
-| `inventory_modal.c`          | Full inventory modal                    |
-| `entity_overhead_ui.c`       | Nameplate + status icon rendering       |
-| `interaction_bubble.c`       | NPC interaction prompt bubble           |
-| `tap_effect.c`               | Tap visual feedback animation           |
-| `modal_dialogue.c`           | NPC dialogue modal                      |
-| `modal_player.c`             | Player info modal                       |
-| `message_parser.c`           | Server message routing                  |
-
-**Build system:**
-
-```bash
-# Development build
-make -f Web.mk clean && make -f Web.mk web
-
-# Production / release build
-make -f Web.mk clean && make -f Web.mk web BUILD_MODE=RELEASE
-```
+- Rendering and UI.
+- Input capture: raw OS events → typed input commands with monotonic sequence numbers.
+- Prediction of the local player.
+- Reconciliation against authoritative snapshots.
+- Interpolation of remote entities.
+- Presentation defaults (palette, status-icon visuals, camera knobs, interpolation window, dev-overlay flag) — loaded at startup from the client-hints REST endpoint.
+- Optional client-hints fetch for per-instance presentation overrides.
+
+What it does NOT own:
+
+- World simulation.
+- Economy outcomes, combat resolution, skill dispatch decisions.
+- Any state another client depends on for correctness.
 
 ---
 
-## Binary AOI Wire Protocol
+## Runtime operating model
 
-The Go server and C client communicate via a custom little-endian binary WebSocket protocol. Only render-essential data is transmitted; atlas binaries are fetched from the Engine REST API independently.
+The three processes are supervised independently. Each service owns its own monitor and reconnector. The game is playable only when all three are healthy at the same time.
 
-```
-Header (5 bytes):
-  [0]     u8   msgType
-            0x01 = aoi_update   (partial delta update)
-            0x02 = init_data    (full game config on connect)
-            0x03 = full_aoi     (complete world snapshot)
-            0x04 = FCT          (Floating Combat Text, 14 bytes fixed)
-            0x05 = ItemFCT      (Item quantity FCT, variable)
-  [1..2]  u16  reserved (0)
-  [3..4]  u16  entityCount
-
-Per-entity block (variable):
-  [0]     u8   flags
-               bits 0-2: entity type (0=player, 1=bot, 2=floor, 3=obstacle, 4=portal, 5=foreground)
-               bit 3:    removed (entity left AOI)
-               bit 4:    has life data
-               bit 5:    has respawn timer
-               bit 6:    has behavior string
-               bit 7:    has color data (RGBA)
-  [1..36] 36B  entity UUID (zero-padded)
-  -- if not removed: --
-  f32  posX, posY, dimW, dimH
-  u8   direction (0–8: UP, UP_RIGHT, RIGHT, DOWN_RIGHT, DOWN, DOWN_LEFT, LEFT, UP_LEFT, NONE)
-  u8   mode (0=idle, 1=walking, 2=teleporting)
-  -- if bit 4: f32 life, f32 maxLife --
-  -- if bit 5: f32 respawnIn --
-  -- if bit 6: u8 behaviorLen + str behavior --
-  -- if bit 7: u8 r, g, b, a --
-  -- item ID stack: --
-  u8   itemIdCount
-  per item: u8 len + str itemId
-
-Self-player section (appended after entity blocks):
-  <entity block fields>
-  f32  aoiMinX, aoiMinY, aoiMaxX, aoiMaxY
-  u8   onPortal
-  u16  sumStatsLimit
-  u16  activeStatsSum
-  u8+str mapCode
-  u8   pathLen
-  per path point: i16 x, i16 y
-  i16  targetPosX, targetPosY
-  u8+str activePortalID
-  u32  coinBalance
-  <full inventory>
-  u8   frozen (FrozenInteractionState)
-```
+| State      | Meaning                                                              |
+| ---------- | -------------------------------------------------------------------- |
+| `healthy`  | all three Cyberia services are up and connected                      |
+| `degraded` | at least one service is reconnecting or unavailable                  |
+| `standby`  | gameplay is paused because the full three-service set is not healthy |
 
-**FCT message (14 bytes fixed):**
+Dependency between services is handled by supervision and reconnect loops:
 
-| `fctType` | Constant          | Color  | Display        |
-| --------- | ----------------- | ------ | -------------- |
-| `0x00`    | `FCTTypeDamage`   | Red    | `-N` HP lost   |
-| `0x01`    | `FCTTypeRegen`    | Green  | `+N` HP gained |
-| `0x02`    | `FCTTypeCoinGain` | Yellow | `+N` coins     |
-| `0x03`    | `FCTTypeCoinLoss` | Yellow | `-N` coins     |
-| `0x04`    | `FCTTypeItemGain` | Cyan   | `+N ItemID`    |
-| `0x05`    | `FCTTypeItemLoss` | Purple | `-N ItemID`    |
+- `cyberia-server` dials `engine-cyberia` gRPC at boot and exits on dial failure rather than fabricate a world. On reconnect, it reloads world configuration.
+- `cyberia-client` reconnects to `cyberia-server` over WebSocket and re-fetches content from `engine-cyberia` over REST independently.
+- If any one of the three services goes unhealthy, the game moves to standby until all three recover.
 
----
+Underpost Platform deploy orchestration ensures the backend layer is ready before the simulation layer is started, and the simulation layer is ready before the presentation layer connects. This ordering is an infrastructure concern, not a documentation model: the processes themselves are supervised and reconnect without requiring a manual restart chain.
 
-## gRPC Data Pipeline
+---
 
-```mermaid
-graph LR
-    Engine["Node.js Engine\nMongoDB + Express\ngrpc-server.js :50051"]
-    GoServer["Go Game Server\ncyberia-server\ngrpcclient/"]
+## Tick model
 
-    Engine -->|"GetFullInstance\nGetObjectLayerBatch\nGetMapData · Ping\nGetObjectLayerManifest"| GoServer
-```
+The tick is the universal coordinate of the simulation. Every server→client snapshot and every client→server input command carries a tick value.
 
-**Data flow:**
+| Concept                  | Value                                 | Notes                                                                                                   |
+| ------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| **tick**                 | `uint32`                              | Monotonic simulation step counter on `cyberia-server`. Resets only on world rebuild.                    |
+| **tick rate**            | Hz (default `30`)                     | Simulation frequency. Authoritative; comes from world configuration. The string "fps" is never used to describe the server. |
+| **snapshot rate**        | Hz (default `20`)                     | AOI replication frequency. Decoupled from tick rate so bandwidth scales independently of simulation fidelity. |
+| **tick duration**        | `1 / tick_rate`                       | The dt used by every simulation phase.                                                                  |
+| **client tick estimate** | derived                               | Client estimate of the server's current tick, used to stamp outgoing input commands.                    |
+| **render tick**          | `server_tick_estimate − INTERP_TICKS` | The tick the interpolation module samples remote entities at.                                           |
 
-```
-MongoDB (CyberiaInstance + CyberiaMap + ObjectLayer)
-  │
-  ▼
-Node.js Engine (grpc-server.js)
-  │  GetFullInstance → instance graph + maps + entities + ObjectLayers + InstanceConfig
-  │  GetObjectLayerBatch → stream all ObjectLayers
-  │  GetObjectLayerManifest → itemId + sha256 pairs (hot-reload diffing)
-  │  Ping → liveness check
-  ▼
-Go Game Server (world_builder.go → instance_loader.go → server.go)
-  │  ApplyInstanceConfig → sets all game parameters from gRPC
-  │  BuildWorldFromInstance → builds maps, entities, portals
-  │  ReplaceObjectLayerCache → caches ObjectLayer metadata
-  ▼
-C/WASM Client (WebSocket binary AOI protocol)
-  │  init_data → game config, player state, grid dimensions
-  │  metadata → ObjectLayer cache (delivered once after connect)
-  │  aoi_update → binary-encoded entity positions, directions, modes, colors, item stacks
-```
+Three clocks, one tick number: simulation tick (server), snapshot tick (server replication), render frame (client). The tick number is the only synchronization point.
 
 ---
 
-## Instance Topology
+## Simulation phases
 
-A `CyberiaInstance` is a directed graph:
+Inside one simulation tick, `cyberia-server` runs the following phases in fixed order. These are the only functions that mutate authoritative world state:
 
-- **Vertices** = `CyberiaMap` documents (grid-based maps).
-- **Edges** = `PortalEdge` records connecting source cell → target map/cell.
+1. `phaseInput` — drain each player's `InputQueue`; dispatch typed input commands to gameplay handlers.
+2. `phaseLifecycle` — respawn timers, despawn expirations.
+3. `phaseSkills` — skill projectile collisions.
+4. `phaseAI` — bot behaviour decisions.
+5. `phaseMovement` — integrate positions using `tickDuration`.
+6. `phasePortals` — portal entry and teleport.
 
-**Portal modes:**
+A separate ticker runs replication independently of the simulation:
 
-| Mode           | Behavior                                    |
-| -------------- | ------------------------------------------- |
-| `inter-portal` | Teleport to specific cell on target map     |
-| `inter-random` | Teleport to random valid cell on target map |
-| `intra-portal` | Teleport within same map to specific cell   |
-| `intra-random` | Teleport within same map to random cell     |
+- `phaseReplication` — per player: compute AOI, encode snapshot, dispatch. Runs at `snapshotRate`.
 
-**Topology modes:** `linear`, `hub-spoke`, `open`, `grid`.
+Phases never read presentation data. They consume world configuration loaded at boot (gameplay rules) and the input queue.
 
 ---
 
-## Entity Types and Status Indicators
+## Client render frame
 
-### Entity Types
+The render frame runs at vsync. Inside one render frame, `cyberia-client` performs:
 
-| Type           | Behavior              | Description                 |
-| -------------- | --------------------- | --------------------------- |
-| `player`       | interactive           | Local player (self)         |
-| `other_player` | interactive           | Remote players in AOI       |
-| `bot`          | `hostile` / `passive` | AI-controlled entities      |
-| `skill`        | `skill`               | Runtime-spawned projectile  |
-| `coin`         | `coin`                | Runtime-spawned collectible |
-| `floor`        | static                | Terrain tile                |
-| `obstacle`     | static                | Collision tile              |
-| `portal`       | static                | Zone transition trigger     |
-| `foreground`   | static                | Foreground decoration       |
-| `resource`     | extractable           | Exploitable world object    |
-
-### Entity Status Indicator (ESI)
-
-The Go server computes a status `u8` per entity on each AOI tick. The C client renders the corresponding icon above the entity nameplate:
-
-| `id` | Name                 | Icon            | Description                      |
-| ---- | -------------------- | --------------- | -------------------------------- |
-| 0    | `none`               | —               | Skill/coin bots, world objects   |
-| 1    | `passive`            | arrow-down-gray | Non-aggressive bot               |
-| 2    | `hostile`            | arrow-down-red  | Aggressive bot (will aggro)      |
-| 3    | `frozen`             | chat            | Player in FrozenInteractionState |
-| 4    | `player`             | arrow-down      | Normal alive player              |
-| 5    | `dead`               | skull           | Dead / respawning entity         |
-| 6    | `resource`           | arrow-down-gray | Static exploitable resource      |
-| 7    | `resource-extracted` | clock           | Depleted resource (respawning)   |
-| 8    | `action-provider`    | chat (bounce)   | NPC with available actions       |
+1. Poll any pending optional client-hints fetch.
+2. Capture raw input → build typed input command (`kind`, `clientTick`, `sequence`, payload) → apply to prediction → send on the wire.
+3. Reconcile against the latest snapshot: drop input commands ≤ `lastAckedSequence`, rewind self to authoritative position, replay unacked commands.
+4. Fixed-timestep simulation: while accumulator ≥ `tickDuration`, advance prediction one tick.
+5. Interpolation: compute remote-entity view positions at `renderTick`.
+6. Render. Read view models; never mutate world state.
+
+Render frame rate is independent of simulation tick rate. The fixed-timestep accumulator ensures the predicted simulation advances at the authoritative `tickRate` regardless of FPS.
 
 ---
 
-## FrozenInteractionState
+## Wire protocol — AOI snapshot header
+
+Snapshots travel as binary WebSocket frames. The header carries the simulation tick and the per-player acknowledged input sequence.
 
-When a player opens a modal (dialogue, inventory, shop, craft), they enter **FrozenInteractionState**:
+```
+Header (binary, little-endian, 11 bytes for AOI snapshots):
+  [0]       u8   msgType     0x01 = aoi_update, 0x03 = full_aoi
+  [1..4]    u32  tick        simulation tick at which the snapshot was produced
+  [5..8]    u32  lastAcked   highest InputCommand.Sequence applied for this player
+  [9..10]   u16  entityCount entity blocks that follow
+```
 
-- Cannot deal or receive damage.
-- Cannot send or receive movement events.
-- The rest of the world continues normally.
-- Managed exclusively by `FreezePlayer` / `ThawPlayer` in `frozen_state.go`.
+Other message types (init data, FCT) use their own headers and are not part of the per-tick replication stream.
 
 ---
 
-## Skill System
+## Input command pipeline
 
-### Item → Skill Mapping
+Client input flows through a typed pipeline. There is no JSON intermediate on the binary path. The simulation tick is the only consumer.
 
 ```
-CyberiaInstanceConf.skillConfig[]:
-  triggerItemId:  "atlas_pistol_mk2"   ← item in player's active object layers
-  logicEventIds: ["projectile"]        ← ordered handler keys executed in sequence
+WS frame (binary)  →  decode  →  typed InputCommand{kind, clientTick, sequence, payload}
+                                              ↓
+                                              dispatchInputCommand
+                                              ↓
+                                              PlayerState.InputQueue (per-player, bounded)
+                                              ↓
+                       phaseInput (under world mutex, once per simulation tick)
+                                              ↓
+                       phase_input_handlers.go — typed dispatch per InputKind
+                                              ↓
+                       authoritative world state
 ```
 
-### Skill Handlers
+`InputCommand.Sequence` is monotonic per client. The server tracks the highest applied sequence per player; `phaseReplication` writes it into every snapshot header. The client drops acknowledged input commands from its prediction replay buffer using this value.
 
-| `logicEventId`             | Handler                      | Description                                      |
-| -------------------------- | ---------------------------- | ------------------------------------------------ |
-| `projectile`               | `executeProjectileSkill()`   | Spawn a directional projectile entity            |
-| `doppelganger`             | `executeDoppelgangerSkill()` | Spawn a temporary allied duplicate               |
-| `coin_drop_or_transaction` | economy handler              | Spawn a coin entity at target position (economy) |
+---
 
-### Skill Parameters (SkillRules)
+## Presentation metadata ownership
 
-| Parameter                         | Description                                      |
-| --------------------------------- | ------------------------------------------------ |
-| `projectileSpawnChance`           | Probability of spawning a projectile per trigger |
-| `projectileLifetimeMs`            | Projectile lifetime in milliseconds              |
-| `projectileWidth/Height`          | Projectile entity dimensions                     |
-| `projectileSpeedMultiplier`       | Speed relative to base entity speed              |
-| `doppelgangerSpawnChance`         | Probability of spawning a doppelganger           |
-| `doppelgangerLifetimeMs`          | Doppelganger lifetime                            |
-| `doppelgangerSpawnRadius`         | Max spawn distance from player                   |
-| `doppelgangerInitialLifeFraction` | Initial HP as fraction of player max HP          |
+Presentation is client-owned. The authoritative server holds no presentation state.
 
----
+| Concern                                          | Owner                 | Mechanism                                                                       |
+| ------------------------------------------------ | --------------------- | ------------------------------------------------------------------------------- |
+| Palette (named ColorRGBA entries)                | engine-cyberia (REST) | served by `GET /api/cyberia-client-hints/:CYBERIA_CLIENT_HINTS_CODE`. Source schema: `SharedDefaultsCyberia.js`. |
+| Status-icon visuals (icon stems + border colors) | engine-cyberia (REST) | same                                                                            |
+| Per-entity-type fallback color keys              | engine-cyberia (REST) | same                                                                            |
+| Camera defaults (smoothing, zoom)                | engine-cyberia (REST) | same                                                                            |
+| Cell-pixel size, default object dims             | engine-cyberia (REST) | same                                                                            |
+| Interpolation window                             | engine-cyberia (REST) | same                                                                            |
+| Dev-overlay flag                                 | engine-cyberia (REST) | same                                                                            |
+| World configuration (gameplay rules)             | engine-cyberia (gRPC) | `CyberiaInstanceConf` — no presentation; only simulation                        |
 
-## Development Setup
-
-```bash
-# Terminal 1: Engine (Node.js)
-cd /home/dd/engine
-npm run dev
-# Starts Express :4005+, gRPC :50051, connects to MongoDB
-
-# Terminal 2: Go game server
-cd /home/dd/engine/cyberia-server
-cat > .env << 'EOF'
-ENGINE_GRPC_ADDRESS=localhost:50051
-INSTANCE_CODE=cyberia-main
-ENGINE_API_BASE_URL=http://localhost:4005
-SERVER_PORT=8081
-EOF
-go run main.go
-
-# Terminal 3: C/WASM client
-cd /home/dd/engine/cyberia-client
-# Edit src/config.h: WS_URL="ws://localhost:8081/ws", API_BASE_URL="http://localhost:4005"
-source ~/.emsdk/emsdk_env.sh
-make -f Web.mk clean && make -f Web.mk web
-make -f Web.mk serve-development   # http://localhost:8082
-```
+The cyberia-client carries **no** compile-time palette. `domain/presentation_runtime.{c,h}` fetches the full presentation surface on startup; until the fetch settles the runtime returns a tiny inline neutral-grey bootstrap so the splash screen has something to draw. The simulation is unaffected by the fetch outcome.
 
-**Startup order is required:** Engine must start before the Go server dials gRPC; Go server must be running before the C client connects.
+`cyberia-server` never reads any presentation field. The only "representational" data on the simulation wire is the **active item IDs** carried inside each AOI snapshot. Everything else visual is the client's job, fed by the hints REST endpoint.
 
-### Dev Port Summary
+---
 
-| Component           | Port  | Protocol  |
-| ------------------- | ----- | --------- |
-| Engine Express      | 4005+ | HTTP/REST |
-| Engine gRPC         | 50051 | gRPC      |
-| Go server           | 8081  | HTTP + WS |
-| C client dev server | 8082  | HTTP      |
+## Canonical vocabulary
+
+Every Cyberia document uses the same terms. Aliases are not permitted.
+
+| Term                      | Definition                                                                                                                |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| **tick**                  | Monotonic simulation step counter.                                                                                        |
+| **tick rate**             | Simulation Hz on `cyberia-server`.                                                                                        |
+| **snapshot**              | AOI-filtered world view at one tick for one player.                                                                       |
+| **prediction**            | Optimistic local apply of input commands to the predicted self entity.                                                    |
+| **reconciliation**        | Drop acknowledged inputs, rewind self to authoritative position, replay unacked inputs.                                   |
+| **display smoothing**     | Per-render-frame exponential lerp from the discrete predicted self position to a continuous on-screen position. Decouples the visible main player from sim-tick boundaries. |
+| **interpolation**         | Render-time smoothing of remote entities, sampled from snapshot history.                                                  |
+| **authoritative server**  | `cyberia-server`. Sole authority on world state.                                                                          |
+| **content authority**     | `engine-cyberia`. Sole authority on persisted content and world configuration.                                            |
+| **client hints**          | Optional presentation overrides served by engine-cyberia.                                                                 |
+| **world configuration**   | Gameplay parameters loaded at server boot from engine-cyberia.                                                            |
+| **presentation metadata** | Render-only data. Client-owned.                                                                                           |
+| **input command**         | Typed client→server frame with kind, clientTick, sequence, payload.                                                       |
+| **AOI**                   | Area of interest — the spatial filter that defines which entities a given player receives.                                |
+| **replication**           | Production and delivery of snapshots from server to clients.                                                              |
+| **simulation phase**      | A named step inside one simulation tick.                                                                                  |
+| **healthy**               | All three Cyberia services up and connected; game is playable.                                                            |
+| **standby**               | Game paused because at least one of the three services is not healthy.                                                    |
+
+Forbidden usages:
+
+- "fps" on `cyberia-server` (use **tick rate**).
+- "frame-based" simulation language on the server.
+- "game_state" as a god object on the client.
+- Render metadata in `cyberia-server` state.
+- "engine" without qualifier when the project name is intended. Use **engine-cyberia** for the Cyberia content backend; use **Underpost Platform** for the umbrella product.
 
 ---
 
-## Production Deployment
+## Instance topology
 
-### Kubernetes Deployment Order
+A `CyberiaInstance` (persisted in MongoDB, served by engine-cyberia) is a directed graph:
 
-```
-1. Engine (dd-cyberia)    ← Express :4005–4014, gRPC :50051 (cluster-internal)
-2. Go server (mmo-server) ← ENGINE_GRPC_ADDRESS=<engine-clusterIP>:50051
-3. C client (mmo-client)  ← static WASM files served on :8082
-```
+- **Vertices** — `CyberiaMap` documents (grid-based maps).
+- **Edges** — `PortalEdge` records connecting source cell → target map/cell.
 
-### Environment Variables
+Portal modes:
 
-**Go Server:**
+| Mode           | Behaviour                                       |
+| -------------- | ----------------------------------------------- |
+| `inter-portal` | Teleport to a specific cell on a target map     |
+| `inter-random` | Teleport to a random valid cell on a target map |
+| `intra-portal` | Teleport within the same map to a specific cell |
+| `intra-random` | Teleport within the same map to a random cell   |
 
-| Variable                          | Default           | Description                                                               |
-| --------------------------------- | ----------------- | ------------------------------------------------------------------------- |
-| `ENGINE_GRPC_ADDRESS`             | `localhost:50051` | Engine gRPC address (required)                                            |
-| `INSTANCE_CODE`                   | `default`         | Instance code to load on startup                                          |
-| `SERVER_PORT`                     | `8081`            | WebSocket + HTTP server listen port                                       |
-| `STATIC_DIR`                      | `./public`        | Directory for static WASM client files                                    |
-| `ENGINE_GRPC_RELOAD_INTERVAL_SEC` | _(disabled)_      | ObjectLayer hot-reload polling interval                                   |
-| `READY_CMD`                       | _(empty)_         | Shell command to run after server starts (orchestration readiness signal) |
+Topology modes: `linear`, `hub-spoke`, `open`, `grid`.
+
+---
 
-**C Client (compile-time, `src/config.h`):**
+## Entity types
 
-| Constant       | Development              | Production                          |
-| -------------- | ------------------------ | ----------------------------------- |
-| `WS_URL`       | `ws://localhost:8081/ws` | `wss://server.cyberiaonline.com/ws` |
-| `API_BASE_URL` | `http://localhost:4005`  | `https://www.cyberiaonline.com`     |
+| Type           | Behavior              | Description                 |
+| -------------- | --------------------- | --------------------------- |
+| `player`       | interactive           | Local player (self)         |
+| `other_player` | interactive           | Remote players inside AOI   |
+| `bot`          | `hostile` / `passive` | AI-controlled entities      |
+| `skill`        | `skill`               | Runtime-spawned projectile  |