cyberia 3.2.5 → 3.2.12

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

@@ -0,0 +1,259 @@
+<div align="center">
+
+  <img src="https://www.cyberiaonline.com/assets/splash/apple-touch-icon-precomposed.png" alt="CYBERIA Network Object Layer Engine"/>
+
+<h1>CYBERIA</h1>
+
+**Network Object Layers**
+
+_Stackable Rendering Layers as a Unified Tokenized Reality_
+
+[![Version](https://img.shields.io/npm/v/cyberia.svg)](https://www.npmjs.org/package/cyberia)
+
+</div>
+Cyberia is an MMORPG extension built on the Underpost Platform. The platform owns the
+toolchain, deployment surface, PWA delivery, and base infrastructure. Cyberia adds a three-service MMO
+runtime: `engine-cyberia`, `cyberia-server`, and `cyberia-client`.
+
+`engine-cyberia` is the **sidecar-backed data layer**: a Node.js sidecar that owns content,
+validation, persistence, the gRPC/REST data services, and asset metadata. It backs the authoritative
+Go server and the WASM client with data — it does not run the simulation or the presentation.
+
+---
+
+## Ecosystem at a glance
+
+```text
+                         ┌───────────────────────────────────────────────┐
+                         │              UNDERPOST PLATFORM                 │
+                         │  toolchain · deploy · PWA build · static        │
+                         │  delivery · cluster/image/db · monitoring       │
+                         │                                                 │
+                         │   underpost CLI  ──▶  builds & deploys all      │
+                         └───────────────────────────────────────────────┘
+                                            │  hosts / delivers
+                                            ▼
+   ╔═══════════════════════════════ CYBERIA MMO ══════════════════════════════════╗
+   ║                                                                               ║
+   ║   ┌──────────────────┐   gRPC    ┌──────────────────┐   WebSocket            ║
+   ║   │  engine-cyberia  │ ────────▶ │  cyberia-server  │ ───────────┐           ║
+   ║   │     (Node.js)    │           │       (Go)       │            │           ║
+   ║   │                  │           │                  │            ▼           ║
+   ║   │ content          │           │ authoritative    │   ┌──────────────────┐ ║
+   ║   │ validation       │           │ simulation       │   │  cyberia-client  │ ║
+   ║   │ persistence      │           │ world tick       │   │    (C / WASM)    │ ║
+   ║   │ gRPC/REST data   │           │ AOI replication  │   │                  │ ║
+   ║   │ asset metadata   │           │                  │   │ rendering        │ ║
+   ║   └──────────────────┘           └──────────────────┘   │ input            │ ║
+   ║            │                                             │ prediction       │ ║
+   ║            └──────────────── REST (content/assets) ─────▶│ presentation     │ ║
+   ║                                                          └──────────────────┘ ║
+   ╚═══════════════════════════════════════════════════════════════════════════════╝
+
+   One source of truth per concern:
+     content & world config ── engine-cyberia
+     real-time world state  ── cyberia-server
+     presentation & input   ── cyberia-client
+```
+
+---
+
+## 1. Toolchain and base infrastructure
+
+Underpost Platform is the operational backbone and the source of truth for deploy IDs, runtime
+selection, host/path layout, generated client assets, and environment resolution.
+
+| Area            | What it owns                                                                         |
+| --------------- | ------------------------------------------------------------------------------------ |
+| Toolchain       | `underpost` CLI, build, deploy, release, metadata, secrets, environment selection    |
+| Infrastructure  | bare metal, LXD, Kubernetes, K3s, kubeadm, images, SSH, runners                      |
+| Data operations | MongoDB, MariaDB where needed, backups, cron, monitoring                             |
+| Delivery        | static build, SSR views, PWA packaging, service worker generation, host/path routing |
+
+`underpost` is the shared control surface for everything infrastructural. Cyberia-specific work belongs
+in the `cyberia` CLI, never in parallel platform commands. When a concern already exists in `underpost`,
+reuse it instead of forking a Cyberia variant.
+
+---
+
+## 2. PWA workflow
+
+Every deployed client ships as a static application shell with PWA support. The pipeline has exactly two
+inputs:
+
+- the deploy `ssr` configuration in `conf.dd-*.js` (or `conf.ssr.json`)
+- the service worker source in `src/client/sw/core.sw.js`
+
+Everything else — `index.html` pages, `sw.js`, the precache list — is **generated** during the client
+build. Treat them as outputs only; never hand-edit them.
+
+Runtime service-worker behavior:
+
+| Request       | Strategy                         |
+| ------------- | -------------------------------- |
+| static assets | stale-while-revalidate           |
+| API `GET`     | network-first + short cache      |
+| API mutations | network-only + background replay |
+| navigation    | network-first + fallback shells  |
+
+Fallback selection: offline network → offline fallback view; origin/server failure → maintenance
+fallback view. Only fallback-marked views are guaranteed precached.
+
+---
+
+## 3. Cyberia MMO extension
+
+### Responsibility split
+
+| Service          | Owns                                                                      | Must not own                                  |
+| ---------------- | ------------------------------------------------------------------------- | --------------------------------------------- |
+| `engine-cyberia` | content, validation, persistence, gRPC/REST data services, asset metadata | authoritative simulation, render policy       |
+| `cyberia-server` | authoritative simulation, world tick, gameplay mutation, AOI replication  | content authority, presentation metadata      |
+| `cyberia-client` | rendering, input, prediction, interpolation, presentation                 | authoritative world state, gameplay authority |
+
+Two boundaries are non-negotiable:
+
+- Do not move authoritative logic into the client.
+- Do not move content-authority logic into the Go runtime.
+
+### Data flow
+
+```text
+engine-cyberia ──gRPC──▶ cyberia-server ──WebSocket──▶ cyberia-client
+engine-cyberia ──REST──────────────────────────────▶ cyberia-client
+```
+
+### `engine-cyberia` as the sidecar-backed data layer
+
+`engine-cyberia` is the only Cyberia service that owns content-backed data and asset metadata.
+
+- Boot-time world configuration flows from `engine-cyberia` to `cyberia-server` over gRPC `GetFullInstance`.
+- Client-facing assets, object layers, dialogues, and presentation hints flow from `engine-cyberia` to `cyberia-client` over REST.
+- Simulation never migrates into the sidecar, and presentation policy never migrates out of the client.
+
+### Runtime / health model
+
+Three supervised processes run in parallel, each with its own monitor and reconnect loop. Gameplay is live only when all three are healthy at once.
+
+```text
+        ┌──────────────────────────────────────────────────────────────┐
+        │                    SUPERVISION (parallel)                      │
+        │                                                                │
+        │   engine-cyberia        cyberia-server        cyberia-client   │
+        │   ┌────────────┐        ┌────────────┐        ┌────────────┐   │
+        │   │  monitor   │        │  monitor   │        │  monitor   │   │
+        │   │ +reconnect │        │ +reconnect │        │ +reconnect │   │
+        │   └─────┬──────┘        └─────┬──────┘        └─────┬──────┘   │
+        │         │                     │                     │          │
+        │         └──────────┬──────────┴──────────┬──────────┘          │
+        │                    ▼                     ▼                     │
+        │            all three up & connected?                          │
+        └────────────────────────────┬─────────────────────────────────┘
+                                      │
+                ┌─────────────────────┼─────────────────────┐
+                ▼                     ▼                     ▼
+          ┌───────────┐        ┌───────────┐         ┌───────────┐
+          │  HEALTHY  │        │ DEGRADED  │         │  STANDBY  │
+          │ all 3 up  │        │ ≥1 service│         │ gameplay  │
+          │ gameplay  │        │ reconnect-│         │ paused    │
+          │ live      │        │ ing / down│         │ until all │
+          │           │        │           │         │ 3 healthy │
+          └───────────┘        └───────────┘         └───────────┘
+```
+
+| 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 |
+
+---
+
+## User commands
+
+Use `underpost` for platform, infrastructure, build, and deploy. Use `cyberia` for MMO content and
+extension workflows. Both share the same helpers — never duplicate config, env, or path logic.
+
+### Platform (underpost)
+
+```bash
+# Bootstrap a new app (local app serves on http://localhost:4001)
+underpost new app-name
+
+# Build the client bundle / static + PWA output
+underpost client
+npm run build            # node bin client
+
+# Deploy and operate
+underpost deploy <deploy-id>
+underpost monitor
+```
+
+### Cyberia (cyberia) — `bin/cyberia.js`
+
+| Group          | Command                                | Purpose                                                  |
+| -------------- | -------------------------------------- | -------------------------------------------------------- |
+| `ol`           | `cyberia ol [item-id]`                 | ObjectLayer import, procedural generation, atlas/sprite  |
+| `instance`     | `cyberia instance [instance-code]`     | export / import / drop a Cyberia instance and its data   |
+| `client-hints` | `cyberia client-hints [instance-code]` | per-instance presentation hints (palette, camera, icons) |
+| `chain`        | `cyberia chain <sub>`                  | Hyperledger Besu + ERC-1155 ObjectLayerToken lifecycle   |
+| `run-workflow` | `cyberia run-workflow <name>`          | named maintenance/build scripts from `scripts/`          |
+
+Common examples:
+
+```bash
+# Object layer content
+cyberia ol hatchet,sword --import                 # import specific items
+cyberia ol --import-types skin,floors             # batch import by type (or: all)
+cyberia ol floor-desert --generate --seed fx-42   # procedural generation
+cyberia ol hatchet --to-atlas-sprite-sheet        # build atlas sprite sheet
+cyberia ol --drop --client-public                 # drop data + static asset folders
+
+# Instance data
+cyberia instance FOREST --export ./backup
+cyberia instance FOREST --import ./backup
+cyberia instance FOREST --drop
+
+# Presentation hints
+cyberia client-hints cyberia-main --seed-defaults
+
+# Chain / token lifecycle
+cyberia chain deploy --chain-id 777771
+cyberia chain status
+cyberia chain register / mint / transfer / burn / pause / unpause
+
+# Named workflows
+cyberia run-workflow import-default-items
+cyberia run-workflow seed-skill-config --instance-code default
+cyberia run-workflow seed-dialogues
+cyberia run-workflow build-manifest
+cyberia run-workflow build-server-dashboard
+```
+
+### Run the MMO services
+
+```bash
+# engine-cyberia (Node.js data/content services)
+npm start                                          # node src/server
+
+# cyberia-server (Go authoritative simulation)
+cd cyberia-server && go run main.go                # dev
+cd cyberia-server && go build -o cyberia-server . && ./cyberia-server
+
+# cyberia-client (C / WASM presentation)
+cd cyberia-client && make -f Web.mk clean && make -f Web.mk web
+cd cyberia-client && make -f Web.mk serve-development     # serves on :8082
+```
+
+---
+
+## Operational guardrails
+
+- Prefer one source of truth for config, deploy IDs, runtime selection, startup behavior, and generated assets.
+- Reuse existing helpers and conventions instead of creating parallel implementations.
+- Do not duplicate parsing, env resolution, or path normalization logic across modules.
+- Treat generated artifacts (`sw.js`, static pages, atlases, README, manifests) as outputs only.
+- Host-level changes must be idempotent, reversible, and explicit; validate before mutating; keep
+  orchestration scripts safe to rerun.
+- `engine-private/` is a private external dependency. Reference it only as private input; never assume
+  its contents exist locally.

package/src/client/public/cyberia-docs/ENTITY-PROFILE.md

@@ -0,0 +1,241 @@
+# Entity Profile
+
+**Module:** `src/api/cyberia-entity` · `src/api/cyberia-instance-conf`
+
+---
+
+## Overview
+
+An **Entity** is any object in the Cyberia Online game world — players, bots, NPCs, resource nodes, terrain tiles, portals, and skill-spawned projectiles. Every entity is represented as an ordered stack of **Object Layer** item IDs, a position on the grid, a type discriminator, and a runtime state.
+
+---
+
+## CyberiaEntity Schema (MongoDB)
+
+```
+CyberiaEntity {
+  entityType:         String  // see Entity Type Registry below
+  initCellX:          Number  // initial grid column
+  initCellY:          Number  // initial grid row
+  dimX:               Number  // width in cells (default: 1)
+  dimY:               Number  // height in cells (default: 1)
+  color:              String  // RGBA fallback color (no active OL texture)
+  objectLayerItemIds: [String] // ordered list of ObjectLayer item IDs
+
+  // Bot-specific (ignored for non-bot entities)
+  spawnRadius:  Number  // max wander / respawn radius in cells
+  aggroRange:   Number  // attack range in cells (0 = passive)
+  maxLife:      Number  // maximum HP (0 = immortal)
+  lifeRegen:    Number  // HP regeneration per tick
+}
+```
+
+---
+
+## Entity Type Registry
+
+| `entityType`   | Behavior              | Map-placed | Description                                           |
+| -------------- | --------------------- | ---------- | ----------------------------------------------------- |
+| `player`       | interactive           | no         | Local (self) player                                   |
+| `other_player` | interactive           | no         | Remote players in AOI                                 |
+| `bot`          | `hostile` / `passive` | yes        | AI-controlled bot                                     |
+| `skill`        | `skill`               | no         | Runtime-spawned projectile (created by skill system)  |
+| `coin`         | `coin`                | no         | Runtime-spawned collectible (dropped on entity death) |
+| `floor`        | static                | yes        | Terrain tile (walkable)                               |
+| `obstacle`     | static                | yes        | Collision tile (blocks movement)                      |
+| `portal`       | static                | yes        | Zone transition trigger                               |
+| `foreground`   | static                | yes        | Foreground decoration layer                           |
+| `resource`     | extractable           | yes        | Exploitable world object (drops items on extraction)  |
+
+---
+
+## Runtime PlayerState (Go)
+
+```go
+type PlayerState struct {
+    ID                string             // Go server player UUID
+    MapCode           string             // current map
+    Pos               Point              // world position (float64 X, Y)
+    Dims              Dimensions         // entity size
+    Color             ColorRGBA          // fallback solid color
+    Direction         Direction          // UP, UP_RIGHT, RIGHT, DOWN_RIGHT, DOWN, DOWN_LEFT, LEFT, UP_LEFT, NONE
+    Mode              ObjectLayerMode    // IDLE, WALKING, TELEPORTING
+    ObjectLayers      []ObjectLayerState // active OL stack: { ItemID, Active, Quantity }
+    MaxLife           float64
+    Life              float64
+    LifeRegen         float64
+    Coins             uint32             // flat coin balance (single source of truth)
+    Frozen            bool               // FrozenInteractionState active
+    FreezeReason      string             // "dialogue" | "inventory" | ...
+    Path              []PointI           // A* path (for smooth movement)
+    AOI               Rectangle          // current area-of-interest bounds
+    SumStatsLimit     int                // max aggregate stat sum (equipment rules)
+}
+```
+
+---
+
+## ObjectLayer State
+
+Each entity carries an ordered stack of `ObjectLayerState` entries:
+
+```go
+type ObjectLayerState struct {
+    ItemID   string  // references ObjectLayer.data.item.id
+    Active   bool    // equipped/activated (only activable types can be true)
+    Quantity int     // inventory quantity (for stackable items)
+}
+```
+
+The **active layers** determine the entity's rendered appearance and mechanical stats. The `Active` field is managed by the equipment rules.
+
+---
+
+## Equipment Rules
+
+Equipment rules govern which item types may be simultaneously active on a character:
+
+```javascript
+EQUIPMENT_RULES_DEFAULTS = {
+  activeItemTypes: ['skin', 'breastplate', 'weapon'], // only these types may be activated
+  onePerType: true, // at most one active item per type
+  requireSkin: true, // player must always have an active skin if they own any
+};
+```
+
+**Validation on `item_activation` request:**
+
+1. Reject if `item.type` not in `activeItemTypes`.
+2. If `onePerType`, deactivate any currently active item of the same type before activating the new one.
+3. If `requireSkin`, ensure a skin remains active after the change.
+
+---
+
+## Z-Order Rendering
+
+The C client composites layers bottom-to-top by `item.type`:
+
+```
+z-order  type
+──────   ───────────────────
+  0      floor / obstacle / portal / foreground
+  1      skin  (base character body)
+  2      breastplate (armor overlay)
+  3      weapon (weapon overlay)
+```
+
+`get_priority_for_type()` in `entity_render.c` maps item type → z-order integer. Multiple layers of the same type are rendered in declared order within that z-level.
+
+---
+
+## Stat Aggregation
+
+Stats are aggregated across all **active** Object Layers on an entity. The server enforces a `sumStatsLimit` — the maximum sum of all stat values allowed for the player. Attempting to equip items that would exceed this limit is rejected.
+
+**Active stats sum:**
+
+$$\text{activeStatsSum} = \sum_{\text{active layers}} (\text{effect} + \text{resistance} + \text{agility} + \text{range} + \text{intelligence} + \text{utility})$$
+
+The `sumStatsLimit` and `activeStatsSum` are sent to the client on each AOI update so the inventory UI can show remaining equip budget.
+
+---
+
+## Entity Status Indicator (ESI)
+
+The Go server computes a status `u8` per entity each AOI tick. The C client renders the corresponding icon above the entity nameplate.
+
+```go
+// Status constants (entity_status.go) — MUST stay in sync with JS STATUS_ICONS array
+StatusNone              = 0  // skill/coin bots, world objects
+StatusPassive           = 1  // passive bot
+StatusHostile           = 2  // hostile bot
+StatusFrozen            = 3  // player in FrozenInteractionState
+StatusPlayer            = 4  // normal alive player
+StatusDead              = 5  // dead / respawning entity
+StatusResource          = 6  // static exploitable resource
+StatusResourceExtracted = 7  // depleted resource (respawning)
+StatusActionProvider    = 8  // NPC with available actions (bouncing chat icon)
+```
+
+---
+
+## Per-EntityType Defaults
+
+Instance configuration (`CyberiaInstanceConf`) defines canonical defaults per entity type:
+
+| Field         | Description                                                                       |
+| ------------- | --------------------------------------------------------------------------------- |
+| `liveItemIds` | ObjectLayer item IDs applied when entity is alive with no explicit items assigned |
+| `deadItemIds` | ObjectLayer item IDs for dead/ghost/respawning state                              |
+| `dropItemIds` | Items granted to the extractor when a resource entity is depleted                 |
+| `colorKey`    | Named palette color used as solid fallback when no active OL texture is available |
+
+---
+
+## Bot Entity Profile
+
+Bot entities extend the base schema with runtime AI state:
+
+```go
+type BotState struct {
+    // Inherits all PlayerState fields
+    Behavior      string     // "hostile" | "passive" | "skill" | "coin"
+    SpawnRadius   int        // wander / respawn radius
+    AggroRange    int        // attack range (0 = passive)
+    SpawnPoint    PointI     // original spawn cell
+    RespawnTimer  time.Time  // next respawn timestamp
+}
+```
+
+**Bot behaviors:**
+
+| Behavior  | AI Actions                              | Description              |
+| --------- | --------------------------------------- | ------------------------ |
+| `hostile` | pathfind to player, attack              | Aggressive enemy bot     |
+| `passive` | random wander                           | Non-aggressive world NPC |
+| `skill`   | move in direction, despawn on collision | Projectile entity        |
+| `coin`    | static, collectible                     | Coin drop entity         |
+
+---
+
+## Resource Entity Profile
+
+Resource entities have a specific lifecycle:
+
+```
+Alive (StatusResource)
+  → Player extracts (tap interaction)
+    → dropItemIds granted to player inventory
+    → Entity transitions to StatusResourceExtracted
+      → Respawn timer starts
+        → Entity returns to StatusResource
+```
+
+---
+
+## Entity Lifecycle Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> Alive : Spawned by instance_loader
+    Alive --> Dead : Life reaches 0 (combat/skill)
+    Alive --> ResourceExtracted : Player extracts (resource type)
+    Dead --> Alive : Respawn timer elapsed
+    ResourceExtracted --> Alive : Respawn timer elapsed
+    Alive --> Frozen : Player opens modal (FrozenInteractionState)
+    Frozen --> Alive : Player closes modal
+    Alive --> [*] : Entity removed from AOI
+```
+
+---
+
+## Coin Balance Architecture
+
+Coins use a **flat + display split** design to avoid O(N) inventory traversal:
+
+| Field                         | Type               | Purpose                                                                                            |
+| ----------------------------- | ------------------ | -------------------------------------------------------------------------------------------------- |
+| `entity.Coins`                | `uint32`           | **Single source of truth** — all economy operations read/write this field O(1)                     |
+| `coinItemId ObjectLayer slot` | `ObjectLayerState` | **Display only** — `Active: false`, `Quantity = Coins`, synced by `syncCoinOL()` on every mutation |
+
+The `coin` item type is never activable. The inventory UI automatically renders it with a lock indicator.