@underpostnet/cyberia 3.2.80

package/src/client/public/cyberia-docs/OFF-CHAIN-ECONOMY.md

@@ -0,0 +1,309 @@
+# Off-Chain Economy: Fountain & Sink Architecture
+
+**Module:** `cyberia-server/src/economy.go` · `src/api/cyberia-instance-conf`
+
+> **Status:** Alpha (sinks disabled by default; all values reset on reconnect).
+> **On-chain bridge:** CKY ERC-1155 token (ID 0) on Hyperledger Besu.
+> The bridge protocol stays aligned with the project's CKY tokenomics model.
+
+---
+
+## 1. Model Overview
+
+Cyberia Online uses the **Fountain & Sink** economy — the industry standard for sustainable in-game economies, pioneered by _Ultima Online_ and refined in _EVE Online_ and _World of Warcraft_.
+
+```
+                ┌─────────────────────────────┐
+                │         FOUNTAINS           │
+                │  (inject coins into economy) │
+                │                             │
+                │  botSpawnCoins  ──► Bot      │
+                │  playerSpawnCoins ► Player   │
+                └──────────────┬──────────────┘
+                               │ new coins
+                               ▼
+                ┌──────────────────────────────┐
+                │      CIRCULATING SUPPLY      │
+                │   (player & bot wallets)     │
+                └──────┬───────────────────────┘
+                       │
+          ┌────────────┴────────────┐
+          │   KILL LOOT             │  zero-sum drop race
+          │   victim stake → grid drop    │
+          │   contributors race to collect│
+          │   (players + bots, any victim)│
+          │                         │
+          │  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 wallet to `botSpawnCoins`. Supply bounded by player kill rate.         |
+| **Players are zero-sum**      | A player kill scatters the victim's coins as a grid drop but creates no new ones — redistribution only. A player who dies to bots still drops coins (per `coinKillPercentVsPlayer`); the contributing bots may reclaim them. |
+| **Loot is a contributor race**| Every kill scatters the victim's configured `dropItemIds` (plus coins where the entity carries them); only damage contributors may collect, and the first eligible collider wins. Damage amount is irrelevant — only contribution counts. The contributor set is tracked uniformly for **any** victim (player, bot, resource) and includes both players and the bots that dealt damage: a contributing player collects on collision, a contributing bot has the loot transferred to it on collision. A death with no contributor drops nothing. |
+| **Kill floor**                | `coinKillMinAmount` guarantees every successful kill pays out even against a near-empty wallet. |
+| **Sinks scale with activity** | Fees burn a fraction — more activity = more burn, preventing indefinite inflation.              |
+
+---
+
+## 2. Configuration Structure
+
+Economy parameters live in `CyberiaInstanceConf.economyRules`. A document without an `economyRules` sub-document receives canonical defaults automatically.
+
+### 2.1 JavaScript Defaults (`cyberia-server-defaults.js`)
+
+```javascript
+economyRules: {
+  // ── Fountains ──────────────────────────────────────────
+  botSpawnCoins:    50,   // coins on bot spawn/respawn (infinite mint)
+  playerSpawnCoins: 50,   // guest starting wallet (resets on reconnect)
+
+  // ── Kill Transfer ───────────────────────────────────────
+  coinKillPercentVsBot:    0.40, // 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 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;
+}
+```
+
+### 2.3 Go Server (`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 (`economy.go`)
+
+All economy logic is encapsulated in a single file enforcing 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) |
+| `botCoinDropAmount(bot)`              | `collision.go handleBotDeath`      | Coin stake a dead bot scatters as a grid drop        |
+| `pvpCoinDropAmount(player)`           | `collision.go handlePlayerDeath`   | Coin stake a dead player scatters as a grid drop     |
+| `SinkRespawnCost(player)`             | `collision.go handlePlayerDeath`   | Burns `respawnCostPercent`% of player coins          |
+| `SinkPortalFee(player)`               | Portal handler                     | Burns flat `portalFee` coins on portal use           |
+| `SinkCraftingFee(player, item)`       | Craft handler                      | Burns `craftingFeePercent`% on crafting              |
+
+### Kill Loot Logic
+
+Every kill scatters the victim's configured `dropItemIds` (resolved per entity
+via the entity-type default build) plus its coin stake — where the entity carries
+coins — as grid drop tokens (`spawnDrops`, `loot.go`). Contribution is tracked
+uniformly for **any** victim (player, bot, resource): players and the bots that
+dealt damage all join the set. Only contributors may collect — the amount of
+damage does not matter, only that the entity contributed — and collection is a
+race: the first eligible collider with the settled token wins it. A contributing
+player collects on collision; a contributing bot has the loot transferred to it
+on collision. A death with no contributor drops nothing.
+
+```
+OnDeath(victim):
+  contributors = players who damaged victim
+                 + bots who damaged victim    // uniform for any victim type
+  if empty(contributors): return             // no contributor → no drop
+
+  // Item drops (all victim types): the victim's configured dropItemIds.
+  for itemID in victim.dropItemIds:
+    spawnDropToken(itemID × 1, contributors)
+
+  // Coin drop (only entities that carry coins: players, bots — resources = 0).
+  rate = coinKillPercentVsBot     if victim is bot     (PvE)
+         coinKillPercentVsPlayer  if victim is player  (PvP or bot-kills-player)
+
+  amount = max(floor(victim.coins × rate), coinKillMinAmount)
+  amount = min(amount, victim.coins)          // can't drop more than available
+                                              // (bots mint up to botSpawnCoins)
+
+  victim.coins -= amount                      // bots re-mint on respawn
+  if amount > 0: spawnDropToken(coin × amount, contributors)
+  // No coin FCT — the victim's balance change surfaces in the inventory-bar
+  // quantity FX, and the gain side in the collector's loot grid.
+```
+
+---
+
+## 4. Coin Balance Architecture
+
+Coins use a **flat + display split** design:
+
+| Field                         | Type                                                  | Role                                                              |
+| ----------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------- |
+| `entity.Coins`                | `uint32`                                              | **Single source of truth** — O(1) read/write for all economy math |
+| `coinItemId` ObjectLayer slot | `ObjectLayerState { Active: false, Quantity: Coins }` | **Display only** — synced by `syncCoinOL()` on every mutation     |
+
+**Why split:**
+
+- Economy math uses `Coins` directly (O(1)); no OL iteration.
+- Coin slot is always `Active: false` — the inventory UI automatically renders it with a lock indicator (non-activable).
+- No risk of coin OL being activated by the `item_activation` handler.
+
+---
+
+## 5. Floating Combat Text (FCT) Wire Protocol
+
+Economy events trigger client-side visual feedback via the binary AOI protocol.
+
+**Coin FCT (14 bytes, fixed):**
+
+```
+MsgTypeFCT = 0x04
+
+Offset  Size  Field
+──────  ────  ─────────────────────────────
+  0      u8   message type (0x04)
+  1      u8   fct_type (see table)
+  2      f32  world_x (entity position)
+  6      f32  world_y
+ 10      u32  value (always positive; sign implied by type)
+```
+
+**Item FCT (variable length):**
+
+```
+MsgTypeItemFCT = 0x05
+
+Offset  Size  Field
+──────  ────  ─────────────────────────────
+  0      u8   message type (0x05)
+  1      u8   fct_type (FCTTypeItemGain or FCTTypeItemLoss)
+  2      f32  world_x
+  6      f32  world_y
+ 10      u32  quantity
+ 14      u8   itemId length
+ 15      str  itemId bytes
+```
+
+| `fct_type` | Constant            | Color  | Display        | Status |
+| ---------- | ------------------- | ------ | -------------- | ------ |
+| `0x00`     | `FCTTypeDamage`     | Red    | `-N` HP lost   | active |
+| `0x01`     | `FCTTypeRegen`      | Green  | `+N` HP gained | active |
+| `0x02`     | `FCTTypeCoinGain`   | Yellow | `+N` coins     | retired |
+| `0x03`     | `FCTTypeCoinLoss`   | Yellow | `-N` coins     | retired |
+| `0x04`     | `FCTTypeItemGain`   | Cyan   | `+N ItemID`    | retired |
+| `0x05`     | `FCTTypeItemLoss`   | Purple | `-N ItemID`    | retired |
+
+One uniform visibility rule: **every combat FCT (damage and regen, on any
+entity — player, bot, or resource) is broadcast with its exact amount to every
+player whose AOI covers the event. All viewers see the identical message.**
+
+Coin and item quantity changes emit no FCT: gains surface in the loot grid and
+balance changes in the inventory-bar quantity FX (`fx_inventory_bar_qty`),
+which plays a `+N`/`-N` popup on the affected slot. The retired wire values
+are never reused.
+
+---
+
+## 6. MongoDB Document Example
+
+```json
+{
+  "instanceCode": "alpha-01",
+  "economyRules": {
+    "botSpawnCoins": 50,
+    "playerSpawnCoins": 50,
+    "coinKillPercentVsBot": 0.4,
+    "coinKillPercentVsPlayer": 0.15,
+    "coinKillMinAmount": 10,
+    "respawnCostPercent": 0.0,
+    "portalFee": 0,
+    "craftingFeePercent": 0.0
+  }
+}
+```
+
+---
+
+## 7. gRPC Config Builder
+
+The `toInstanceConfig()` function in `grpc-server.js` resolves `economyRules` with a two-tier fallback:
+
+```
+priority:  gc.economyRules.field    (instance document in MongoDB)
+         → fb.economyRules.field    (CYBERIA_INSTANCE_CONF_DEFAULTS — always set)
+```
+
+---
+
+## 8. On-Chain Bridge
+
+The off-chain `coin` balance maps to the on-chain **CKY token (ERC-1155 Token ID 0)** on Hyperledger Besu:
+
+```
+Off-chain Coins (uint32)
+    ↕  conversion (via cryptokoyn.net withdrawal protocol)
+On-chain CKY (ERC-1155, Token ID 0, 18-decimal precision)
+```
+
+**Bridge mechanics:**
+
+- **Withdrawal:** Player requests conversion of off-chain coins to on-chain CKY via cryptokoyn.net.
+- **Deposit:** Player deposits on-chain CKY to top up off-chain balance.
+- **CKY Minting Fee:** Converting off-chain items to ERC-1155 tokens requires a CKY fee — the primary on-chain sink mechanism.
+
+---
+
+## 9. Enabling Sinks (Alpha → Beta)
+
+To activate economy pressure:
+
+```javascript
+// Update CyberiaInstanceConf in MongoDB for the target instance
+{
+  "economyRules": {
+    "respawnCostPercent":  0.05,  // 5% burned on death
+    "portalFee":           5,     // 5 coins burned per portal use
+    "craftingFeePercent":  0.03   // 3% burned on each crafting action
+  }
+}
+```
+
+The Go server picks up updated config via gRPC hot-reload (`GetFullInstance` polling at `ENGINE_GRPC_RELOAD_INTERVAL_SEC`).

package/src/client/public/cyberia-docs/QUEST-SYSTEM.md

@@ -0,0 +1,228 @@
+# Quest System
+
+**Module:** `src/api/cyberia-quest` · `src/api/cyberia-quest-progress`
+
+---
+
+## Overview
+
+The Quest System is a **chain/tree-structured progression framework** linking NPC entities, player actions, map coordinates, and item rewards. Quests are the primary mechanism for guided player progression in Cyberia Online.
+
+Quests are defined server-side as MongoDB documents and delivered to the client through the Engine REST API. Progress is tracked per-player in `CyberiaQuestProgress` documents.
+
+> **Implementation status — Alpha (talk / collect / kill):** The Quest and QuestProgress MongoDB schemas and Engine REST API (`src/api/cyberia-quest`, `src/api/cyberia-quest-progress`) are defined and seeded. The Go server fetches quest definitions at instance init and evaluates **all three** objective types authoritatively: `talk` (on `dlg_complete`), `kill` (on victim death, matched by the victim's active skin), and `collect` (idempotent inventory reconcile on item/coin gain). It grants quests — gated by `prerequisiteCodes` (AND logic) — advances steps, delivers rewards via FCT, and unlocks successors on completion. Live progress is pushed to the client over the `dlg_ack` envelope outside the dialogue flow. Quest progress is authoritative **per Go session** (in-memory) and best-effort mirrored to `POST /api/cyberia-quest-progress`; it resets on reconnect. The C client surfaces it through the **Quest Journal** and the **action tab** (offer + reward item slots), populated from the engine REST metadata endpoint `GET /api/cyberia-quest/code/:code` (which falls back to the canonical defaults so the procedural fallback world is playable without a seed).
+
+---
+
+## Data Model
+
+### CyberiaQuest Schema
+
+```
+CyberiaQuest {
+  code:              String   // stable slug, e.g. "fallback-intro-quest"
+  title:             String
+  description:       String
+
+  // Spatial origin — the NPC/entity cell that grants this quest
+  sourceMapCode:     String
+  sourceCellX:       Number
+  sourceCellY:       Number
+
+  // Chain / tree unlock structure
+  prerequisiteCodes: [String] // AND logic — all must be completed to unlock
+  unlocksQuestCodes: [String] // quests activated on completion (chain or tree)
+
+  // Ordered linear step sequence
+  steps: [{
+    id:          String
+    description: String
+    objectives: [{
+      type:     String  // 'collect' | 'talk' | 'kill'
+      itemId:   String  // semantic target (see Objective Types below)
+      quantity: Number  // default: 1
+    }]
+  }]
+
+  // Rewards granted on quest completion
+  rewards: [{
+    itemId:   String
+    quantity: Number
+  }]
+}
+```
+
+### CyberiaQuestProgress Schema
+
+```
+CyberiaQuestProgress {
+  playerId:   String   // Go server player UUID
+  questCode:  String   // references CyberiaQuest.code
+  status:     String   // 'active' | 'completed'
+
+  stepProgress: [{
+    stepId: String
+    objectiveProgress: [{
+      current:  Number  // current count toward objective
+      required: Number  // denormalized from quest definition
+    }]
+  }]
+
+  startedAt:   Date
+  completedAt: Date | null
+}
+```
+
+**Completeness is always computed, never stored.** A step is complete when all `objectiveProgress[i].current >= objectiveProgress[i].required`. The active step is always the first step where not all objectives are done.
+
+---
+
+## Objective Types
+
+| `type`    | `itemId` semantics                                             | Completion trigger                                                                                 |
+| --------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `collect` | ObjectLayer item ID that must appear in the player's inventory | Player inventory holds `>= quantity` of `itemId` (coins via the flat balance) — reconciled on every gain |
+| `talk`    | Active **skin** item ID of the NPC to interact with           | Player completes a `dlg_complete` whose NPC active skin `=== itemId` and `dialogCode ∈ questDialogueCodes` |
+| `kill`    | Skin item ID of the target entity (e.g. `"scp-2040"`)         | Player kills an entity whose active skin matches `itemId`                                          |
+
+---
+
+## Quest Graph (Chain and Tree)
+
+Quests form a **directed acyclic graph** via `prerequisiteCodes` → `unlocksQuestCodes`:
+
+```mermaid
+graph LR
+    A["intro-quest\n(no prerequisites)"]
+    B["village-quest\n(requires: intro-quest)"]
+    C["forest-quest\n(requires: intro-quest)"]
+    D["final-quest\n(requires: village-quest AND forest-quest)"]
+
+    A -->|unlocksQuestCodes| B
+    A -->|unlocksQuestCodes| C
+    B -->|unlocksQuestCodes| D
+    C -->|unlocksQuestCodes| D
+```
+
+**AND logic on prerequisites:** A quest only becomes available when **all** listed `prerequisiteCodes` are completed.
+
+**Tree branching:** A quest can list multiple `unlocksQuestCodes`, enabling parallel quest branches that reconverge later.
+
+---
+
+## Quest Lifecycle
+
+```mermaid
+sequenceDiagram
+    participant P as Player
+    participant G as Go Server
+    participant E as Engine (Node.js)
+    participant DB as MongoDB
+
+    P->>G: Tap NPC + Take Quest (quest_accept) — quest bound to the NPC's cell
+    G->>E: POST /api/cyberia-quest-progress (grant quest)
+    E->>DB: Create CyberiaQuestProgress { status: 'active' }
+    E-->>G: Progress document
+
+    loop For each game event (kill / collect / talk)
+        G->>E: PATCH /api/cyberia-quest-progress (increment objective)
+        E->>DB: objectiveProgress[i].current++
+        E-->>G: Updated progress
+    end
+
+    Note over G,E: All steps complete
+    G->>E: PATCH status → 'completed'
+    E->>DB: completedAt = now
+    G->>E: GET unlocksQuestCodes → activate successor quests
+    E->>DB: Create CyberiaQuestProgress for each unlocked quest
+    G-->>P: Deliver reward items (inventory grant + FCT ItemGain events)
+```
+
+---
+
+## Spatial Binding
+
+Each `CyberiaQuest` can declare `sourceMapCode + sourceCellX + sourceCellY`, linking it to the map entity at that cell. This binding is used during instance initialization:
+
+- `instance_loader.go` reads `CyberiaEntity.initCellX/initCellY` and correlates with quest `sourceCellX/sourceCellY` to assign quest-granting behaviors to the correct NPC entity at world construction time.
+- The `ObjectLayerEngineModal` (Engine UI) allows editors to assign quest codes to entity cells visually.
+
+---
+
+## Reward Delivery
+
+On quest completion, the Engine grants each `rewards[].{itemId, quantity}` to the player's inventory:
+
+- Off-chain items are added to the player's `ObjectLayers` array in the Go server.
+- If the item has an on-chain ERC-1155 token, the server relayer calls `mint(playerAddress, tokenId, quantity)` on the `ObjectLayerToken` contract.
+- FCT `ItemGain` events (`MsgTypeItemFCT`, `FCTTypeItemGain`) are broadcast to the client for visual feedback.
+
+---
+
+## Step Progression Rules
+
+1. Steps are always processed in **declared order** — step N cannot advance until step N-1 is complete.
+2. Within a step, all objectives must be satisfied (any order).
+3. Quests do not fail — they remain `active` until completed or explicitly abandoned.
+4. The `required` count is **denormalized** from the quest definition into each `objectiveProgress` record at quest grant time, enabling O(1) progress checks without re-fetching the quest definition.
+
+---
+
+## Quest Journal (client)
+
+The C client keeps a local `quest_store` (in `cyberia-client/src/ui/quest_store.c`)
+populated from two server sources — **no extra REST calls**:
+
+- `init_data.quests[]` — the player's active/completed snapshot on connect.
+- `dlg_ack.quests[]` — live upserts as quests are granted or completed.
+
+The **Quest Journal** modal (`ui/quest_journal.c`) renders this store on the
+right side below the map info modal: a three-section tree (Active / Completed /
+Failed), each section independently collapsible via the shared `ui_toggle`
+component, each with its own 10-per-page pagination cursor. The interaction
+bubble column on the left is collapsible by the same toggle pattern. Both panels
+default collapsed on screens narrower than 600 px. Collapse state is not
+persisted across sessions.
+
+Each server quest snapshot entry carries `{ code, title, description, status,
+activeStep, objectivesText }` so the journal can render rows and inline detail
+without re-fetching the quest definition.
+
+---
+
+## Indexes
+
+```javascript
+// CyberiaQuest
+{ code: 1 }  // unique
+{ sourceMapCode: 1, sourceCellX: 1, sourceCellY: 1 }
+
+// CyberiaQuestProgress
+{ playerId: 1, questCode: 1 }  // unique
+{ playerId: 1, status: 1 }
+```
+
+---
+
+## Example Quest Document
+
+```json
+{
+  "code": "wason-intro",
+  "title": "Meet Wason",
+  "description": "Find the village elder to begin your journey.",
+  "sourceMapCode": "cyberia-village",
+  "sourceCellX": 12,
+  "sourceCellY": 8,
+  "prerequisiteCodes": [],
+  "unlocksQuestCodes": ["wason-collection"],
+  "steps": [
+    {
+      "id": "step-talk",
+      "description": "Speak with Wason.",
+      "objectives": [{ "type": "talk", "itemId": "wason", "quantity": 1 }]
+    }
+  ],
+  "rewards": [{ "itemId": "health-potion", "quantity": 2 }]
+}
+```