cyberia 3.1.3 → 3.2.5

package/src/api/cyberia-instance-conf/cyberia-instance-conf.defaults.js

@@ -0,0 +1,413 @@
+/**
+ * Canonical default values and type definitions for a CyberiaInstanceConf document.
+ *
+ * Single source of truth used by:
+ *   - cyberia-instance-conf.model.js  — Mongoose schema `default:` declarations
+ *   - grpc-server.js                  — FALLBACK_CONFIG_DEFAULTS for missing instances
+ *   - bin/cyberia.js                  — imports ITEM_TYPES for asset type enumeration
+ *
+ * @module src/api/cyberia-instance-conf/cyberia-instance-conf.defaults.js
+ */
+
+// ── Item type registry ───────────────────────────────────────────────────────
+/**
+ * Canonical set of ObjectLayer item type names, used as asset directory names
+ * and as the `data.item.type` discriminator on ObjectLayer documents.
+ *
+ * Values intentionally equal their keys — the object is an enum of valid
+ * strings, NOT an integer→z-index map.  Render layer ordering (z-order) is
+ * determined separately by `get_priority_for_type()` in entity_render.c.
+ *
+ * @constant
+ * @type {Readonly<{floor:string, skin:string, breastplate:string, weapon:string, skill:string, coin:string}>}
+ */
+export const ITEM_TYPES = Object.freeze({
+  floor: 'floor',
+  skin: 'skin',
+  breastplate: 'breastplate',
+  weapon: 'weapon',
+  skill: 'skill',
+  coin: 'coin',
+});
+
+// ── Entity Status Indicator (ESI) registry ───────────────────────────────────
+/**
+ * Canonical mapping of server-computed entity status icon IDs to the ui-icon
+ * filename stem served from /assets/ui-icons/{iconId}.png.
+ *
+ * The Go server assigns a status u8 per entity each AOI tick.  The C client
+ * receives this mapping dynamically via init_data.statusIcons and uses it to
+ * resolve the u8 to an icon filename at runtime.  This JS-side copy is the
+ * configuration source of truth; it supports instance-specific icon overrides.
+ *
+ * Industry standard name: "Overhead Status Indicator" (OSI).
+ *   WoW: nameplate colour + debuff icons
+ *   FFXIV: enmity/claim icons (red ◆, yellow ●)
+ *   UO: skull for murderers, shield for invulnerables
+ *
+ * IMPORTANT: The numeric IDs MUST stay in sync with:
+ *   - Go:  cyberia-server/src/entity_status.go   (StatusNone … StatusDead)
+ *
+ * @constant
+ */
+export const STATUS_ICONS = Object.freeze([
+  {
+    id: 0,
+    name: 'none',
+    iconId: null,
+    bounce: false,
+    borderColor: { r: 70, g: 70, b: 120, a: 200 },
+    description: 'No icon (skill/coin bots, world objects)',
+  },
+  {
+    id: 1,
+    name: 'passive',
+    iconId: 'arrow-down-gray',
+    bounce: false,
+    borderColor: { r: 130, g: 140, b: 160, a: 200 },
+    description: 'Passive bot — no weapon, non-aggressive',
+  },
+  {
+    id: 2,
+    name: 'hostile',
+    iconId: 'arrow-down-red',
+    bounce: true,
+    borderColor: { r: 210, g: 50, b: 50, a: 240 },
+    description: 'Hostile bot — has weapon, will aggro',
+  },
+  {
+    id: 3,
+    name: 'frozen',
+    iconId: 'chat',
+    bounce: true,
+    borderColor: { r: 80, g: 160, b: 220, a: 240 },
+    description: 'Player in FrozenInteractionState (modal open)',
+  },
+  {
+    id: 4,
+    name: 'player',
+    iconId: 'arrow-down',
+    bounce: false,
+    borderColor: { r: 60, g: 190, b: 90, a: 240 },
+    description: 'Normal player — alive, not frozen',
+  },
+  {
+    id: 5,
+    name: 'dead',
+    iconId: 'skull',
+    bounce: false,
+    borderColor: { r: 160, g: 130, b: 200, a: 200 },
+    description: 'Entity is dead / respawning',
+  },
+]);
+
+// ── Equipment rules ──────────────────────────────────────────────────────────
+/**
+ * Equipment rules govern which ObjectLayer item types can be simultaneously
+ * active on a character entity and enforce the one-active-per-type constraint.
+ *
+ * The server validates every item_activation request against these rules:
+ *   1. Only item types listed in `activeItemTypes` may be activated.
+ *   2. When `onePerType` is true (default), activating an item of a given type
+ *      automatically deactivates any other active item of the same type.
+ *   3. When `requireSkin` is true, the player must always have at least one
+ *      active skin if they own any skin-type items.
+ *
+ * Item types NOT listed in `activeItemTypes` (e.g. 'coin', 'floor') are
+ * considered non-activable and their activation requests are rejected.
+ *
+ * @constant
+ * @type {Readonly<{activeItemTypes:string[], onePerType:boolean, requireSkin:boolean}>}
+ */
+export const EQUIPMENT_RULES_DEFAULTS = Object.freeze({
+  // Item types that players are allowed to activate (equip).
+  // Types not in this list are non-activable (coins, floors, etc.).
+  activeItemTypes: ['skin', 'breastplate', 'weapon'],
+  // Enforce at most one active item per item type.
+  onePerType: true,
+  // Require at least one active skin when the player owns any skin.
+  requireSkin: true,
+});
+
+// ── Entity type defaults ─────────────────────────────────────────────────────
+/**
+ * Per-entity-type rendering defaults.
+ *
+ * Each entry defines the canonical visual configuration for ONE entity type:
+ *
+ *   entityType  — string used by the Go server and C client to identify the
+ *                 entity category (matches entity_type_str in game_render.c
+ *                 and Behavior for bot sub-types).
+ *   liveItemIds — Array of ObjectLayer item IDs applied when the entity is
+ *                 alive/active and no explicit items are assigned.  Empty array =
+ *                 no OL fallback, rely on colorKey solid fill.
+ *   deadItemIds — Array of ObjectLayer item IDs for the dead / ghost / respawning
+ *                 state.  Empty array = no dead-state OL; same solid fill as live.
+ *                 Replaces the old flat ghostItemId field for players.
+ *   colorKey    — Named palette colour key (see colors in CYBERIA_INSTANCE_CONF_DEFAULTS).
+ *                 Used as solid-colour fallback when the entity carries NO active
+ *                 ObjectLayer items, or while atlas textures are still loading.
+ *                 The Go server stamps this colour on every newly spawned entity
+ *                 so the binary AOI stream always carries the correct RGBA.
+ *
+ * Character entity types:
+ *   player       — the local (self) player
+ *   other_player — remote players in the AOI
+ *   bot          — AI-controlled entities (behavior: hostile / passive)
+ *   skill        — skill-spawned projectile bot (behavior = "skill");
+ *                  NOT placed in maps — created at runtime by skill_projectile.go
+ *                  when a player/bot triggers a projectile skill.
+ *                  liveItemIds carries the skill-type OL (the projectile sprite).
+ *   coin         — skill-spawned collectible bot (behavior = "coin");
+ *                  NOT placed in maps — dropped at runtime on entity death.
+ *
+ * World object entity types:
+ *   floor / obstacle / portal / foreground
+ *
+ * @constant
+ * @type {ReadonlyArray<{entityType:string, liveItemIds:string[], deadItemIds:string[], colorKey:string}>}
+ */
+export const ENTITY_TYPE_DEFAULTS = Object.freeze([
+  // ── Characters ─────────────────────────────────────────────────────────
+  {
+    entityType: 'player',
+    liveItemIds: ['anon', 'atlas_pistol_mk2'],
+    deadItemIds: ['ghost'],
+    colorKey: 'PLAYER',
+    // Full default ObjectLayer inventory for newly spawned players.
+    // active:false items appear in the inventory bar but are not worn.
+    // The coin slot is always active:false — coins are non-activable.
+    defaultObjectLayers: [
+      { itemId: 'anon', active: true, quantity: 1 },
+      { itemId: 'atlas_pistol_mk2', active: true, quantity: 1 },
+      { itemId: 'purple', active: false, quantity: 1 },
+      { itemId: 'ghost', active: false, quantity: 1 },
+      { itemId: 'atlas_pistol_mk2_bullet', active: false, quantity: 5 },
+      { itemId: 'lain', active: false, quantity: 1 },
+      { itemId: 'hatchet', active: false, quantity: 1 },
+      { itemId: 'wason', active: false, quantity: 1 },
+      { itemId: 'scp-2040', active: false, quantity: 1 },
+      { itemId: 'punk', active: false, quantity: 1 },
+      { itemId: 'kaneki', active: false, quantity: 1 },
+      { itemId: 'junko', active: false, quantity: 1 },
+      { itemId: 'eiri', active: false, quantity: 1 },
+      { itemId: 'alex', active: false, quantity: 1 },
+      { itemId: 'agent', active: false, quantity: 1 },
+      { itemId: 'coin', active: false, quantity: 0 },
+    ],
+  },
+  {
+    entityType: 'other_player',
+    liveItemIds: ['anon', 'atlas_pistol_mk2'],
+    deadItemIds: ['ghost'],
+    colorKey: 'OTHER_PLAYER',
+    defaultObjectLayers: [
+      { itemId: 'anon', active: true, quantity: 1 },
+      { itemId: 'atlas_pistol_mk2', active: true, quantity: 1 },
+      { itemId: 'purple', active: false, quantity: 1 },
+      { itemId: 'ghost', active: false, quantity: 1 },
+      { itemId: 'atlas_pistol_mk2_bullet', active: false, quantity: 5 },
+      { itemId: 'lain', active: false, quantity: 1 },
+      { itemId: 'hatchet', active: false, quantity: 1 },
+      { itemId: 'wason', active: false, quantity: 1 },
+      { itemId: 'scp-2040', active: false, quantity: 1 },
+      { itemId: 'punk', active: false, quantity: 1 },
+      { itemId: 'kaneki', active: false, quantity: 1 },
+      { itemId: 'junko', active: false, quantity: 1 },
+      { itemId: 'eiri', active: false, quantity: 1 },
+      { itemId: 'alex', active: false, quantity: 1 },
+      { itemId: 'agent', active: false, quantity: 1 },
+      { itemId: 'coin', active: false, quantity: 0 },
+    ],
+  },
+  {
+    entityType: 'bot',
+    liveItemIds: ['purple'],
+    deadItemIds: ['ghost'],
+    colorKey: 'BOT',
+    defaultObjectLayers: [
+      { itemId: 'purple', active: true, quantity: 1 },
+      { itemId: 'coin', active: false, quantity: 0 },
+    ],
+  },
+  {
+    entityType: 'skill',
+    liveItemIds: ['atlas_pistol_mk2_bullet'],
+    deadItemIds: [],
+    colorKey: 'SKILL',
+    defaultObjectLayers: [{ itemId: 'atlas_pistol_mk2_bullet', active: true, quantity: 1 }],
+  },
+  {
+    entityType: 'coin',
+    liveItemIds: ['coin'],
+    deadItemIds: [],
+    colorKey: 'COIN',
+    defaultObjectLayers: [{ itemId: 'coin', active: true, quantity: 1 }],
+  },
+  // ── World objects ───────────────────────────────────────────────────────
+  { entityType: 'floor', liveItemIds: ['grass'], deadItemIds: [], colorKey: 'FLOOR', defaultObjectLayers: [] },
+  { entityType: 'obstacle', liveItemIds: [], deadItemIds: [], colorKey: 'OBSTACLE', defaultObjectLayers: [] },
+  { entityType: 'portal', liveItemIds: [], deadItemIds: [], colorKey: 'PORTAL', defaultObjectLayers: [] },
+  { entityType: 'portal', liveItemIds: [], deadItemIds: [], colorKey: 'PORTAL_INTER_PORTAL', defaultObjectLayers: [] },
+  { entityType: 'portal', liveItemIds: [], deadItemIds: [], colorKey: 'PORTAL_INTER_RANDOM', defaultObjectLayers: [] },
+  { entityType: 'portal', liveItemIds: [], deadItemIds: [], colorKey: 'PORTAL_INTRA_RANDOM', defaultObjectLayers: [] },
+  { entityType: 'portal', liveItemIds: [], deadItemIds: [], colorKey: 'PORTAL_INTRA_PORTAL', defaultObjectLayers: [] },
+  { entityType: 'foreground', liveItemIds: [], deadItemIds: [], colorKey: 'FOREGROUND', defaultObjectLayers: [] },
+]);
+
+// ── Instance configuration defaults ─────────────────────────────────────────
+export const CYBERIA_INSTANCE_CONF_DEFAULTS = {
+  // ── Rendering / camera ─────────────────────────────────────────────
+  cellSize: 45,
+  fps: 60,
+  interpolationMs: 100,
+  defaultObjWidth: 1,
+  defaultObjHeight: 1,
+  cameraSmoothing: 0.1,
+  cameraZoom: 1.0,
+  defaultWidthScreenFactor: 1,
+  defaultHeightScreenFactor: 1,
+  devUi: false,
+
+  /**
+   * Named colour palette forwarded to Go server and C client via the WebSocket
+   * init payload.  Entity colour keys (PLAYER, BOT, SKILL, …) are consumed via
+   * entityDefaults[n].colorKey as the solid fallback for that entity type when
+   * no ObjectLayer items are assigned.
+   * The WEAPON key is kept for UI use (weapon-stat highlights) only.
+   */
+  colors: [
+    // ── World ─────────────────────────────────────────────────────
+    { key: 'BACKGROUND', r: 30, g: 30, b: 30, a: 255 }, // rgba(30, 30, 30, 1)
+    { key: 'FLOOR_BACKGROUND', r: 45, g: 45, b: 45, a: 255 }, // rgba(45, 45, 45, 1)
+    { key: 'FLOOR', r: 60, g: 60, b: 60, a: 255 }, // rgba(60, 60, 60, 1)
+    { key: 'OBSTACLE', r: 80, g: 80, b: 80, a: 255 }, // rgba(80, 80, 80, 1)
+    { key: 'PORTAL', r: 0, g: 200, b: 200, a: 255 }, // rgba(0, 200, 200, 1) — generic fallback
+    { key: 'PORTAL_INTER_PORTAL', r: 0, g: 200, b: 200, a: 255 }, // cyan — to portal on another map
+    { key: 'PORTAL_INTER_RANDOM', r: 80, g: 130, b: 255, a: 255 }, // blue — to random pos on another map
+    { key: 'PORTAL_INTRA_RANDOM', r: 220, g: 200, b: 50, a: 255 }, // yellow — to random pos on same map
+    { key: 'PORTAL_INTRA_PORTAL', r: 200, g: 80, b: 200, a: 255 }, // magenta — to portal on same map
+    { key: 'FOREGROUND', r: 255, g: 255, b: 255, a: 189 }, // rgba(255, 255, 255, 0.73)
+    // ── Entity solid-colour fallbacks (matched by entityDefaults[n].colorKey) ──
+    { key: 'PLAYER', r: 0, g: 255, b: 0, a: 255 }, // rgba(0, 255, 0, 1)
+    { key: 'OTHER_PLAYER', r: 128, g: 128, b: 255, a: 255 }, // rgba(128, 128, 255, 1)
+    { key: 'BOT', r: 255, g: 128, b: 0, a: 255 }, // rgba(255, 128, 0, 1)
+    { key: 'GHOST', r: 200, g: 200, b: 255, a: 100 }, // rgba(200, 200, 255, 0.39)
+    { key: 'COIN', r: 255, g: 215, b: 0, a: 255 }, // rgba(255, 215, 0, 1)
+    { key: 'SKILL', r: 255, g: 255, b: 50, a: 255 }, // rgba(255, 255, 50, 1)
+    // ── UI-only ────────────────────────────────────────────────────
+    { key: 'WEAPON', r: 180, g: 50, b: 50, a: 255 }, // rgba(180, 50, 50, 1)
+    // ── Interaction overlay — self-player bubble/panel border ──────
+    { key: 'SELF_BORDER', r: 220, g: 190, b: 60, a: 240 }, // rgba(220, 190, 60, 0.94) — gold
+  ],
+
+  // ── World / AOI ────────────────────────────────────────────────────
+  aoiRadius: 10,
+  portalHoldTimeMs: 1000,
+  portalSpawnRadius: 3,
+
+  // ── Entity base stats ──────────────────────────────────────────────
+  entityBaseSpeed: 5,
+  entityBaseMaxLife: 100,
+  entityBaseActionCooldownMs: 500,
+  entityBaseMinActionCooldownMs: 100,
+
+  // ── Bot defaults ───────────────────────────────────────────────────
+  botAggroRange: 10,
+
+  // ── Player defaults ────────────────────────────────────────────────
+  defaultPlayerWidth: 2,
+  defaultPlayerHeight: 2,
+  playerBaseLifeRegenMin: 0.5,
+  playerBaseLifeRegenMax: 1.5,
+  sumStatsLimit: 500,
+  maxActiveLayers: 4,
+  initialLifeFraction: 1.0,
+
+  // ── Combat / death ─────────────────────────────────────────────────
+  respawnDurationMs: 3000,
+  collisionLifeLoss: 10,
+
+  // ── Economy — Fountain & Sink Model ────────────────────────────────
+  //
+  // All economy parameters live under a single `economyRules` sub-document,
+  // mirroring the `skillRules` pattern used by the skill system.
+  //
+  // This system follows the Fountain & Sink model used by industry-standard
+  // MMORPGs (Ultima Online, EverQuest, WoW, EVE Online).
+  //   Fountains  — inject new coins into the economy on spawn events.
+  //   Kill Transfer — zero-sum redistribution between kill participants.
+  //   Sinks      — destroy coins permanently (alpha: all disabled / 0).
+  //
+  // On-chain bridge (future):
+  //   Off-chain coins map 1-to-1 with the CKY token (token ID 0) of the
+  //   ObjectLayerToken ERC-1155 contract on Hyperledger Besu.  On auth the
+  //   server credits the on-chain balance and this wallet becomes a hot cache.
+  //   See hardhat/WHITE-PAPER.md §7 "Tokenomics" and OFF_CHAIN_ECONOMY.md.
+  economyRules: {
+    // ── Fountains ────────────────────────────────────────────────────
+    // Coins bots carry at spawn and on every respawn (infinite mint).
+    // Bots always reset to this value so the PvE reward loop never dries up.
+    botSpawnCoins: 50,
+    // Player starting wallet. No persistence — resets on reconnect (guest mode).
+    // Persists only when authenticated with an on-chain wallet (future).
+    playerSpawnCoins: 50,
+
+    // ── Kill Transfer (zero-sum redistribution) ───────────────────────
+    // Fraction [0,1] of victim coins taken per kill when killing a bot (PvE).
+    coinKillPercentVsBot: 0.4,
+    // Fraction [0,1] of victim coins taken in PvP — intentionally gentler.
+    coinKillPercentVsPlayer: 0.15,
+    // Hard floor per kill: guarantees at least this many coins per successful kill.
+    coinKillMinAmount: 10,
+
+    // ── Sinks (alpha stubs — all disabled by default) ─────────────────
+    // Fraction [0,1] of dead player's coins burned on respawn (0 = disabled).
+    respawnCostPercent: 0.0,
+    // Flat coins burned per portal use — travel tax (0 = disabled).
+    portalFee: 0,
+    // Fraction [0,1] of item value burned per crafting action (0 = disabled).
+    craftingFeePercent: 0.0,
+  },
+
+  // ── Regen ──────────────────────────────────────────────────────────
+  lifeRegenChance: 300,
+  maxChance: 10000,
+
+  // ── Entity type rendering defaults ─────────────────────────────────
+  // Replaces flat fields: userDefaultItemId, botDefaultItemId, ghostItemId,
+  // coinItemId, defaultFloorItemId, weaponDefaultItemId.
+  // See ENTITY_TYPE_DEFAULTS for documentation of each field.
+  // liveItemIds / deadItemIds are arrays of ObjectLayer item IDs.
+  entityDefaults: ENTITY_TYPE_DEFAULTS.map((e) => ({ ...e })),
+
+  // ── Entity Status Indicators (ESI) ─────────────────────────────────
+  // Overhead icon mapping — documents the u8→icon relationship.
+  // Stored in config for future instance-specific overrides.
+  // See STATUS_ICONS constant for documentation.
+  statusIcons: STATUS_ICONS.map((s) => ({ ...s })),
+
+  // ── Skill system ───────────────────────────────────────────────────
+  skillConfig: [
+    { triggerItemId: 'atlas_pistol_mk2', logicEventIds: ['atlas_pistol_mk2_logic'] },
+    { triggerItemId: 'coin', logicEventIds: ['coin_drop_or_transaction'] },
+    { triggerItemId: 'anon', logicEventIds: ['doppelganger'] },
+  ],
+
+  skillRules: {
+    projectileSpawnChance: 0.5,
+    projectileLifetimeMs: 2000,
+    projectileWidth: 1,
+    projectileHeight: 1,
+    projectileSpeedMultiplier: 3,
+    doppelgangerSpawnChance: 0.5,
+    doppelgangerLifetimeMs: 5000,
+    doppelgangerSpawnRadius: 3,
+    doppelgangerInitialLifeFraction: 1.0,
+  },
+
+  // ── Equipment Rules ────────────────────────────────────────────────
+  // Governs which item types can be equipped (activated) and enforces
+  // the one-active-per-type constraint.  See EQUIPMENT_RULES_DEFAULTS.
+  equipmentRules: { ...EQUIPMENT_RULES_DEFAULTS },
+};

package/src/api/cyberia-instance-conf/cyberia-instance-conf.model.js

@@ -0,0 +1,228 @@
+import { Schema, model } from 'mongoose';
+import { CYBERIA_INSTANCE_CONF_DEFAULTS as D } from './cyberia-instance-conf.defaults.js';
+
+const ColorEntrySchema = new Schema(
+  {
+    key: { type: String, required: true },
+    r: { type: Number, default: 0 },
+    g: { type: Number, default: 0 },
+    b: { type: Number, default: 0 },
+    a: { type: Number, default: 255 },
+  },
+  { _id: false },
+);
+
+// ObjectLayer inventory slot: itemId + whether it starts active + initial quantity.
+// Used by EntityDefaultSchema.defaultObjectLayers.
+const ObjectLayerSlotSchema = new Schema(
+  {
+    itemId: { type: String, required: true },
+    active: { type: Boolean, default: false },
+    quantity: { type: Number, default: 1 },
+  },
+  { _id: false },
+);
+
+const EntityDefaultSchema = new Schema(
+  {
+    // Entity category string (matches entity_type_str / bot Behavior in game engine)
+    entityType: { type: String, required: true },
+    // Default ObjectLayer item IDs when the entity is alive and carries no assigned items.
+    liveItemIds: { type: [String], default: [] },
+    // Default ObjectLayer item IDs for the dead / ghost / respawning state.
+    // Empty array = use liveItemIds solid fill color.
+    deadItemIds: { type: [String], default: [] },
+    // Palette key for solid-color fallback when no OL items are assigned.
+    colorKey: { type: String, default: '' },
+    // Full default ObjectLayer inventory for this entity type.
+    // Each entry specifies itemId, whether it starts active, and its initial quantity.
+    // The coin slot must always have active:false — coins are non-activable.
+    // When non-empty this supersedes liveItemIds for inventory initialization.
+    defaultObjectLayers: { type: [ObjectLayerSlotSchema], default: [] },
+  },
+  { _id: false },
+);
+
+const SkillConfigEntrySchema = new Schema(
+  {
+    triggerItemId: { type: String, required: true },
+    logicEventIds: { type: [String], default: [] },
+  },
+  { _id: false },
+);
+
+// ── StatusIconEntrySchema ────────────────────────────────────────────────────
+// Maps a u8 status ID to an overhead icon and a border colour used by the
+// interaction bubble / interact overlay on the C/WASM client.
+// See STATUS_ICONS in cyberia-instance-conf.defaults.js.
+const StatusIconBorderColorSchema = new Schema(
+  {
+    r: { type: Number, default: 100 },
+    g: { type: Number, default: 100 },
+    b: { type: Number, default: 100 },
+    a: { type: Number, default: 200 },
+  },
+  { _id: false },
+);
+
+const StatusIconEntrySchema = new Schema(
+  {
+    id: { type: Number, required: true },
+    name: { type: String, default: '' },
+    iconId: { type: String, default: null },
+    bounce: { type: Boolean, default: false },
+    borderColor: { type: StatusIconBorderColorSchema },
+    description: { type: String, default: '' },
+  },
+  { _id: false },
+);
+
+// ── EconomyRulesSchema ───────────────────────────────────────────────────────
+// Mirrors the EconomyRules proto message and the economyRules sub-document in
+// cyberia-instance-conf.defaults.js.  All fields default from those canonical
+// values so a freshly created document is immediately playable.
+// See OFF_CHAIN_ECONOMY.md for the full Fountain & Sink architecture.
+const EconomyRulesSchema = new Schema(
+  {
+    // ── Fountains ───────────────────────────────────────────────────────────
+    botSpawnCoins: { type: Number, default: D.economyRules.botSpawnCoins },
+    playerSpawnCoins: { type: Number, default: D.economyRules.playerSpawnCoins },
+    // ── Kill Transfer ───────────────────────────────────────────────────────
+    coinKillPercentVsBot: { type: Number, default: D.economyRules.coinKillPercentVsBot },
+    coinKillPercentVsPlayer: { type: Number, default: D.economyRules.coinKillPercentVsPlayer },
+    coinKillMinAmount: { type: Number, default: D.economyRules.coinKillMinAmount },
+    // ── Sinks ───────────────────────────────────────────────────────────────
+    respawnCostPercent: { type: Number, default: D.economyRules.respawnCostPercent },
+    portalFee: { type: Number, default: D.economyRules.portalFee },
+    craftingFeePercent: { type: Number, default: D.economyRules.craftingFeePercent },
+  },
+  { _id: false },
+);
+
+// ── EquipmentRulesSchema ─────────────────────────────────────────────────────
+// Governs which ObjectLayer item types can be simultaneously active on a
+// character entity and enforces the one-active-per-type constraint.
+// See EQUIPMENT_RULES_DEFAULTS in cyberia-instance-conf.defaults.js.
+const EquipmentRulesSchema = new Schema(
+  {
+    // Item types that players are allowed to activate (equip).
+    // Types not in this list are non-activable (coins, floors, etc.).
+    activeItemTypes: { type: [String], default: D.equipmentRules.activeItemTypes },
+    // Enforce at most one active item per item type.
+    onePerType: { type: Boolean, default: D.equipmentRules.onePerType },
+    // Require at least one active skin when the player owns any skin.
+    requireSkin: { type: Boolean, default: D.equipmentRules.requireSkin },
+  },
+  { _id: false },
+);
+
+const SkillRulesSchema = new Schema(
+  {
+    projectileSpawnChance: { type: Number, default: D.skillRules.projectileSpawnChance },
+    projectileLifetimeMs: { type: Number, default: D.skillRules.projectileLifetimeMs },
+    projectileWidth: { type: Number, default: D.skillRules.projectileWidth },
+    projectileHeight: { type: Number, default: D.skillRules.projectileHeight },
+    projectileSpeedMultiplier: { type: Number, default: D.skillRules.projectileSpeedMultiplier },
+    doppelgangerSpawnChance: { type: Number, default: D.skillRules.doppelgangerSpawnChance },
+    doppelgangerLifetimeMs: { type: Number, default: D.skillRules.doppelgangerLifetimeMs },
+    doppelgangerSpawnRadius: { type: Number, default: D.skillRules.doppelgangerSpawnRadius },
+    doppelgangerInitialLifeFraction: { type: Number, default: D.skillRules.doppelgangerInitialLifeFraction },
+  },
+  { _id: false },
+);
+
+/**
+ * Game server configuration for a Cyberia instance.
+ * Separated from CyberiaInstance so the GUI never overwrites live server parameters
+ * when editing instance identity / map-graph fields.
+ *
+ * Linked from CyberiaInstance.conf (ObjectId ref).
+ * Looked up by instanceCode for CLI / gRPC use.
+ */
+const CyberiaInstanceConfSchema = new Schema(
+  {
+    // Back-reference to the owning instance (indexed for fast lookup by code).
+    instanceCode: { type: String, required: true, unique: true, trim: true },
+
+    // ── Rendering / camera ──────────────────────────────────────────
+    cellSize: { type: Number, default: D.cellSize },
+    fps: { type: Number, default: D.fps },
+    interpolationMs: { type: Number, default: D.interpolationMs },
+    defaultObjWidth: { type: Number, default: D.defaultObjWidth },
+    defaultObjHeight: { type: Number, default: D.defaultObjHeight },
+    cameraSmoothing: { type: Number, default: D.cameraSmoothing },
+    cameraZoom: { type: Number, default: D.cameraZoom },
+    defaultWidthScreenFactor: { type: Number, default: D.defaultWidthScreenFactor },
+    defaultHeightScreenFactor: { type: Number, default: D.defaultHeightScreenFactor },
+    devUi: { type: Boolean, default: D.devUi },
+    // Empty array by default — colours must be configured per-instance.
+    // toInstanceConfig() fills in CYBERIA_INSTANCE_CONF_DEFAULTS.colors when the array is empty.
+    colors: { type: [ColorEntrySchema], default: [] },
+
+    // ── World / AOI ─────────────────────────────────────────────────
+    aoiRadius: { type: Number, default: D.aoiRadius },
+    portalHoldTimeMs: { type: Number, default: D.portalHoldTimeMs },
+    portalSpawnRadius: { type: Number, default: D.portalSpawnRadius },
+
+    // ── Entity base stats ────────────────────────────────────────────
+    entityBaseSpeed: { type: Number, default: D.entityBaseSpeed },
+    entityBaseMaxLife: { type: Number, default: D.entityBaseMaxLife },
+    entityBaseActionCooldownMs: { type: Number, default: D.entityBaseActionCooldownMs },
+    entityBaseMinActionCooldownMs: { type: Number, default: D.entityBaseMinActionCooldownMs },
+
+    // ── Bot defaults ─────────────────────────────────────────────────
+    botAggroRange: { type: Number, default: D.botAggroRange },
+
+    // ── Player defaults ──────────────────────────────────────────────
+    defaultPlayerWidth: { type: Number, default: D.defaultPlayerWidth },
+    defaultPlayerHeight: { type: Number, default: D.defaultPlayerHeight },
+    playerBaseLifeRegenMin: { type: Number, default: D.playerBaseLifeRegenMin },
+    playerBaseLifeRegenMax: { type: Number, default: D.playerBaseLifeRegenMax },
+    sumStatsLimit: { type: Number, default: D.sumStatsLimit },
+    maxActiveLayers: { type: Number, default: D.maxActiveLayers },
+    initialLifeFraction: { type: Number, default: D.initialLifeFraction },
+
+    // ── Combat / death ───────────────────────────────────────────────
+    respawnDurationMs: { type: Number, default: D.respawnDurationMs },
+    collisionLifeLoss: { type: Number, default: D.collisionLifeLoss },
+
+    // ── Economy ──────────────────────────────────────────────────────
+    // Fountain & Sink parameters. See EconomyRulesSchema and OFF_CHAIN_ECONOMY.md.
+    economyRules: { type: EconomyRulesSchema },
+
+    // ── Regen ────────────────────────────────────────────────────────
+    lifeRegenChance: { type: Number, default: D.lifeRegenChance },
+    maxChance: { type: Number, default: D.maxChance },
+
+    // ── Entity type rendering defaults ───────────────────────────────
+    // Replaces flat fields: userDefaultItemId, botDefaultItemId, ghostItemId,
+    // coinItemId, defaultFloorItemId, weaponDefaultItemId.
+    // Each entry: { entityType, liveItemIds, deadItemIds, colorKey }.
+    entityDefaults: { type: [EntityDefaultSchema], default: D.entityDefaults },
+
+    // ── Entity Status Indicators ────────────────────────────────────
+    // Overhead icon mapping + per-status border colour.
+    // See STATUS_ICONS in cyberia-instance-conf.defaults.js.
+    statusIcons: { type: [StatusIconEntrySchema], default: D.statusIcons },
+
+    // ── Skill system ─────────────────────────────────────────────────
+    // Each entry maps a trigger item to an ordered list of logic handler keys.
+    // Spawning entities (e.g. projectiles) is handled inside the logic handler itself.
+    skillConfig: { type: [SkillConfigEntrySchema], default: [] },
+
+    // Numeric tuning parameters for each skill archetype.
+    skillRules: { type: SkillRulesSchema },
+
+    // ── Equipment rules ──────────────────────────────────────────────
+    // Governs which item types can be simultaneously active and enforces
+    // the one-active-per-type constraint.  See EQUIPMENT_RULES_DEFAULTS.
+    equipmentRules: { type: EquipmentRulesSchema },
+  },
+  { timestamps: true },
+);
+
+const CyberiaInstanceConfModel = model('CyberiaInstanceConf', CyberiaInstanceConfSchema);
+
+const ProviderSchema = CyberiaInstanceConfSchema;
+
+export { CyberiaInstanceConfSchema, CyberiaInstanceConfModel, ProviderSchema };

package/src/api/cyberia-instance-conf/cyberia-instance-conf.router.js

@@ -0,0 +1,27 @@
+import { loggerFactory } from '../../server/logger.js';
+import { CyberiaInstanceConfController } from './cyberia-instance-conf.controller.js';
+import express from 'express';
+
+const logger = loggerFactory(import.meta);
+
+const CyberiaInstanceConfRouter = (options) => {
+  const router = express.Router();
+  const authMiddleware = options.authMiddleware;
+  router.post(`/:id`, async (req, res) => await CyberiaInstanceConfController.post(req, res, options));
+  router.post(`/`, async (req, res) => await CyberiaInstanceConfController.post(req, res, options));
+  router.get(
+    `/:id`,
+    // authMiddleware,
+    async (req, res) => await CyberiaInstanceConfController.get(req, res, options),
+  );
+  router.get(`/`, async (req, res) => await CyberiaInstanceConfController.get(req, res, options));
+  router.put(`/:id`, async (req, res) => await CyberiaInstanceConfController.put(req, res, options));
+  router.put(`/`, async (req, res) => await CyberiaInstanceConfController.put(req, res, options));
+  router.delete(`/:id`, async (req, res) => await CyberiaInstanceConfController.delete(req, res, options));
+  router.delete(`/`, async (req, res) => await CyberiaInstanceConfController.delete(req, res, options));
+  return router;
+};
+
+const ApiRouter = CyberiaInstanceConfRouter;
+
+export { ApiRouter, CyberiaInstanceConfRouter };