cyberia 3.2.5 → 3.2.12

package/src/client/public/cyberia-docs/CYBERIA-CLIENT.md

@@ -0,0 +1,291 @@
+<p align="center">
+  <img src="https://www.cyberiaonline.com/assets/splash/apple-touch-icon-precomposed.png" alt="CYBERIA online"/>
+</p>
+
+<div align="center">
+
+<h1>cyberia client</h1>
+
+</div>
+
+**Path:** `cyberia-client/` · **Language:** C11/GNU11 → WebAssembly (Emscripten) · **Role:** presentation runtime for Cyberia
+
+`cyberia-client` is the rendering and interactive runtime for the Cyberia MMO extension on Underpost Platform. It captures input, predicts the local player, reconciles against authoritative snapshots, interpolates remote entities, and renders the world. It owns the render policy locally.
+
+It is **not** a world-simulation authority. The authoritative simulation runs on `cyberia-server`. Persistent content and asset metadata come from `engine-cyberia` via REST.
+
+---
+
+## Operating model
+
+Three independent processes, non-overlapping roles. The ecosystem is playable only when all three are running and healthy at the same time.
+
+```text
+engine-cyberia          cyberia-server          cyberia-client
+content authority       simulation authority    presentation runtime
+  ^ REST                  | WebSocket binary
+  | atlases, asset        | snapshots  (server -> client)
+  | metadata, optional    | input cmds (client -> server)
+  | client hints          v
+  `---------------- Browser tab: prediction, reconciliation, interpolation, render
+```
+
+- Each service owns its own monitor and reconnector.
+- The client reconnects to `cyberia-server` over WebSocket and fetches content from `engine-cyberia` over REST.
+- If any of the three services is unhealthy, the game moves to standby until all three recover.
+
+The client speaks two transports:
+
+- **WebSocket binary** to `cyberia-server` for snapshots and input commands
+- **REST** to `engine-cyberia` for atlas frames, asset blobs, and optional client-hints overrides
+
+Asset distribution flows through Underpost Platform's static and PWA pipeline.
+
+---
+
+## Render loop
+
+The render loop runs at vsync. Tick simulation is decoupled from render frames via a fixed-timestep accumulator. Step ordering inside one render frame:
+
+1. **Optional client hints poll** — advance the asynchronous hints fetch state machine.
+2. **Input capture** — drain raw OS events.
+3. **Input dispatch** — UI hit-test → build typed input command (`kind`, `clientTick`, `sequence`, payload) → apply to prediction → send on the wire.
+4. **Reconciliation** — apply latest snapshot's `lastAcked`: drop acknowledged input commands from the replay buffer; rewind predicted self to authoritative position; replay unacked input commands.
+5. **Fixed-timestep prediction** — while accumulator ≥ `tickDuration`, advance prediction one tick.
+6. **Interpolation** — compute remote-entity view positions at `renderTick = serverTickEstimate − INTERP_TICKS`.
+7. **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.
+
+---
+
+## Module map
+
+Directional dependency: from outermost (UI / render) inward toward `domain/`. Nothing in `domain/` imports outward.
+
+```
+src/
+  domain/
+    tick.h                          tick rate constants, monotonic types
+    presentation_runtime.{c,h}      sole owner of presentation: async fetch of
+                                    /api/cyberia-client-hints/:CYBERIA_CLIENT_HINTS_CODE,
+                                    palette/status-icon/camera accessors, tiny
+                                    inline bootstrap fallback
+  input/
+    input_command.{c,h}             typed InputCommand factory; sequence allocation
+  prediction/
+    prediction.{c,h}                predicted self position; replay buffer; reconcile
+  interpolation/
+    interpolation.{c,h}             remote entity view positions at renderTick
+  network/
+    session.{c,h}                   last server tick, last acked sequence, tick estimate
+    client.{c,h}                    WebSocket lifecycle + binary I/O
+    socket.{c,h}                    Emscripten WebSocket bridge
+  ui/                               modals, HUD, inventory bar, FCT, nameplates
+  game_state.{c,h}                  world state mirror (gameplay subset only)
+  binary_aoi_decoder.{c,h}          server snapshot parser
+  game_render.{c,h}, render.{c,h}   render pipeline
+  main.c                            entry point + render loop
+  js/services.{js,c,h}              REST fetch bridge (atlas, ui-icons, client-hints)
+```
+
+| Owner                         | Owns                                                                                                                                                              | Reads                                          | Writes                                                                                          |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `domain/presentation_runtime` | the entire presentation surface (palette, entity colour keys, status icons, camera, cell, interpolation). Inline bootstrap fallback while the fetch is in flight. | JSON response from `/api/cyberia-client-hints` | own table + one-shot hydration of `g_game_state.cell_size`, `.interpolation_ms`, `.camera.zoom` |
+| `input/input_command`         | typed InputCommand factory                                                                                                                                        | session for tick + sequence                    | —                                                                                               |
+| `prediction/`                 | predicted self position, input replay buffer                                                                                                                      | snapshot self + session ack                    | predicted self                                                                                  |
+| `interpolation/`              | remote entity `interp_pos`                                                                                                                                        | snapshot history                               | remote `interp_pos` only                                                                        |
+| `network/session`             | last server tick, last acked sequence                                                                                                                             | snapshot header                                | session singletons                                                                              |
+| `binary_aoi_decoder`          | wire parser                                                                                                                                                       | binary frames                                  | `game_state` + session + prediction (via callback)                                              |
+| `game_state`                  | gameplay world mirror                                                                                                                                             | —                                              | —                                                                                               |
+| `render/`, `ui/`              | rendering                                                                                                                                                         | view models                                    | screen                                                                                          |
+
+`game_state` holds only the gameplay subset of world state (entities, positions, life, AOI, equipment, frozen flag, coins). It does not carry palette state, status-icon visuals, or any other presentation field.
+
+---
+
+## Presentation ownership
+
+The client owns its render policy. The authoritative server holds no presentation state.
+
+Three layers, strictly inward-dependent:
+
+1. **`domain/presentation_runtime.{c,h}`** — sole owner of every presentation value. Fires a single asynchronous GET against `/api/cyberia-client-hints/:CYBERIA_CLIENT_HINTS_CODE` at startup, polled once per render frame. When the response settles, parses palette, entity colour keys, status-icon visuals, and camera/cell tunings into a process-local table and writes a one-shot hydration into `g_game_state` (cell_size, interpolation_ms, camera.zoom). The C client carries NO compile-time palette or status table — only a tiny inline neutral-grey bootstrap so the splash screen has something to draw while the fetch is in flight. The canonical schema for the response lives at engine-cyberia's `src/client/components/cyberia/SharedDefaultsCyberia.js`.
+2. **Renderers** — call `presentation_runtime_palette("KEY")`, `presentation_runtime_status_icon(u8)`, `presentation_runtime_status_border(u8)`, `presentation_runtime_entity_fallback_color(entity_type)` at each use site.
+
+What lives in this layer:
+
+- Named palette (colors).
+- Per-entity-type fallback color keys.
+- Status-icon visual table (icon stem + border color per numeric ID).
+- Camera smoothing / zoom defaults.
+- Interpolation window.
+- Dev-overlay flag.
+- Viewport screen factors.
+
+What does **not** travel on the WebSocket init or AOI streams:
+
+- Palette.
+- Camera knobs.
+- Dev-overlay flag.
+- Interpolation window.
+- Status-icon visuals.
+- Per-entity-type color keys.
+
+The numeric status-icon u8 still rides on the AOI wire — that is the protocol-level half. The icon stem and border color are presentation and are resolved entirely on the client.
+
+### Optional client hints
+
+`GET /api/cyberia-client-hints/:instanceCode` (engine-cyberia REST, **not** cyberia-server) returns a JSON document mirroring the structure of the compile-time defaults. The client is required to function with no successful call to this endpoint:
+
+- 200 with `{ palette, entityColorKeys, statusIcons, cameraSmoothing, cameraZoom, defaultWidthScreenFactor, defaultHeightScreenFactor, interpolationMs, devUi }` — overrides applied on top of defaults.
+- 404 if the instance has no overrides — defaults are used.
+- Network error — defaults are used.
+
+No authentication; presentation hints are not secret. The Go authoritative server never calls this endpoint.
+
+---
+
+## Tick-aware components
+
+### Session
+
+`network/session.{c,h}` tracks per-connection tick state:
+
+- `last_server_tick` — highest snapshot tick observed.
+- `last_acked_input_sequence` — highest sequence the server has applied for this client; echoed in every snapshot header.
+- `next_input_sequence` — monotonic counter for outgoing input commands.
+- `server_tick_estimate` — extrapolation of last server tick by elapsed wall time, used to stamp outgoing input commands and to compute `renderTick`.
+
+### Prediction
+
+`prediction/prediction.{c,h}` owns the predicted self position. It is the only writer of the predicted state. Internally it tracks **two** positions: the discrete per-tick `predicted_pos` (where the simulation says the player is) and the continuous render-frame `display_pos` (what the renderer reads). The renderer never sees the discrete value.
+
+- `prediction_apply(cmd)` — optimistic local apply of an input command + push onto replay buffer.
+- `prediction_step(dt)` — fixed-timestep advance, called by the accumulator. Mutates `predicted_pos` only.
+- `prediction_reconcile()` — on snapshot arrival: drop acknowledged inputs, rewind self to authoritative position, replay unacked inputs. Mutates `predicted_pos` only.
+- `prediction_display_step(frame_dt)` — per-render-frame exponential lerp of `display_pos` toward `predicted_pos`. This is the layer that absorbs reconcile snaps and sim-tick stepping so the visible main player moves continuously.
+- `prediction_self_position()` — render-time accessor; returns the smoothed `display_pos`.
+
+### Interpolation
+
+`interpolation/interpolation.{c,h}` owns remote-entity render-time positions. It is the only writer of remote `interp_pos`. It never touches the local player (prediction owns that). Sampling happens at `renderTick = serverTickEstimate − INTERP_TICKS`.
+
+### Input command pipeline
+
+```
+mouse / touch / keyboard
+        │
+        ▼
+input/input_capture
+        │
+        ▼
+UI hit-test cascade  ──► modal/inventory/HUD consumed?
+        │  no
+        ▼
+input_command_build_*   stamps client_tick + sequence
+        │
+        ▼
+prediction_apply        optimistic local apply
+        │
+        ▼
+uplink send             WebSocket binary frame
+```
+
+`InputCommand.Sequence` is allocated by `session_next_input_sequence`. Monotonic, never reused. The server echoes the highest applied sequence in every snapshot header; the prediction module drops acked commands from its replay buffer on reconciliation.
+
+---
+
+## Binary AOI snapshot format
+
+The client decodes server-pushed AOI frames. Header (little-endian, 11 bytes for `0x01`/`0x03`):
+
+```
+[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 client
+[9..10]  u16  entityCount entity blocks that follow
+```
+
+After parsing the header, the decoder invokes `session_on_snapshot(tick, lastAcked)` and then `prediction_reconcile()` so the predicted self stays consistent with the just-arrived authoritative state.
+
+Other message types — init data (0x02), FCT (0x04), ItemFCT (0x05) — carry their own headers and are not part of the per-tick replication stream.
+
+---
+
+## REST fetches (engine-cyberia)
+
+The client speaks REST directly to engine-cyberia for content. None of these calls go through cyberia-server.
+
+| Endpoint                                         | Purpose                              |
+| ------------------------------------------------ | ------------------------------------ |
+| `GET /api/atlas-sprite-sheet/metadata/:itemKey`  | Frame layout JSON for a sprite atlas |
+| `GET /api/atlas-sprite-sheet/blob/:itemKey`      | Atlas PNG                            |
+| `GET /api/object-layer/:itemId`                  | ObjectLayer JSON metadata            |
+| `GET /api/cyberia-dialogue/code/default-:itemId` | Dialogue lines for an NPC            |
+| `GET /assets/ui-icons/:iconId.png`               | Status-bar icons                     |
+| `GET /api/cyberia-client-hints/:instanceCode`    | Optional presentation overrides      |
+
+All requests are CORS-simple GETs (no preflight) and cacheable. None require credentials.
+
+---
+
+## Build and run
+
+```bash
+cd cyberia-client
+
+# Development build
+make -f Web.mk clean && make -f Web.mk web
+
+# Release build
+make -f Web.mk clean && make -f Web.mk web BUILD_MODE=RELEASE
+
+# Build + serve on dev port :8082
+make -f Web.mk serve-development
+```
+
+The build is part of the Underpost Platform static + PWA pipeline; production deploys go through `underpost client` and `underpost deploy`.
+
+### Output
+
+```
+bin/
+  index.html    — Emscripten HTML container (from shell.html template)
+  index.wasm    — Compiled WebAssembly module
+  index.js      — Emscripten JS glue
+  index.data    — Preloaded data bundle
+```
+
+---
+
+## Compile-time configuration
+
+`src/config.h`:
+
+| Constant                    | Default                             | Description                                                                                                      |
+| --------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `WS_URL`                    | `wss://server.cyberiaonline.com/ws` | WebSocket endpoint of cyberia-server                                                                             |
+| `API_BASE_URL`              | `https://www.cyberiaonline.com`     | engine-cyberia REST base URL                                                                                     |
+| `CYBERIA_CLIENT_HINTS_CODE` | `cyberia-main`                      | Lookup key for the optional client-hints fetch (presentation override key — never an instance/server identifier) |
+| `HTTP_TIMEOUT_SECONDS`      | `10`                                | HTTP request timeout                                                                                             |
+| `MAX_TEXTURE_CACHE_SIZE`    | `512`                               | Atlas texture LRU cap                                                                                            |
+| `MAX_LAYER_CACHE_SIZE`      | `256`                               | ObjectLayer metadata LRU cap                                                                                     |
+| `MAX_ATLAS_CACHE_SIZE`      | `256`                               | Atlas metadata LRU cap                                                                                           |
+| `DEFAULT_FRAME_DURATION_MS` | `100`                               | Default animation frame duration                                                                                 |
+| `ENABLE_DEV_UI`             | `false`                             | Force dev overlay regardless of presentation hints                                                               |
+| `APP_VERSION`               | `"1.0.0"`                           | Application version string                                                                                       |
+
+For local development, point `WS_URL` and `API_BASE_URL` at `localhost` before rebuilding.
+
+---
+
+## Persistent storage
+
+`serial.c` uses Emscripten's IDBFS (IndexedDB File System) at `/persistent/` for:
+
+- Player authentication token (EIP-712 signature).
+- Local game settings (audio volume, key bindings).
+- Cached ObjectLayer metadata (session warm-up cache).
+
+No game state is persisted client-side; the authoritative server is the source of truth.

package/src/client/public/cyberia-docs/CYBERIA-SERVER.md

@@ -0,0 +1,278 @@
+<p align="center">
+  <img src="https://www.cyberiaonline.com/assets/splash/apple-touch-icon-precomposed.png" alt="CYBERIA online"/>
+</p>
+
+<div align="center">
+
+<h1>cyberia server</h1>
+
+</div>
+
+**Path:** `cyberia-server/` · **Language:** Go · **Role:** authoritative simulation runtime for Cyberia
+
+`cyberia-server` is the authoritative simulation runtime for the Cyberia MMO extension on Underpost Platform. It owns world state, advances a fixed-rate tick, drains typed input commands from connected clients, and dispatches AOI-filtered snapshots on a separately-paced replication tick.
+
+It is **not** the content authority. World content is loaded from `engine-cyberia` over gRPC. It is **not** the render-policy authority. Presentation is owned by `cyberia-client`.
+
+---
+
+## Operating model
+
+Three independent processes, non-overlapping roles. The ecosystem is playable only when all three are running and healthy at the same time.
+
+```text
+engine-cyberia (Node.js)        cyberia-server (Go)            cyberia-client (C/WASM)
+content authority               authoritative simulation       presentation runtime
+gRPC + REST                     tick + AOI + snapshots         render + prediction
+
+   └── gRPC GetFullInstance ──►   └── WebSocket binary ──►
+         world config                  snapshots -> / input <-
+```
+
+- Each service is supervised independently and owns its own monitor and reconnector.
+- `cyberia-server` loads world configuration from `engine-cyberia` and does not fabricate a world.
+- If any one of the three services is unhealthy, the game moves to standby until all three recover.
+
+The server speaks two protocols:
+
+- **gRPC inbound** to consume world configuration from `engine-cyberia`
+- **WebSocket binary** to deliver snapshots and accept typed input commands
+
+There is no per-tick traffic between `cyberia-server` and `engine-cyberia`, and no presentation authority in the Go runtime.
+
+---
+
+## Tick model
+
+The tick is the universal coordinate of the simulation.
+
+| Concept           | Default         | Notes                                                                                                   |
+| ----------------- | --------------- | ------------------------------------------------------------------------------------------------------- |
+| **tick**          | `uint32`        | Monotonic, advanced once per simulation step. Resets only on world rebuild.                             |
+| **tick rate**     | `30` Hz         | Simulation Hz. Loaded from world configuration. **The string `fps` is not used to describe this rate.** |
+| **snapshot rate** | `20` Hz         | AOI replication Hz. Decoupled from tick rate so bandwidth scales independently of simulation fidelity.  |
+| **tick duration** | `1 / tick_rate` | The dt used by every simulation phase.                                                                  |
+| **current tick**  | `uint32`        | The simulation step about to run (or just produced). Stamped into every outgoing snapshot.              |
+
+Two independent tickers:
+
+| Ticker      | Rate              | Responsibility                                               |
+| ----------- | ----------------- | ------------------------------------------------------------ |
+| simulation  | `tickRate` Hz     | advance world by exactly one tick; run phases in fixed order |
+| replication | `snapshotRate` Hz | per-player AOI filter + encode + dispatch                    |
+
+Movement integration is `dt`-based: `step = speed * tickDuration.Seconds()`. Frame-count integration is not used anywhere on the server.
+
+---
+
+## Simulation phases
+
+Inside one simulation tick, the phases run in a fixed order. Phases are the **only** functions allowed to mutate world state.
+
+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.
+
+Separately, on the replication ticker:
+
+7. **`phaseReplication`** — per player: compute AOI rectangle, build snapshot, dispatch via the player's WebSocket write channel.
+
+Phases never read presentation data. Phases consume world configuration (gameplay rules) and the per-player input queue.
+
+---
+
+## Input command pipeline
+
+Client input is typed end-to-end. There is no JSON intermediate on the binary path. The simulation tick is the only consumer of input commands.
+
+```
+WS frame (binary)  →  decode  →  typed InputCommand{kind, clientTick, sequence, payload}
+                                              │
+                                              ▼
+                                              dispatchInputCommand
+                                              │
+                                              ▼
+                                              PlayerState.InputQueue (per-player, bounded ring)
+                                              │
+                                              ▼
+                         phaseInput (under world mutex, once per simulation tick)
+                                              │
+                                              ▼
+                         phase_input_handlers.go — typed dispatch per InputKind
+                                              │
+                                              ▼
+                         authoritative world state
+```
+
+| Property                          | Detail                                                                                                                                             |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| One queue per player              | drained exactly once per simulation tick                                                                                                           |
+| One typed handler per `InputKind` | each handler runs under the world mutex held by `phaseInput`                                                                                       |
+| One source of truth               | `phase_input_handlers.go` is the only file that translates an input command into world state                                                       |
+| Sequence numbering                | `InputCommand.Sequence` is monotonic per client; the server tracks the highest applied sequence per player in `PlayerState.LastAckedInputSequence` |
+
+A second uplink path, `handleJSONUplink`, parses text-framed JSON uplinks into the same typed `InputCommand` and routes them through the same per-tick queue. No synchronous game-state mutation runs on the WebSocket read goroutine.
+
+### Input kinds
+
+| Kind             | Wire byte | Effect                                                                          |
+| ---------------- | --------- | ------------------------------------------------------------------------------- |
+| `PlayerAction`   | `0x11`    | TAP — movement intent + skill trigger                                           |
+| `ItemActivation` | `0x12`    | Equip/unequip an ObjectLayer item; validated against equipment rules            |
+| `FreezeStart`    | `0x13`    | Enter FrozenInteractionState (blocks movement/damage; rest of world unaffected) |
+| `FreezeEnd`      | `0x14`    | Exit FrozenInteractionState                                                     |
+| `Chat`           | `0x15`    | Pure relay; no game-state mutation                                              |
+| `GetItemsIDs`    | `0x16`    | Skill-item-id lookup; produces a response frame                                 |
+| `Handshake`      | `0x10`    | Connection establishment; no gameplay effect                                    |
+
+---
+
+## AOI replication
+
+The AOI system filters world state per-player so each client receives only what its character can perceive.
+
+Per player:
+
+- AOI is a rectangle centered on the player position with size determined by `aoiRadius` from world configuration.
+- On each replication tick, the server iterates the player's map, includes any entity whose bounding rectangle overlaps the AOI, and emits a snapshot.
+
+### Snapshot header (binary, little-endian)
+
+```
+[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
+```
+
+The `tick` and `lastAcked` fields are how the client reconciles its predicted self with authoritative state. The client drops input commands with `sequence ≤ lastAcked` from its replay buffer, then rewinds and replays the rest.
+
+Other message types (init data, FCT) carry their own headers and are not part of the per-tick replication stream.
+
+---
+
+## World configuration
+
+World configuration is loaded once at boot from engine-cyberia via gRPC `GetFullInstance(instanceCode)`. The simulation consumes the following from it:
+
+| Field                                                                | Used for                                                                          |
+| -------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `cellSize`                                                           | grid math                                                                         |
+| `tickRate`                                                           | simulation Hz                                                                     |
+| `aoiRadius`                                                          | per-player AOI rectangle size                                                     |
+| `entityBaseSpeed`, `entityBaseMaxLife`, `entityBaseActionCooldownMs` | base stats                                                                        |
+| `economyRules`                                                       | Fountain & Sink coin economy                                                      |
+| `skillRules`                                                         | projectile / doppelganger spawn rates and lifetimes                               |
+| `equipmentRules`                                                     | item activation constraints (one-per-type, requireSkin, activeItemTypes)          |
+| `entityDefaults[*]`                                                  | per-entity-type gameplay defaults: live/dead/drop item IDs, default object layers |
+
+World configuration is gameplay-only. Presentation fields (palette, status-icon visuals, camera knobs, dev-overlay flag, interpolation window, screen factors) are not part of this contract. Presentation metadata ownership is described in the next section.
+
+Hot reload of ObjectLayers is supported via periodic `GetObjectLayerManifest` calls; world topology and gameplay rules are reloaded only on server restart.
+
+---
+
+## Presentation metadata ownership
+
+`cyberia-server` holds **no** presentation state. There is no field on the server for:
+
+- palette
+- status-icon iconId or border color
+- camera smoothing or camera zoom
+- dev-overlay flag
+- screen-factor overrides
+- interpolation window
+
+These live in the client runtime's compile-time defaults. Per-instance presentation overrides are served by engine-cyberia at `GET /api/cyberia-client-hints/:instanceCode` and consumed directly by the client. The Go process never calls that endpoint.
+
+### `sim_palette.go`
+
+A small internal RGBA table inside `sim_palette.go` exists solely to fill the optional per-entity color bytes on the AOI wire for portals, skill projectiles, and freshly spawned players. The table is:
+
+- compile-time constant
+- not loaded from any contract (gRPC, REST, proto, env)
+- read only at world-build and one-shot spawn paths
+- never consulted during any per-tick simulation phase
+
+The client treats those wire bytes as a hint and resolves the actual fallback color from its own palette by entity type.
+
+---
+
+## Source layout
+
+Paths are relative to `cyberia-server/`. Gameplay logic lives under `src/`; the gRPC client and world builder under `src/grpcclient/`; the chi-based REST router under `api/`.
+
+| File                                                                                              | Responsibility                                                                                          |
+| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `main.go`                                                                                         | Entry point — loads `.env`, dials engine-cyberia gRPC, mounts WS and `/api` router, starts listener     |
+| `src/tick.go`                                                                                     | `Tick`, `InputSequence` types and tick rate constants                                                   |
+| `src/server.go`                                                                                   | `GameServer` struct, simulation+replication tickers, `ApplyInstanceConfig`, world mutator orchestration |
+| `src/types.go`                                                                                    | Core data structures (`PlayerState`, `BotState`, `MapState`, `ObjectLayerState`, etc.)                  |
+| `src/simulation_phases.go`                                                                        | Phase entry points called from the tick loop                                                            |
+| `src/phase_input_handlers.go`                                                                     | Typed dispatch per `InputKind`; the only translator from input commands to world state                  |
+| `src/input_command.go`                                                                            | `InputCommand` struct, `InputKind` constants, per-player queue helper                                   |
+| `src/aoi_binary.go`                                                                               | Binary AOI snapshot encoder; message type constants                                                     |
+| `src/object_layer.go`                                                                             | ObjectLayer Go types mirroring MongoDB schema                                                           |
+| `src/instance_loader.go`                                                                          | World reconstruction from gRPC payload                                                                  |
+| `src/collision.go`                                                                                | Grid collision, portal transitions, death handling                                                      |
+| `src/pathfinding.go`                                                                              | A\* pathfinding for bot and player navigation                                                           |
+| `src/skill.go`, `src/skill_dispatcher.go`, `src/skill_projectile.go`, `src/skill_doppelganger.go` | Skill registry and per-skill handlers                                                                   |
+| `src/economy.go`                                                                                  | Fountain & Sink coin economy                                                                            |
+| `src/life_regen.go`                                                                               | HP regeneration                                                                                         |
+| `src/ai.go`                                                                                       | Bot AI                                                                                                  |
+| `src/stats.go`                                                                                    | Active stat aggregation, sum-stats limit enforcement                                                    |
+| `src/entity_status.go`                                                                            | Entity Status Indicator (ESI) numeric IDs                                                               |
+| `src/frozen_state.go`                                                                             | FrozenInteractionState                                                                                  |
+| `src/handlers.go`                                                                                 | WebSocket lifecycle, binary uplink decoder, JSON-uplink back-compat adapter                             |
+| `src/sim_palette.go`                                                                              | Internal RGBA fill for AOI wire bytes (not a contract)                                                  |
+| `src/grpcclient/`                                                                                 | gRPC client + world builder for engine-cyberia                                                          |
+| `api/router.go`, `api/metrics.go`                                                                 | chi router; `/api/v1/*` endpoints                                                                       |
+| `proto/cyberia.proto`                                                                             | gRPC service contract shared with engine-cyberia                                                        |
+
+---
+
+## REST surface
+
+`/api/v1/*` is the operational surface; it is independent of the WebSocket gameplay protocol.
+
+| Endpoint                    | Method | Description                               |
+| --------------------------- | ------ | ----------------------------------------- |
+| `/api/v1/health`            | GET    | Simple health check                       |
+| `/api/v1/metrics`           | GET    | Complete server metrics snapshot          |
+| `/api/v1/metrics/health`    | GET    | Detailed health with entity/player counts |
+| `/api/v1/metrics/entities`  | GET    | Entity-type breakdown                     |
+| `/api/v1/metrics/websocket` | GET    | Active connections, message rates         |
+| `/api/v1/metrics/workload`  | GET    | Per-map entity workload                   |
+
+All content data (ObjectLayer metadata, asset blobs, optional client hints) is served directly by engine-cyberia REST. `cyberia-server` does not proxy content.
+
+---
+
+## Environment
+
+| Variable                          | Default           | Description                                        |
+| --------------------------------- | ----------------- | -------------------------------------------------- |
+| `ENGINE_GRPC_ADDRESS`             | `localhost:50051` | engine-cyberia gRPC address (**required**)         |
+| `INSTANCE_CODE`                   | `default`         | Instance code to load on startup                   |
+| `ENGINE_API_BASE_URL`             | _(empty)_         | engine-cyberia REST base URL; forwarded to clients |
+| `ENGINE_GRPC_RELOAD_INTERVAL_SEC` | _(disabled)_      | ObjectLayer hot-reload polling interval            |
+| `SERVER_PORT`                     | `8081`            | WebSocket + HTTP listen port                       |
+| `STATIC_DIR`                      | `./public`        | Directory for static WASM client files             |
+
+---
+
+## Build and run
+
+```bash
+cd cyberia-server
+
+# Development
+go run main.go
+
+# Production binary
+go build -o cyberia-server .
+./cyberia-server
+```