cyberia 3.1.3 → 3.2.5

package/src/grpc/cyberia/OFF_CHAIN_ECONOMY.md

@@ -0,0 +1,305 @@
+# Off-Chain Economy — Fountain & Sink Architecture
+
+> **Status:** Alpha (sinks disabled; all values reset on reconnect).  
+> **On-chain bridge:** Planned — CKY ERC-1155 token (token ID 0) on Hyperledger Besu.  
+> See `hardhat/WHITE-PAPER.md §7 Tokenomics` for the bridge protocol.
+
+---
+
+## 1. Model Overview
+
+This game uses the **Fountain & Sink** economy model — the industry standard for
+sustainable in-game economies, pioneered by _Ultima Online_ and perfected in
+_EVE Online_ and _World of Warcraft_.
+
+```
+                ┌─────────────────────────────┐
+                │         FOUNTAINS           │
+                │  (inject coins into economy) │
+                │                             │
+                │  botSpawnCoins  ──► Bot      │
+                │  playerSpawnCoins ► Player   │
+                └──────────────┬──────────────┘
+                               │ new coins
+                               ▼
+                ┌──────────────────────────────┐
+                │      CIRCULATING SUPPLY      │
+                │   (player & bot wallets)     │
+                └──────┬───────────────────────┘
+                       │
+          ┌────────────┴────────────┐
+          │   KILL TRANSFER         │  zero-sum: no new coins created
+          │   (redistribution)      │  loser → winner
+          │                         │
+          │  PvE: coinKillPercentVsBot    │
+          │  PvP: coinKillPercentVsPlayer │
+          │  floor: coinKillMinAmount     │
+          └────────────┬────────────┘
+                       │
+                ┌──────▼──────────────────────┐
+                │           SINKS             │
+                │   (destroy coins, alpha=0)  │
+                │                             │
+                │  respawnCostPercent         │
+                │  portalFee                  │
+                │  craftingFeePercent         │
+                └─────────────────────────────┘
+```
+
+### Core rules
+
+| Rule                         | Description                                                                                                               |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| **Bots are infinite mint**   | Every bot respawn resets its wallet to `botSpawnCoins`. The supply is only bounded by player activity (kill rate).        |
+| **Players are zero-sum**     | Killing a player transfers coins but does not create new ones. PvP is redistribution only.                                |
+| **Kill floor**               | `coinKillMinAmount` guarantees every successful kill pays out, even against a near-empty wallet.                          |
+| **Sinks scale with economy** | Portal fees and respawn costs burn a fraction — more activity = more burn. Keeps the economy from inflating indefinitely. |
+
+---
+
+## 2. Configuration Structure
+
+Economy parameters live in a dedicated `economyRules` sub-document inside
+`CyberiaInstanceConf`, exactly mirroring the `skillRules` pattern.
+
+### 2.1 JavaScript defaults (`cyberia-instance-conf.defaults.js`)
+
+```js
+economyRules: {
+  // ── Fountains ──────────────────────────────────────────────────────
+  botSpawnCoins: 50,       // coins on bot spawn / respawn (infinite mint)
+  playerSpawnCoins: 50,    // guest starting wallet (resets on reconnect)
+
+  // ── Kill Transfer ───────────────────────────────────────────────────
+  coinKillPercentVsBot: 0.4,     // 40 % of bot wallet → killer on PvE kill
+  coinKillPercentVsPlayer: 0.15, // 15 % of player wallet → killer on PvP kill
+  coinKillMinAmount: 10,         // minimum coins per kill (hard floor)
+
+  // ── Sinks (alpha: all 0 = disabled) ────────────────────────────────
+  respawnCostPercent: 0.0,  // fraction burned on player death
+  portalFee: 0,             // flat coins burned per portal use
+  craftingFeePercent: 0.0,  // fraction burned per crafting action
+},
+```
+
+### 2.2 Mongoose schema (`cyberia-instance-conf.model.js`)
+
+```js
+// EconomyRulesSchema — mirrors defaults above
+economyRules: {
+  type: EconomyRulesSchema;
+}
+```
+
+The schema validates each field against the default value so a freshly created
+document is immediately playable without any explicit configuration.
+
+### 2.3 Protobuf message (`proto/cyberia.proto`)
+
+```proto
+message EconomyRules {
+  int32  bot_spawn_coins             = 1;
+  int32  player_spawn_coins          = 2;
+  double coin_kill_percent_vs_bot    = 3;
+  double coin_kill_percent_vs_player = 4;
+  int32  coin_kill_min_amount        = 5;
+  double respawn_cost_percent        = 6;
+  int32  portal_fee                  = 7;
+  double crafting_fee_percent        = 8;
+}
+
+// Used in InstanceConfig:
+EconomyRules economy_rules = 62;
+```
+
+### 2.4 Go server (`src/server.go` → `ApplyInstanceConfig`)
+
+```go
+er := cfg.GetEconomyRules()
+if er == nil { er = &pb.EconomyRules{} }
+
+s.botSpawnCoins           = int(er.GetBotSpawnCoins())
+s.playerSpawnCoins        = int(er.GetPlayerSpawnCoins())
+s.coinKillPercentVsBot    = er.GetCoinKillPercentVsBot()
+s.coinKillPercentVsPlayer = er.GetCoinKillPercentVsPlayer()
+s.coinKillMinAmount       = int(er.GetCoinKillMinAmount())
+s.respawnCostPercent      = er.GetRespawnCostPercent()
+s.portalFee               = int(er.GetPortalFee())
+s.craftingFeePercent      = er.GetCraftingFeePercent()
+```
+
+---
+
+## 3. Runtime Economy API (`src/economy.go`)
+
+All economy logic is encapsulated in a single file to enforce the single-source
+principle. Callers (`handlers.go`, `collision.go`, `skill.go`) call named methods
+and never manipulate coin wallets directly.
+
+### Method reference
+
+| Method                                | Caller                             | Description                                                 |
+| ------------------------------------- | ---------------------------------- | ----------------------------------------------------------- |
+| `FountainInitPlayer(player)`          | `handlers.go` on WebSocket connect | Credits `playerSpawnCoins` to new player                    |
+| `FountainInitBot(bot)`                | `collision.go` on bot respawn      | Resets bot wallet to `botSpawnCoins` (infinite mint)        |
+| `ExecuteKillTransfer(caster, victim)` | `skill.go HandleOnKillSkills`      | Transfers coins based on kill scenario (all 4 combinations) |
+| `SinkRespawnCost(player)`             | `collision.go handlePlayerDeath`   | Burns `respawnCostPercent`% of player coins (0 = no-op)     |
+| `SinkPortalFee(player)`               | Portal handler _(future)_          | Burns flat `portalFee` coins on portal use (0 = no-op)      |
+
+### Kill transfer scenarios
+
+```
+ExecuteKillTransfer(caster, victim):
+
+  if caster=Player, victim=Bot    → PvE rate (coinKillPercentVsBot)
+  if caster=Player, victim=Player → PvP rate (coinKillPercentVsPlayer)
+  if caster=Bot,    victim=Player → PvP rate (bot kills player)
+  if caster=Bot,    victim=Bot    → PvE rate (bot kills bot, e.g. friendly fire)
+
+  transfer = max(floor(victim.coins * rate), coinKillMinAmount)
+  transfer = min(transfer, victim.coins)   -- can't take more than available
+  victim.coins  -= transfer
+  caster.coins  += transfer               -- bots ignore received coins
+  sendFCT(caster, FCTTypeCoinGain, ...)
+  sendFCT(victim, FCTTypeCoinLoss, ...)
+```
+
+---
+
+## 4. Floating Combat Text (FCT) Wire Protocol
+
+Economy events trigger client-side visual feedback via the binary AOI protocol.
+
+```
+MsgTypeFCT = 0x04   (14 bytes, little-endian)
+
+Offset  Size  Field
+──────  ────  ──────────────────────────────────────
+  0      u8   message type (0x04)
+  1      u8   fct_type  (see table below)
+  2      f32  world_x   (entity position)
+  6      f32  world_y
+ 10      u32  value     (always positive; sign implied by type)
+```
+
+| `fct_type` | 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     |
+
+---
+
+## 5. MongoDB Document Example
+
+A complete `CyberiaInstanceConf` document with economy configured:
+
+```json
+{
+  "instanceCode": "alpha-01",
+  "cellSize": 45,
+  "fps": 60,
+  "economyRules": {
+    "botSpawnCoins": 50,
+    "playerSpawnCoins": 50,
+    "coinKillPercentVsBot": 0.4,
+    "coinKillPercentVsPlayer": 0.15,
+    "coinKillMinAmount": 10,
+    "respawnCostPercent": 0.0,
+    "portalFee": 0,
+    "craftingFeePercent": 0.0
+  },
+  "skillRules": {
+    "projectileSpawnChance": 0.5,
+    "projectileLifetimeMs": 2000,
+    "projectileWidth": 1,
+    "projectileHeight": 1,
+    "projectileSpeedMultiplier": 3,
+    "doppelgangerSpawnChance": 0.5,
+    "doppelgangerLifetimeMs": 5000,
+    "doppelgangerSpawnRadius": 3,
+    "doppelgangerInitialLifeFraction": 1.0
+  }
+}
+```
+
+---
+
+## 6. gRPC / Config Builder
+
+The `toInstanceConfig()` function in `grpc-server.js` resolves `economyRules`
+with a simple two-tier fallback:
+
+```
+priority:  gc.economyRules.field   (instance document in MongoDB)
+         → fb.economyRules.field   (CYBERIA_INSTANCE_CONF_DEFAULTS — always set)
+```
+
+All economy state lives exclusively in `economyRules`. There is no flat-field
+fallback chain. A document without an `economyRules` sub-document receives
+the canonical defaults automatically.
+
+---
+
+## 7. Enabling Sinks (Graduation from Alpha)
+
+When you want to activate the economy pressure levers, update `economyRules` in
+the DB document for the target instance:
+
+```json
+{
+  "economyRules": {
+    "respawnCostPercent": 0.1,
+    "portalFee": 5,
+    "craftingFeePercent": 0.05
+  }
+}
+```
+
+The Go server picks up changes on the next `LoadAll` / hot-reload via gRPC.
+No binary redeployment is needed.
+
+Recommended progression:
+
+1. **Alpha** — all sinks at 0; fountains generous (50 coins/spawn).
+2. **Beta** — `respawnCostPercent: 0.05`, bots at 30 coins.
+3. **Live** — tune all three sinks; enable on-chain bridge.
+
+---
+
+## 8. On-Chain Bridge (Future)
+
+```
+Off-chain wallet (in-memory)
+        │  on authenticate (secp256k1 sig)
+        ▼
+ERC-1155 CKY token (token ID 0)   ← ObjectLayerToken contract
+        │  on session end / explicit withdraw
+        ▼
+Player's Hyperledger Besu wallet
+```
+
+Until the bridge is live every economy event is ephemeral:
+
+- Wallets reset to `playerSpawnCoins` on every reconnect.
+- Bot wallets reset to `botSpawnCoins` on every respawn.
+- No cross-session coin persistence.
+
+This is intentional — the off-chain fallback lets the economy be tuned and
+battle-tested before committing values to an immutable ledger.
+
+---
+
+## 9. Field Reference
+
+| Field                                  | Type          | Default | Scope         |
+| -------------------------------------- | ------------- | ------- | ------------- |
+| `economyRules.botSpawnCoins`           | `int`         | `50`    | Fountain      |
+| `economyRules.playerSpawnCoins`        | `int`         | `50`    | Fountain      |
+| `economyRules.coinKillPercentVsBot`    | `float` [0,1] | `0.4`   | Kill Transfer |
+| `economyRules.coinKillPercentVsPlayer` | `float` [0,1] | `0.15`  | Kill Transfer |
+| `economyRules.coinKillMinAmount`       | `int`         | `10`    | Kill Transfer |
+| `economyRules.respawnCostPercent`      | `float` [0,1] | `0.0`   | Sink          |
+| `economyRules.portalFee`               | `int`         | `0`     | Sink          |
+| `economyRules.craftingFeePercent`      | `float` [0,1] | `0.0`   | Sink          |

package/src/grpc/cyberia/README.md

@@ -0,0 +1,326 @@
+# Cyberia gRPC Data Pipeline
+
+Internal gRPC server that exposes read-only RPCs over MongoDB data for the Go game server (`cyberia-server`).
+
+## Architecture
+
+```mermaid
+graph LR
+    engine["Node.js Engine\nMongoDB + Express\ngrpc-server.js"]
+    go["Go Game Server\ncyberia-server\ngrpcclient/world_builder.go"]
+
+    engine -->|"gRPC :50051\nGetFullInstance\nGetObjectLayerBatch\nGetMapData \u00b7 Ping"| go
+```
+
+## Data Flow
+
+```
+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 (for 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 from gRPC data
+  │  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
+```
+
+### Fallback Instance
+
+When `getFullInstance` is called with an instance code that does not exist in MongoDB, the Engine returns a **minimal playable fallback** instead of `NOT_FOUND`:
+
+- 1 empty map (64×64 floor grid, no obstacles, no bots, no portals)
+- No ObjectLayers, no AtlasSpriteSheets
+- `buildFallbackConfig()` provides playable defaults (speed, life, AOI, etc.)
+- Players are rendered as solid colored rectangles using the `PLAYER` color from the instance's color palette (no sprites needed)
+
+The Go server **always** requires gRPC — if the Engine is unreachable it exits with a fatal error. The fallback is purely Engine-side: `getFullInstance` with an unknown code returns a synthetic response, not `NOT_FOUND`.
+
+### Skill System: itemId → logicEventIds
+
+The skill pipeline maps trigger item IDs to ordered lists of logic handler keys:
+
+```
+CyberiaInstanceConf.skillConfig[] (MongoDB)
+  ├─ triggerItemId:  "atlas_pistol_mk2"        ← item in player's active object layer
+  └─ logicEventIds: ["atlas_pistol_mk2_logic"] ← ordered handler keys executed in sequence
+
+CyberiaInstanceConf.skillRules (MongoDB) → SkillRules proto message → GameServer fields
+  ├─ bulletSpawnChance / bulletLifetimeMs / bulletWidth / bulletHeight / bulletSpeedMultiplier
+  └─ doppelgangerSpawnChance / doppelgangerLifetimeMs / doppelgangerSpawnRadius / doppelgangerInitialLifeFraction
+
+Go runtime:
+  1. Player performs action
+  2. Iterate active object layers → s.skillConfig[layer.ItemID] → []SkillDefinition
+  3. For each SkillDefinition, iterate LogicEventIDs in order:
+       "doppelganger"          → executePlayerDoppelgangerSkill()
+       "atlas_pistol_mk2_logic" → executePlayerBulletSkill()  (bullet item ID is internal to the handler)
+```
+
+Spawning new entities (e.g. bullets) is handled entirely inside the logic handler — no `spawnedItemIds` config is needed.
+
+## Configuration
+
+Add `grpc` to the host conf in `conf.dd-cyberia.js`:
+
+```js
+'www.cyberiaonline.com': {
+  '/': {
+    db: { provider: 'mongoose', host: 'env:DB_HOST', name: 'env:DB_NAME_CYBERIA' },
+    grpc: { port: 50051 },
+    // ...
+  },
+},
+```
+
+The gRPC server starts automatically after `DataBaseProvider.load()` when the `grpc` key is present.
+
+### mTLS (optional)
+
+For production environments with network-separated services:
+
+```js
+grpc: {
+  port: 50051,
+  tls: {
+    caPath: '/path/to/ca.pem',
+    certPath: '/path/to/server-cert.pem',
+    keyPath: '/path/to/server-key.pem',
+  },
+},
+```
+
+The Go client (`cyberia-server/src/grpcclient/client.go`) supports the same mTLS config via `CACertPath`, `ClientCertPath`, `ClientKeyPath`.
+
+## Auth
+
+No application-level auth is required. This is a **private cluster-internal** channel:
+
+- Both services run on the same host or within a trusted network
+- The Go server is the only consumer — it dials `localhost:50051` by default
+- mTLS provides mutual authentication when services are network-separated
+- No user credentials or tokens flow over this channel — it's a data relay, not a user-facing API
+
+## Proto
+
+Service definition: [`cyberia-server/proto/cyberia.proto`](../../../cyberia-server/proto/cyberia.proto)
+
+After editing the proto, regenerate Go code:
+
+```sh
+cd cyberia-server
+export PATH=$PATH:$(go env GOPATH)/bin
+protoc --go_out=. --go_opt=paths=source_relative \
+       --go-grpc_out=. --go-grpc_opt=paths=source_relative \
+       proto/cyberia.proto
+```
+
+## Runtime Modes
+
+The gRPC server starts in **all** engine runtime modes that load `conf.server.json`:
+
+| npm script               | NODE_ENV    | gRPC starts? | Notes                               |
+| ------------------------ | ----------- | ------------ | ----------------------------------- |
+| `npm start`              | _(none)_    | Yes          | Production entry point              |
+| `npm run dev`            | development | Yes          | Nodemon auto-restart                |
+| `npm run dev:container`  | development | Yes          | Docker development                  |
+| `npm run prod:container` | production  | Yes          | Docker production                   |
+| `npm run dev:api`        | development | **No**       | API-only mode, no Express lifecycle |
+
+## Environment Variables
+
+### Engine (Node.js) — set in `.env` or `conf.dd-cyberia.js`
+
+| Variable          | Description           |
+| ----------------- | --------------------- |
+| `DB_HOST`         | MongoDB host          |
+| `DB_NAME_CYBERIA` | MongoDB database name |
+| `VALKEY_HOST`     | Valkey (Redis) host   |
+| `VALKEY_PORT`     | Valkey port           |
+
+### Go Server — set in `.env` or environment
+
+| Variable                          | Default           | Description                                        |
+| --------------------------------- | ----------------- | -------------------------------------------------- |
+| `ENGINE_GRPC_ADDRESS`             | `localhost:50051` | Engine gRPC server address — **required**          |
+| `INSTANCE_CODE`                   | `default`         | Instance code to load on startup                   |
+| `ENGINE_API_BASE_URL`             | _(empty)_         | Engine HTTP base URL (forwarded to clients)        |
+| `ENGINE_GRPC_RELOAD_INTERVAL_SEC` | _(disabled)_      | ObjectLayer hot-reload polling interval in seconds |
+| `SERVER_PORT`                     | `8081`            | HTTP/WS server listen port                         |
+| `STATIC_DIR`                      | `./public`        | Directory for static WASM client files             |
+| `ENGINE_GRPC_CA_CERT`             | _(empty)_         | CA certificate for mTLS                            |
+| `ENGINE_GRPC_CLIENT_CERT`         | _(empty)_         | Client certificate for mTLS                        |
+| `ENGINE_GRPC_CLIENT_KEY`          | _(empty)_         | Client private key for mTLS                        |
+
+### C/WASM Client — compile-time constants in `src/config.h`
+
+| Constant        | Development              | Production                          |
+| --------------- | ------------------------ | ----------------------------------- |
+| `WS_URL`        | `ws://localhost:8081/ws` | `wss://server.cyberiaonline.com/ws` |
+| `API_BASE_URL`  | `http://localhost:4005`  | `https://www.cyberiaonline.com`     |
+| `GHOST_ITEM_ID` | `ghost`                  | `ghost`                             |
+
+## Development
+
+Run all three components locally in separate terminals:
+
+```sh
+# Terminal 1: Engine (Node.js — Express + MongoDB + gRPC :50051)
+cd /home/dd/engine
+npm run dev
+
+# Terminal 2: Go game server (WS :8081 + REST /api/v1/*)
+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 (static :8082)
+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
+```
+
+### Startup order
+
+```
+1. Engine (npm run dev)       → gRPC server listens on :50051
+2. Go server (go run main.go) → dials :50051, loads instance, WS on :8081
+3. C client (serve-development) → opens browser, connects WS to :8081
+```
+
+If `INSTANCE_CODE` doesn't match a database record, the Engine returns a minimal fallback instance — the Go server starts normally. If the Engine is not running, the Go server exits (gRPC is required).
+
+### Dev ports summary
+
+| Component      | Port  | Protocol  |
+| -------------- | ----- | --------- |
+| Engine Express | 4005+ | HTTP      |
+| Engine gRPC    | 50051 | gRPC      |
+| Go server      | 8081  | HTTP + WS |
+| C client       | 8082  | HTTP      |
+
+## Production
+
+### Kubernetes deployment order
+
+```
+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
+```
+
+### C client production build
+
+```sh
+cd /home/dd/engine/cyberia-client
+# Ensure src/config.h has production URLs:
+#   WS_URL = "wss://server.cyberiaonline.com/ws"
+#   API_BASE_URL = "https://www.cyberiaonline.com"
+source ~/.emsdk/emsdk_env.sh
+make -f Web.mk clean && make -f Web.mk web BUILD_MODE=RELEASE
+make -f Web.mk serve-production   # http://localhost:8082
+```
+
+### Go server with embedded client
+
+The Go server can serve the WASM client directly via `STATIC_DIR`:
+
+```sh
+# Copy WASM build output to Go server's public dir
+cp -r cyberia-client/bin/web/release/* cyberia-server/public/
+
+# Go server serves both WS and static files on :8081
+STATIC_DIR=./public go run main.go
+```
+
+In Kubernetes, each runs in its own pod behind Contour/Envoy:
+
+```
+Contour/Envoy (L7 proxy, TLS termination via cert-manager)
+  ├─ www.cyberiaonline.com    → Engine pods (:4005)
+│  server.cyberiaonline.com → Go server pod (:8081)  ← WS + REST
+│  client.cyberiaonline.com → Client pod (:8082)     ← WASM static
+```
+
+Port 50051 (gRPC) is **not** exposed via Contour — it is cluster-internal only.
+
+### TLS
+
+- **External**: cert-manager + LetsEncrypt (ACME HTTP-01) for `*.cyberiaonline.com`
+- **Internal gRPC**: No TLS needed for same-cluster. mTLS only if cross-cluster.
+
+### Hot-reload
+
+When `ENGINE_GRPC_RELOAD_INTERVAL_SEC` is set, the Go server periodically:
+
+1. Pings the Engine for liveness
+2. Fetches ObjectLayer manifest (itemId + sha256 pairs)
+3. Diffs against local cache
+4. Re-fetches only changed/new ObjectLayers
+5. Removes deleted ObjectLayers
+
+## CD Workflows
+
+All three repos use `workflow_dispatch` for manual triggers + commit-message triggers:
+
+| Repo             | Trigger                              | Job                           |
+| ---------------- | ------------------------------------ | ----------------------------- |
+| `engine`         | `cd(ssh-engine-cyberia)` or dispatch | deploy, sync-and-deploy, init |
+| `cyberia-server` | `cd(ssh-cyberia-server)` or dispatch | deploy                        |
+| `cyberia-client` | `cd(ssh-cyberia-client)` or dispatch | deploy                        |
+
+## KubeAdm Cluster Topology
+
+```mermaid
+graph TD
+    internet(["🌐 Internet\nHTTPS / WSS"])
+
+    subgraph cluster["KubeAdm Cluster"]
+        subgraph contour["Contour / Envoy — L7 proxy · cert-manager TLS"]
+            proxy["HTTPProxy\n*.cyberiaonline.com"]
+        end
+
+        subgraph dd_cyberia["dd-cyberia Pod  (blue/green)"]
+            engine["Node.js Engine  :4005-4014\nExpress · MongoDB · Valkey · Mailer"]
+            grpc_srv["gRPC server  :50051\ncluster-internal only"]
+            engine --- grpc_srv
+        end
+
+        subgraph mmo_server["dd-cyberia-mmo-server Pod"]
+            go_srv["Go game server  :8081\nWebSocket /ws · REST /api/v1/*"]
+        end
+
+        subgraph mmo_client["dd-cyberia-mmo-client Pod"]
+            wasm["WASM static server  :8082\ncyberia-client (Raylib/Emscripten)"]
+        end
+
+        cfg["ConfigMap  underpost-config\n.env.production"]
+    end
+
+    internet -->|HTTPS/WSS| proxy
+    proxy -->|"www.cyberiaonline.com → :4005"| engine
+    proxy -->|"server.cyberiaonline.com → :8081"| go_srv
+    proxy -->|"client.cyberiaonline.com → :8082"| wasm
+    grpc_srv -->|"gRPC  GetFullInstance\nGetObjectLayerBatch\nHot-reload"| go_srv
+    cfg -.->|env vars| dd_cyberia
+    cfg -.->|env vars| mmo_server
+```