@underpostnet/cyberia 3.2.80

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

@@ -0,0 +1,200 @@
+import { Schema, model } from 'mongoose';
+import { CYBERIA_INSTANCE_CONF_DEFAULTS as D } from '../cyberia-server-defaults/cyberia-server-defaults.js';
+
+// 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 },
+);
+
+// Per-entity-type simulation defaults. ONLY authoritative item-id wiring
+// lives here — presentation (palette, colour keys) is the client's
+// responsibility and travels through the CyberiaClientHints REST contract.
+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.
+    deadItemIds: { type: [String], default: [] },
+    // Resource-only inventory items granted on extraction/depletion.
+    // These are not auto-activated on the entity itself.
+    dropItemIds: { 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: [] },
+    // Canonical entity behavior (SharedDefaultsCyberia.ENTITY_BEHAVIORS). Empty
+    // lets the runtime derive it (armed → hostile, else passive).
+    behavior: { type: String, default: '' },
+  },
+  { _id: false },
+);
+
+const SkillConfigEntrySchema = new Schema(
+  {
+    triggerItemId: { type: String, required: true },
+    logicEventIds: { type: [String], default: [] },
+  },
+  { _id: false },
+);
+
+// ── StatusIconEntrySchema ────────────────────────────────────────────────────
+// Numeric Entity Status Indicator (ESI) IDs. The Go server stamps one of
+// these u8 IDs on every entity in the AOI binary wire format. Visual
+// resolution (icon stem, border colour, bounce) is the C client's job and
+// arrives through the /api/cyberia-client-hints REST contract — NOT here.
+const StatusIconEntrySchema = new Schema(
+  {
+    id: { type: Number, required: true },
+    name: { type: String, default: '' },
+    description: { type: String, default: '' },
+  },
+  { _id: false },
+);
+
+// ── EconomyRulesSchema ───────────────────────────────────────────────────────
+// Mirrors the EconomyRules proto message and the economyRules sub-document in
+// cyberia-server-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-server-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 },
+
+    // ── Tick model (authoritative simulation cadence) ─────────────────
+    tickRate: { type: Number, default: D.tickRate },
+    snapshotRate: { type: Number, default: D.snapshotRate },
+
+    // ── 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, dropItemIds, colorKey }.
+    entityDefaults: { type: [EntityDefaultSchema], default: D.entityDefaults },
+
+    // ── Entity Status Indicators ────────────────────────────────────
+    // Overhead icon mapping + per-status border colour.
+    // See STATUS_ICONS in cyberia-server-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,17 @@
+import express from 'express';
+import { registerCrudRoutes } from '../../server/middlewares.js';
+import { CyberiaInstanceConfController } from './cyberia-instance-conf.controller.js';
+
+class CyberiaInstanceConfRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    return registerCrudRoutes(express.Router(), CyberiaInstanceConfController, options);
+  }
+}
+
+const ApiRouter = (options) => CyberiaInstanceConfRouter.router(options);
+
+export { ApiRouter, CyberiaInstanceConfRouter };

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

@@ -0,0 +1,46 @@
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
+import { loggerFactory } from '../../server/logger.js';
+import { DataQuery } from '../../server/data-query.js';
+
+const logger = loggerFactory(import.meta);
+
+class CyberiaInstanceConfService {
+  static post = async (req, res, options) => {
+    /** @type {import('./cyberia-instance-conf.model.js').CyberiaInstanceConfModel} */
+    const CyberiaInstanceConf =
+      DataBaseProviderService.getModel("CyberiaInstanceConf", options);
+    return await new CyberiaInstanceConf(req.body).save();
+  };
+  static get = async (req, res, options) => {
+    /** @type {import('./cyberia-instance-conf.model.js').CyberiaInstanceConfModel} */
+    const CyberiaInstanceConf =
+      DataBaseProviderService.getModel("CyberiaInstanceConf", options);
+    if (req.params.id) return await CyberiaInstanceConf.findById(req.params.id);
+
+    // Parse query parameters using DataQuery helper
+    const { query, sort, skip, limit, page } = DataQuery.parse(req.query);
+
+    const [data, total] = await Promise.all([
+      CyberiaInstanceConf.find(query).sort(sort).limit(limit).skip(skip),
+      CyberiaInstanceConf.countDocuments(query),
+    ]);
+
+    const totalPages = Math.ceil(total / limit);
+    return { data, total, page, totalPages };
+  };
+  static put = async (req, res, options) => {
+    /** @type {import('./cyberia-instance-conf.model.js').CyberiaInstanceConfModel} */
+    const CyberiaInstanceConf =
+      DataBaseProviderService.getModel("CyberiaInstanceConf", options);
+    return await CyberiaInstanceConf.findByIdAndUpdate(req.params.id, req.body);
+  };
+  static delete = async (req, res, options) => {
+    /** @type {import('./cyberia-instance-conf.model.js').CyberiaInstanceConfModel} */
+    const CyberiaInstanceConf =
+      DataBaseProviderService.getModel("CyberiaInstanceConf", options);
+    if (req.params.id) return await CyberiaInstanceConf.findByIdAndDelete(req.params.id);
+    else return await CyberiaInstanceConf.deleteMany();
+  };
+}
+
+export { CyberiaInstanceConfService };

package/src/api/cyberia-map/cyberia-map.controller.js

@@ -0,0 +1,6 @@
+import { buildCrudController } from '../../server/middlewares.js';
+import { CyberiaMapService } from './cyberia-map.service.js';
+
+const CyberiaMapController = buildCrudController(CyberiaMapService);
+
+export { CyberiaMapController };

package/src/api/cyberia-map/cyberia-map.model.js

@@ -0,0 +1,33 @@
+import { Schema, model, Types } from 'mongoose';
+import { CyberiaEntitySchema } from '../cyberia-entity/cyberia-entity.model.js';
+
+// https://mongoosejs.com/docs/2.7.x/docs/schematypes.html
+
+const CyberiaMapSchema = new Schema(
+  {
+    code: { type: String, default: '', unique: true },
+    name: { type: String, default: '' },
+    description: { type: String, default: '' },
+    entities: { type: [CyberiaEntitySchema], default: [] },
+    tags: { type: [String], default: [] },
+    creator: { type: Schema.Types.ObjectId, ref: 'User' },
+    status: { type: String, default: 'unlisted' },
+    thumbnail: { type: Schema.Types.ObjectId, ref: 'File' },
+    // Auto-generated Object Layer canvas capture (MapEngine save/clone).
+    // Serves as the node background image in the client's Instance Map.
+    preview: { type: Schema.Types.ObjectId, ref: 'File' },
+    gridX: { type: Number, default: 16 },
+    gridY: { type: Number, default: 16 },
+    cellWidth: { type: Number, default: 32 },
+    cellHeight: { type: Number, default: 32 },
+  },
+  {
+    timestamps: true,
+  },
+);
+
+const CyberiaMapModel = model('CyberiaMap', CyberiaMapSchema);
+
+const ProviderSchema = CyberiaMapSchema;
+
+export { CyberiaMapSchema, CyberiaMapModel, ProviderSchema };

package/src/api/cyberia-map/cyberia-map.router.js

@@ -0,0 +1,19 @@
+import express from 'express';
+import { registerCrudRoutes } from '../../server/middlewares.js';
+import { CyberiaMapController } from './cyberia-map.controller.js';
+
+class CyberiaMapRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+    router.get(`/search-codes`, async (req, res) => await CyberiaMapController.get(req, res, options));
+    return registerCrudRoutes(router, CyberiaMapController, options);
+  }
+}
+
+const ApiRouter = (options) => CyberiaMapRouter.router(options);
+
+export { ApiRouter, CyberiaMapRouter };

package/src/api/cyberia-map/cyberia-map.service.js

@@ -0,0 +1,76 @@
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
+import { loggerFactory } from '../../server/logger.js';
+import { DataQuery } from '../../server/data-query.js';
+
+const logger = loggerFactory(import.meta);
+
+class CyberiaMapService {
+  static post = async (req, res, options) => {
+    /** @type {import('./cyberia-map.model.js').CyberiaMapModel} */
+    const CyberiaMap = DataBaseProviderService.getModel("CyberiaMap", options);
+    if (req.auth && req.auth.user) req.body.creator = req.auth.user._id;
+    return await new CyberiaMap(req.body).save();
+  };
+  static get = async (req, res, options) => {
+    /** @type {import('./cyberia-map.model.js').CyberiaMapModel} */
+    const CyberiaMap = DataBaseProviderService.getModel("CyberiaMap", options);
+    const populateCreator = { path: 'creator', model: 'User', select: '_id username' };
+
+    // GET /search-codes?q=<partial> - Fast partial match search on code
+    if (req.path?.startsWith('/search-codes')) {
+      const q = (req.query.q || '').trim();
+      if (!q) return { codes: [] };
+      const escaped = q.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const results = await CyberiaMap.find({ code: { $regex: escaped, $options: 'i' } }, { code: 1, _id: 0 })
+        .limit(20)
+        .lean();
+      const codes = [...new Set(results.map((r) => r.code).filter(Boolean))];
+      return { codes };
+    }
+
+    if (req.params.id) return await CyberiaMap.findById(req.params.id).populate(populateCreator);
+
+    // Parse query parameters using DataQuery helper
+    const { query, sort, skip, limit, page } = DataQuery.parse(req.query);
+
+    const [data, total] = await Promise.all([
+      CyberiaMap.find(query).sort(sort).limit(limit).skip(skip).populate(populateCreator),
+      CyberiaMap.countDocuments(query),
+    ]);
+
+    const totalPages = Math.ceil(total / limit);
+    return { data, total, page, totalPages };
+  };
+  static put = async (req, res, options) => {
+    /** @type {import('./cyberia-map.model.js').CyberiaMapModel} */
+    const CyberiaMap = DataBaseProviderService.getModel("CyberiaMap", options);
+    const map = await CyberiaMap.findById(req.params.id);
+    if (!map) throw new Error('map not found');
+    if (req.auth.user.role !== 'admin' && String(map.creator) !== String(req.auth.user._id))
+      throw new Error('insufficient permission');
+    const File = DataBaseProviderService.getModel("File", options);
+    if (req.body.thumbnail && map.thumbnail && String(req.body.thumbnail) !== String(map.thumbnail)) {
+      await File.findByIdAndDelete(map.thumbnail);
+    }
+    if (req.body.preview && map.preview && String(req.body.preview) !== String(map.preview)) {
+      await File.findByIdAndDelete(map.preview);
+    }
+    return await CyberiaMap.findByIdAndUpdate(req.params.id, req.body, { returnDocument: 'after' });
+  };
+  static delete = async (req, res, options) => {
+    /** @type {import('./cyberia-map.model.js').CyberiaMapModel} */
+    const CyberiaMap = DataBaseProviderService.getModel("CyberiaMap", options);
+    if (req.params.id) {
+      const map = await CyberiaMap.findById(req.params.id);
+      if (!map) throw new Error('map not found');
+      if (req.auth.user.role !== 'admin' && String(map.creator) !== String(req.auth.user._id))
+        throw new Error('insufficient permission');
+      const File = DataBaseProviderService.getModel("File", options);
+      if (map.thumbnail) await File.findByIdAndDelete(map.thumbnail);
+      if (map.preview) await File.findByIdAndDelete(map.preview);
+      return await CyberiaMap.findByIdAndDelete(req.params.id);
+    } else return await CyberiaMap.deleteMany();
+  };
+}
+
+export { CyberiaMapService };

package/src/api/cyberia-quest/cyberia-quest.controller.js

@@ -0,0 +1,9 @@
+import { buildCrudController, serviceHandler } from '../../server/middlewares.js';
+import { CyberiaQuestService } from './cyberia-quest.service.js';
+
+const CyberiaQuestController = buildCrudController(CyberiaQuestService, {
+  getByCode: serviceHandler(CyberiaQuestService.getByCode, { crossOrigin: true, errorStatus: 404 }),
+  getByCell: serviceHandler(CyberiaQuestService.getByCell, { crossOrigin: true, errorStatus: 404 }),
+});
+
+export { CyberiaQuestController };

package/src/api/cyberia-quest/cyberia-quest.model.js

@@ -0,0 +1,67 @@
+import { Schema, model } from 'mongoose';
+import { QUEST_STEPS_TYPES } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
+
+// https://mongoosejs.com/docs/2.7.x/docs/schematypes.html
+
+const CyberiaQuestSchema = new Schema(
+  {
+    // Spatial origin: the NPC/entity cell that grants this quest.
+    // Matched against map entity initCellX/initCellY during instance init
+    // and assignable from ObjectLayerEngineModal.
+    sourceMapCode: { type: String, trim: true },
+    sourceCellX: { type: Number },
+    sourceCellY: { type: Number },
+
+    // Stable slug, e.g. "fallback-intro-quest"
+    code: { type: String, required: true, trim: true },
+    title: { type: String, required: true, trim: true },
+    description: { type: String, default: '' },
+
+    // ── Chain / tree unlock structure ─────────────────────────────────────
+    // All listed quest codes must be completed before this quest becomes
+    // available (AND logic). Empty array = no prerequisites.
+    prerequisiteCodes: { type: [String], default: [] },
+
+    // Quest codes unlocked when this quest is completed.
+    // Supports both chain (one successor) and tree (multiple successors).
+    // The server re-checks prerequisiteCodes on each target before activating it.
+    unlocksQuestCodes: { type: [String], default: [] },
+
+    // ── Steps ─────────────────────────────────────────────────────────────
+    // Ordered linear sequence. The active step is always the first incomplete one.
+    steps: [
+      {
+        id: { type: String, required: true },
+        description: { type: String, default: '' },
+        objectives: [
+          {
+            // collect — itemId = item that must appear in the player's inventory
+            // talk    — itemId = provideItemId of the CyberiaAction to interact with
+            // kill    — itemId = skin item ID of the target entity
+            type: { type: String, required: true, enum: QUEST_STEPS_TYPES },
+            itemId: { type: String, required: true, trim: true },
+            quantity: { type: Number, default: 1, min: 1 },
+          },
+        ],
+      },
+    ],
+
+    // ── Rewards ───────────────────────────────────────────────────────────
+    rewards: [
+      {
+        itemId: { type: String, required: true, trim: true },
+        quantity: { type: Number, default: 1, min: 1 },
+      },
+    ],
+  },
+  { timestamps: true },
+);
+
+CyberiaQuestSchema.index({ code: 1 }, { unique: true });
+CyberiaQuestSchema.index({ sourceMapCode: 1, sourceCellX: 1, sourceCellY: 1 });
+
+const CyberiaQuestModel = model('CyberiaQuest', CyberiaQuestSchema);
+
+const ProviderSchema = CyberiaQuestSchema;
+
+export { CyberiaQuestSchema, CyberiaQuestModel, ProviderSchema };

package/src/api/cyberia-quest/cyberia-quest.router.js

@@ -0,0 +1,26 @@
+import express from 'express';
+import { registerCrudRoutes } from '../../server/middlewares.js';
+import { CyberiaQuestController } from './cyberia-quest.controller.js';
+
+class CyberiaQuestRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+    // Direct lookup by code — C client fetches quest metadata by code.
+    router.get(`/code/:code`, async (req, res) => await CyberiaQuestController.getByCode(req, res, options));
+    // Quest offers located by binding cell — C client resolves the Quest tab from
+    // here using the interacted entity's cell, decoupled from CyberiaAction.
+    router.get(
+      `/cell/:mapCode/:cellX/:cellY`,
+      async (req, res) => await CyberiaQuestController.getByCell(req, res, options),
+    );
+    return registerCrudRoutes(router, CyberiaQuestController, options);
+  }
+}
+
+const ApiRouter = (options) => CyberiaQuestRouter.router(options);
+
+export { ApiRouter, CyberiaQuestRouter };

package/src/api/cyberia-quest/cyberia-quest.service.js

@@ -0,0 +1,97 @@
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
+import { loggerFactory } from '../../server/logger.js';
+import { DataQuery } from '../../server/data-query.js';
+import { DefaultCyberiaQuests } from '../cyberia-server-defaults/cyberia-server-defaults.js';
+
+const logger = loggerFactory(import.meta);
+
+// A step may not repeat the same (type, itemId) objective combination.
+const validateQuestObjectives = (body) => {
+  for (const [stepIndex, step] of (body?.steps || []).entries()) {
+    const seen = new Set();
+    for (const objective of step?.objectives || []) {
+      const key = `${objective?.type}::${objective?.itemId}`;
+      if (seen.has(key))
+        throw new Error(
+          `Duplicate objective "${objective?.type}" for itemId "${objective?.itemId}" in step ${stepIndex + 1}.`,
+        );
+      seen.add(key);
+    }
+  }
+};
+
+class CyberiaQuestService {
+  static post = async (req, res, options) => {
+    /** @type {import('./cyberia-quest.model.js').CyberiaQuestModel} */
+    const CyberiaQuest = DataBaseProviderService.getModel('CyberiaQuest', options);
+    validateQuestObjectives(req.body);
+    return await new CyberiaQuest(req.body).save();
+  };
+  static get = async (req, res, options) => {
+    /** @type {import('./cyberia-quest.model.js').CyberiaQuestModel} */
+    const CyberiaQuest = DataBaseProviderService.getModel('CyberiaQuest', options);
+    if (req.params.id) return await CyberiaQuest.findById(req.params.id);
+
+    // Parse query parameters using DataQuery helper
+    const { query, sort, skip, limit, page } = DataQuery.parse(req.query);
+
+    const [data, total] = await Promise.all([
+      CyberiaQuest.find(query).sort(sort).limit(limit).skip(skip),
+      CyberiaQuest.countDocuments(query),
+    ]);
+
+    const totalPages = Math.ceil(total / limit);
+    return { data, total, page, totalPages };
+  };
+  static getByCode = async (req, res, options) => {
+    /** @type {import('./cyberia-quest.model.js').CyberiaQuestModel} */
+    const CyberiaQuest = DataBaseProviderService.getModel('CyberiaQuest', options);
+    const { code } = req.params;
+    if (!code) throw new Error('code parameter is required');
+    const data = await CyberiaQuest.findOne({ code }).lean();
+    if (data) return data;
+    // Fallback world delivers quests to the Go server via gRPC from the
+    // canonical defaults without persisting them. Serve those same defaults so
+    // the client can resolve metadata even when Mongo has no seeded quest.
+    const fallback = DefaultCyberiaQuests.find((q) => q.code === code);
+    if (fallback) return fallback;
+    throw new Error(`No quest found for code: ${code}`);
+  };
+  // Quest OFFERS are located by the quest's own (sourceMapCode, sourceCellX,
+  // sourceCellY). The client queries this with the interacted entity's binding
+  // cell — no dependency on CyberiaAction. Full docs are returned so the client
+  // populates its quest metadata cache in a single request.
+  static getByCell = async (req, res, options) => {
+    /** @type {import('./cyberia-quest.model.js').CyberiaQuestModel} */
+    const CyberiaQuest = DataBaseProviderService.getModel('CyberiaQuest', options);
+    const { mapCode } = req.params;
+    const cellX = parseInt(req.params.cellX);
+    const cellY = parseInt(req.params.cellY);
+    if (!mapCode || Number.isNaN(cellX) || Number.isNaN(cellY))
+      throw new Error('mapCode, cellX and cellY parameters are required');
+    const docs = await CyberiaQuest.find({ sourceMapCode: mapCode, sourceCellX: cellX, sourceCellY: cellY }).lean();
+    const seen = new Set(docs.map((d) => d.code));
+    // Fallback-world quests are served from the canonical defaults, not Mongo.
+    for (const q of DefaultCyberiaQuests) {
+      if (q.sourceMapCode === mapCode && q.sourceCellX === cellX && q.sourceCellY === cellY && !seen.has(q.code)) {
+        docs.push(q);
+        seen.add(q.code);
+      }
+    }
+    return docs;
+  };
+  static put = async (req, res, options) => {
+    /** @type {import('./cyberia-quest.model.js').CyberiaQuestModel} */
+    const CyberiaQuest = DataBaseProviderService.getModel('CyberiaQuest', options);
+    validateQuestObjectives(req.body);
+    return await CyberiaQuest.findByIdAndUpdate(req.params.id, req.body);
+  };
+  static delete = async (req, res, options) => {
+    /** @type {import('./cyberia-quest.model.js').CyberiaQuestModel} */
+    const CyberiaQuest = DataBaseProviderService.getModel('CyberiaQuest', options);
+    if (req.params.id) return await CyberiaQuest.findByIdAndDelete(req.params.id);
+    else return await CyberiaQuest.deleteMany();
+  };
+}
+
+export { CyberiaQuestService };

package/src/api/cyberia-quest-progress/cyberia-quest-progress.controller.js

@@ -0,0 +1,6 @@
+import { buildCrudController } from '../../server/middlewares.js';
+import { CyberiaQuestProgressService } from './cyberia-quest-progress.service.js';
+
+const CyberiaQuestProgressController = buildCrudController(CyberiaQuestProgressService);
+
+export { CyberiaQuestProgressController };