cyberia 3.1.3 → 3.2.9

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

@@ -0,0 +1,279 @@
+# 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.
+> See [WHITE-PAPER.md](WHITE-PAPER.md) §7 for the bridge protocol.
+
+---
+
+## 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 TRANSFER         │  zero-sum 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 wallet to `botSpawnCoins`. Supply bounded by player kill rate.         |
+| **Players are zero-sum**      | Killing a player transfers coins but creates no new ones. PvP is redistribution only.           |
+| **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-instance-conf.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) |
+| `ExecuteKillTransfer(caster, victim)` | `skill.go HandleOnKillSkills`      | Transfers coins based on kill scenario               |
+| `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 Transfer Logic
+
+```
+ExecuteKillTransfer(caster, victim):
+
+  if caster=Player, victim=Bot    → rate = coinKillPercentVsBot     (PvE farming)
+  if caster=Player, victim=Player → rate = coinKillPercentVsPlayer  (PvP)
+  if caster=Bot,    victim=Player → rate = coinKillPercentVsPlayer  (bot kills player)
+  if caster=Bot,    victim=Bot    → rate = coinKillPercentVsBot     (bot-on-bot)
+
+  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, worldX, worldY, transfer)
+  → sendFCT(victim, FCTTypeCoinLoss,  worldX, worldY, transfer)
+```
+
+---
+
+## 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        |
+| ---------- | ----------------- | ------ | -------------- |
+| `0x00`     | `FCTTypeDamage`   | Red    | `-N` HP lost   |
+| `0x01`     | `FCTTypeRegen`    | Green  | `+N` HP gained |
+| `0x02`     | `FCTTypeCoinGain` | Yellow | `+N` coins     |
+| `0x03`     | `FCTTypeCoinLoss` | Yellow | `-N` coins     |
+| `0x04`     | `FCTTypeItemGain` | Cyan   | `+N ItemID`    |
+| `0x05`     | `FCTTypeItemLoss` | Purple | `-N ItemID`    |
+
+---
+
+## 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,206 @@
+# 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 — Pre-alpha:** The Quest and QuestProgress MongoDB schemas and Engine REST API (`src/api/cyberia-quest`, `src/api/cyberia-quest-progress`) are defined and seeded. Go server integration (quest tracking, objective evaluation, reward delivery via FCT) is planned for the **Alpha milestone**. For pre-alpha, quest progress is ephemeral: it lives in the client session only and resets on page reload.
+
+---
+
+## 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 contains `>= quantity` of `itemId`                                                |
+| `talk`    | `CyberiaAction.provideItemId` of the NPC to interact with      | Player triggers a talk action where `provideItemId === itemId` and all `questDialogueCodes` viewed |
+| `kill`    | Skin item ID of the target entity (e.g. `"wason"`)             | 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 with grantQuestCode
+    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.
+
+---
+
+## 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 }]
+}
+```