cyberia 3.1.3 → 3.2.9

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

@@ -0,0 +1,231 @@
+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: [] },
+    // Resource-only inventory items granted on extraction/depletion.
+    // These are not auto-activated on the entity itself.
+    dropItemIds: { 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, dropItemIds, 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 };

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

@@ -0,0 +1,46 @@
+import { DataBaseProvider } 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 =
+      DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaInstanceConf;
+    return await new CyberiaInstanceConf(req.body).save();
+  };
+  static get = async (req, res, options) => {
+    /** @type {import('./cyberia-instance-conf.model.js').CyberiaInstanceConfModel} */
+    const CyberiaInstanceConf =
+      DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaInstanceConf;
+    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 =
+      DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaInstanceConf;
+    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 =
+      DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaInstanceConf;
+    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,79 @@
+import { loggerFactory } from '../../server/logger.js';
+import { CyberiaMapService } from './cyberia-map.service.js';
+
+const logger = loggerFactory(import.meta);
+
+class CyberiaMapController {
+  static post = async (req, res, options) => {
+    try {
+      const result = await CyberiaMapService.post(req, res, options);
+      return res.status(200).json({
+        status: 'success',
+        data: result,
+      });
+    } catch (error) {
+      logger.error(error, error.stack);
+      return res.status(400).json({
+        status: 'error',
+        message: error.message,
+      });
+    }
+  };
+  static get = async (req, res, options) => {
+    try {
+      const { page, limit } = req.query;
+      const result = await CyberiaMapService.get(
+        {
+          ...req,
+          path: req.path,
+          params: req.params,
+          query: { ...req.query, page: parseInt(page), limit: parseInt(limit) },
+        },
+        res,
+        options,
+      );
+      return res.status(200).json({
+        status: 'success',
+        data: result,
+      });
+    } catch (error) {
+      logger.error(error, error.stack);
+      return res.status(400).json({
+        status: 'error',
+        message: error.message,
+      });
+    }
+  };
+  static put = async (req, res, options) => {
+    try {
+      const result = await CyberiaMapService.put(req, res, options);
+      return res.status(200).json({
+        status: 'success',
+        data: result,
+      });
+    } catch (error) {
+      logger.error(error, error.stack);
+      return res.status(400).json({
+        status: 'error',
+        message: error.message,
+      });
+    }
+  };
+  static delete = async (req, res, options) => {
+    try {
+      const result = await CyberiaMapService.delete(req, res, options);
+      return res.status(200).json({
+        status: 'success',
+        data: result,
+      });
+    } catch (error) {
+      logger.error(error, error.stack);
+      return res.status(400).json({
+        status: 'error',
+        message: error.message,
+      });
+    }
+  };
+}
+
+export { CyberiaMapController };

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

@@ -0,0 +1,30 @@
+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' },
+    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,40 @@
+import { loggerFactory } from '../../server/logger.js';
+import { CyberiaMapController } from './cyberia-map.controller.js';
+import { userGuard, adminGuard } from '../../server/auth.js';
+import express from 'express';
+
+const logger = loggerFactory(import.meta);
+
+const CyberiaMapRouter = (options) => {
+  const router = express.Router();
+  const authMiddleware = options.authMiddleware;
+  router.post(
+    `/:id`,
+    authMiddleware,
+    userGuard,
+    async (req, res) => await CyberiaMapController.post(req, res, options),
+  );
+  router.post(`/`, authMiddleware, userGuard, async (req, res) => await CyberiaMapController.post(req, res, options));
+  router.get(`/search-codes`, async (req, res) => await CyberiaMapController.get(req, res, options));
+  router.get(`/:id`, async (req, res) => await CyberiaMapController.get(req, res, options));
+  router.get(`/`, async (req, res) => await CyberiaMapController.get(req, res, options));
+  router.put(`/:id`, authMiddleware, userGuard, async (req, res) => await CyberiaMapController.put(req, res, options));
+  router.put(`/`, authMiddleware, userGuard, async (req, res) => await CyberiaMapController.put(req, res, options));
+  router.delete(
+    `/:id`,
+    authMiddleware,
+    userGuard,
+    async (req, res) => await CyberiaMapController.delete(req, res, options),
+  );
+  router.delete(
+    `/`,
+    authMiddleware,
+    adminGuard,
+    async (req, res) => await CyberiaMapController.delete(req, res, options),
+  );
+  return router;
+};
+
+const ApiRouter = CyberiaMapRouter;
+
+export { ApiRouter, CyberiaMapRouter };

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

@@ -0,0 +1,74 @@
+import { DataBaseProvider } 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 = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaMap;
+    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 = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaMap;
+    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 = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaMap;
+    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');
+    if (req.body.thumbnail && map.thumbnail && String(req.body.thumbnail) !== String(map.thumbnail)) {
+      const File = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.File;
+      await File.findByIdAndDelete(map.thumbnail);
+    }
+    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 = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaMap;
+    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');
+      if (map.thumbnail) {
+        const File = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.File;
+        await File.findByIdAndDelete(map.thumbnail);
+      }
+      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,74 @@
+import { loggerFactory } from '../../server/logger.js';
+import { CyberiaQuestService } from './cyberia-quest.service.js';
+
+const logger = loggerFactory(import.meta);
+
+class CyberiaQuestController {
+  static post = async (req, res, options) => {
+    try {
+      const result = await CyberiaQuestService.post(req, res, options);
+      return res.status(200).json({
+        status: 'success',
+        data: result,
+      });
+    } catch (error) {
+      logger.error(error, error.stack);
+      return res.status(400).json({
+        status: 'error',
+        message: error.message,
+      });
+    }
+  };
+  static get = async (req, res, options) => {
+    try {
+      const { page, limit } = req.query;
+      const result = await CyberiaQuestService.get(
+        { ...req, query: { ...req.query, page: parseInt(page), limit: parseInt(limit) } },
+        res,
+        options,
+      );
+      return res.status(200).json({
+        status: 'success',
+        data: result,
+      });
+    } catch (error) {
+      logger.error(error, error.stack);
+      return res.status(400).json({
+        status: 'error',
+        message: error.message,
+      });
+    }
+  };
+  static put = async (req, res, options) => {
+    try {
+      const result = await CyberiaQuestService.put(req, res, options);
+      return res.status(200).json({
+        status: 'success',
+        data: result,
+      });
+    } catch (error) {
+      logger.error(error, error.stack);
+      return res.status(400).json({
+        status: 'error',
+        message: error.message,
+      });
+    }
+  };
+  static delete = async (req, res, options) => {
+    try {
+      const result = await CyberiaQuestService.delete(req, res, options);
+      return res.status(200).json({
+        status: 'success',
+        data: result,
+      });
+    } catch (error) {
+      logger.error(error, error.stack);
+      return res.status(400).json({
+        status: 'error',
+        message: error.message,
+      });
+    }
+  };
+}
+
+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-portal/CommonCyberiaPortal.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 };