@underpostnet/cyberia 3.2.80

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

@@ -0,0 +1,21 @@
+import express from 'express';
+import { registerCrudRoutes } from '../../server/middlewares.js';
+import { CyberiaActionController } from './cyberia-action.controller.js';
+
+class CyberiaActionRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+    // Direct lookup by code — the client fetches an NPC's action metadata
+    // (label, dialogue map) by the action code the Go server sends over AOI.
+    router.get(`/code/:code`, async (req, res) => await CyberiaActionController.getByCode(req, res, options));
+    return registerCrudRoutes(router, CyberiaActionController, options);
+  }
+}
+
+const ApiRouter = (options) => CyberiaActionRouter.router(options);
+
+export { ApiRouter, CyberiaActionRouter };

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

@@ -0,0 +1,58 @@
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
+import { loggerFactory } from '../../server/logger.js';
+import { DataQuery } from '../../server/data-query.js';
+import { DefaultCyberiaActions } from '../cyberia-server-defaults/cyberia-server-defaults.js';
+
+const logger = loggerFactory(import.meta);
+
+class CyberiaActionService {
+  static post = async (req, res, options) => {
+    /** @type {import('./cyberia-action.model.js').CyberiaActionModel} */
+    const CyberiaAction = DataBaseProviderService.getModel('CyberiaAction', options);
+    return await new CyberiaAction(req.body).save();
+  };
+  static get = async (req, res, options) => {
+    /** @type {import('./cyberia-action.model.js').CyberiaActionModel} */
+    const CyberiaAction = DataBaseProviderService.getModel('CyberiaAction', options);
+    if (req.params.id) return await CyberiaAction.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([
+      CyberiaAction.find(query).sort(sort).limit(limit).skip(skip),
+      CyberiaAction.countDocuments(query),
+    ]);
+
+    const totalPages = Math.ceil(total / limit);
+    return { data, total, page, totalPages };
+  };
+  static getByCode = async (req, res, options) => {
+    /** @type {import('./cyberia-action.model.js').CyberiaActionModel} */
+    const CyberiaAction = DataBaseProviderService.getModel('CyberiaAction', options);
+    const { code } = req.params;
+    if (!code) throw new Error('code parameter is required');
+    const data = await CyberiaAction.findOne({ code }).lean();
+    if (data) return data;
+    // Fallback world delivers actions to the Go server from the canonical
+    // defaults without persisting them; serve those so the client can fetch the
+    // action's label + dialogue map by code. Quest OFFERS are NOT resolved here —
+    // the client locates offered quests via the cyberia-quest API by cell.
+    const fallback = DefaultCyberiaActions.find((a) => a.code === code);
+    if (fallback) return fallback;
+    throw new Error(`No action found for code: ${code}`);
+  };
+  static put = async (req, res, options) => {
+    /** @type {import('./cyberia-action.model.js').CyberiaActionModel} */
+    const CyberiaAction = DataBaseProviderService.getModel('CyberiaAction', options);
+    return await CyberiaAction.findByIdAndUpdate(req.params.id, req.body);
+  };
+  static delete = async (req, res, options) => {
+    /** @type {import('./cyberia-action.model.js').CyberiaActionModel} */
+    const CyberiaAction = DataBaseProviderService.getModel('CyberiaAction', options);
+    if (req.params.id) return await CyberiaAction.findByIdAndDelete(req.params.id);
+    else return await CyberiaAction.deleteMany();
+  };
+}
+
+export { CyberiaActionService };

package/src/api/cyberia-client-hints/cyberia-client-hints.controller.js

@@ -0,0 +1,27 @@
+import { controllerHandler, sendSuccess } from '../../server/middlewares.js';
+import { CYBERIA_CLIENT_HINTS_DEFAULTS } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
+import { resolveClientHints } from './cyberia-client-hints.service.js';
+
+class CyberiaClientHintsController {
+  static getByCode = controllerHandler(
+    async (req, res, options) => {
+      const { data, source } = await resolveClientHints(req.params.code, {
+        host: options.host || 'default',
+        path: options.path || '/',
+      });
+      // Surface the resolution source as a non-authoritative header so
+      // operators can see whether the runtime fetched from the new
+      // collection, the compatibility read on instance-conf, the cache, or defaults.
+      res.setHeader('X-Cyberia-Hints-Source', source);
+      return sendSuccess(res, data);
+    },
+    { errorStatus: 500 },
+  );
+
+  static getDefaults = controllerHandler(async (req, res, options) => {
+    res.setHeader('X-Cyberia-Hints-Source', 'defaults');
+    return sendSuccess(res, CYBERIA_CLIENT_HINTS_DEFAULTS);
+  });
+}
+
+export { CyberiaClientHintsController };

package/src/api/cyberia-client-hints/cyberia-client-hints.model.js

@@ -0,0 +1,100 @@
+/**
+ * Mongoose model for `CyberiaClientHints`.
+ *
+ * Dedicated collection for per-instance presentation overrides.
+ *
+ * Ownership:
+ *   - Read by:  cyberia-client (via /api/cyberia-client-hints/:code), CMS UIs.
+ *   - Written by: CMS / editor flows. The Cyberia simulation server
+ *                 never reads or writes this collection.
+ *   - Cacheable: yes — the service layer keeps an in-memory TTL cache.
+ *
+ * Schema scope: purely visual fields. Anything that influences simulation
+ * belongs in `CyberiaInstanceConf`.
+ *
+ * @module src/api/cyberia-client-hints/cyberia-client-hints.model.js
+ */
+
+import { Schema, model } from 'mongoose';
+
+const ColorRgbaSchema = new Schema(
+  {
+    r: { type: Number, default: 0 },
+    g: { type: Number, default: 0 },
+    b: { type: Number, default: 0 },
+    a: { type: Number, default: 255 },
+  },
+  { _id: false },
+);
+
+const PaletteEntrySchema = 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 },
+);
+
+const StatusIconHintSchema = new Schema(
+  {
+    id: { type: Number, required: true },
+    iconId: { type: String, default: '' },
+    bounce: { type: Boolean, default: false },
+    borderColor: { type: ColorRgbaSchema, default: () => ({ r: 100, g: 100, b: 100, a: 200 }) },
+  },
+  { _id: false },
+);
+
+const EntityColorKeySchema = new Schema(
+  {
+    entityType: { type: String, required: true },
+    colorKey: { type: String, required: true },
+  },
+  { _id: false },
+);
+
+const CyberiaClientHintsSchema = new Schema(
+  {
+    // Instance code this hint set is scoped to. Matches CyberiaInstance.code
+    // and CyberiaInstanceConf.instanceCode. Indexed and unique to make the
+    // service-layer cache a 1-to-1 keyed lookup.
+    code: { type: String, required: true, unique: true, index: true },
+
+    // Optional palette overrides. Keys not present here fall back to the
+    // client's compile-time defaults.
+    palette: { type: [PaletteEntrySchema], default: [] },
+
+    // Optional per-entity-type color-key overrides.
+    entityColorKeys: { type: [EntityColorKeySchema], default: [] },
+
+    // Optional status-icon visual overrides (id → iconId + borderColor).
+    statusIcons: { type: [StatusIconHintSchema], default: [] },
+
+    // Camera, viewport, and cell-sizing tunings — null/undefined means
+    // "use the SharedDefaultsCyberia.RENDER_DEFAULTS value".
+    cellSize: { type: Number, default: null },
+    defaultObjWidth: { type: Number, default: null },
+    defaultObjHeight: { type: Number, default: null },
+    cameraSmoothing: { type: Number, default: null },
+    cameraZoom: { type: Number, default: null },
+    defaultWidthScreenFactor: { type: Number, default: null },
+    defaultHeightScreenFactor: { type: Number, default: null },
+    interpolationMs: { type: Number, default: null },
+    devUi: { type: Boolean, default: null },
+
+    // Main UI font: TTF file name under engine assets/fonts/ (null = built-in
+    // raylib font) and a uniform text-size multiplier.
+    fontFamily: { type: String, default: null },
+    fontFactorSize: { type: Number, default: null },
+  },
+  { timestamps: true },
+);
+
+const CyberiaClientHintsModel = model('CyberiaClientHints', CyberiaClientHintsSchema);
+
+const ProviderSchema = CyberiaClientHintsSchema;
+
+export { CyberiaClientHintsSchema, CyberiaClientHintsModel, ProviderSchema };

package/src/api/cyberia-client-hints/cyberia-client-hints.router.js

@@ -0,0 +1,70 @@
+/**
+ * @module src/api/cyberia-client-hints
+ *
+ * Client presentation hints — read-only REST endpoint.
+ *
+ * Purpose
+ * -------
+ * The cyberia-server (Go authoritative simulation) and the WS init payload
+ * carry *only* simulation contracts. Client-render policy (palette, camera
+ * defaults, status-icon visuals, interpolation window, dev-overlay flag)
+ * lives off the simulation path entirely.
+ *
+ * This endpoint exposes optional per-instance overrides of those values.
+ * The client is required to function with no calls to this endpoint at
+ * all (it ships built-in defaults that match the canonical engine
+ * defaults 1-to-1 — see cyberia-client/src/domain/presentation_defaults.h).
+ *
+ * Endpoint
+ * --------
+ *   GET /api/cyberia-client-hints/:instanceCode
+ *     -> 200 { palette, entityColorKeys, statusIcons, cameraSmoothing,
+ *              cameraZoom, defaultWidthScreenFactor,
+ *              defaultHeightScreenFactor, interpolationMs, devUi }
+ *     -> 404 if no instance with that code exists in the database — the
+ *            client falls back to its built-in defaults on 404 (this is
+ *            the normal path for stateless servers / fresh deployments).
+ *
+ *   GET /api/cyberia-client-hints/
+ *     -> 200 canonical defaults — same shape as above, no DB read.
+ *
+ * What it intentionally does NOT do
+ * ---------------------------------
+ *   - It does not touch gameplay state (no entity, map, economy, skill,
+ *     equipment, or stat fields).
+ *   - It is not consumed by cyberia-server; the Go process never calls
+ *     this endpoint.
+ *   - It is not authenticated. Presentation hints are not secret.
+ */
+
+import express from 'express';
+import { crossOriginMiddleware } from '../../server/middlewares.js';
+import { CyberiaClientHintsController } from './cyberia-client-hints.controller.js';
+
+class CyberiaClientHintsRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+    router.use(crossOriginMiddleware);
+
+    // GET /:code -> resolved hints.
+    // Resolution order is documented in cyberia-client-hints.service.js:
+    //   1. In-memory TTL cache.
+    //   2. CyberiaClientHints collection (preferred).
+    //   3. Legacy presentation fields on CyberiaInstanceConf (back-compat).
+    //   4. Canonical client defaults (never cached so a later DB insert wins).
+    router.get('/:code', async (req, res) => await CyberiaClientHintsController.getByCode(req, res, options));
+
+    // GET / -> canonical defaults. No DB read. Documentation/diagnostic.
+    router.get('/', async (req, res) => await CyberiaClientHintsController.getDefaults(req, res, options));
+
+    return router;
+  }
+}
+
+const ApiRouter = (options) => CyberiaClientHintsRouter.router(options);
+
+export { ApiRouter, CyberiaClientHintsRouter };

package/src/api/cyberia-client-hints/cyberia-client-hints.service.js

@@ -0,0 +1,152 @@
+/**
+ * @module src/api/cyberia-client-hints/cyberia-client-hints.service.js
+ *
+ * Read-only service layer for client presentation hints.
+ *
+ * Resolution order (highest priority first):
+ *   1. CyberiaClientHints collection — the dedicated presentation-overrides
+ *      collection. Always preferred when present.
+ *   2. Compatibility read on CyberiaInstanceConf with the same `code` —
+ *      covers instances seeded before CyberiaClientHints existed.
+ *   3. Canonical compile-time defaults from
+ *      SharedDefaultsCyberia.js. The C client bakes the
+ *      same defaults at compile time, so this branch returns exactly the
+ *      values the client already has.
+ *
+ * Caching: in-memory TTL cache keyed by instance code. Read-only on the
+ * hot path; cache writes happen on cache miss + DB hit. CMS writes that
+ * mutate the underlying collection should call `clientHintsInvalidate(code)`.
+ *
+ * Output is a plain JSON-friendly object whose shape matches the C
+ * client's compile-time layout.
+ */
+
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
+import { loggerFactory } from '../../server/logger.js';
+import { resolveHostKeyContext } from '../../server/conf.js';
+import {
+  buildClientHints,
+  CYBERIA_CLIENT_HINTS_DEFAULTS,
+} from '../../client/components/cyberia/SharedDefaultsCyberia.js';
+
+const logger = loggerFactory(import.meta);
+
+// TTL chosen long enough that bursty client fetches are absorbed, short
+// enough that an editor change shows up within ~30s without manual flush.
+const CACHE_TTL_MS = 30_000;
+
+// One per instance code. value: { data, expiresAt }
+const cache = new Map();
+
+function now() {
+  return Date.now();
+}
+
+function cacheGet(code) {
+  const entry = cache.get(code);
+  if (!entry) return null;
+  if (entry.expiresAt < now()) {
+    cache.delete(code);
+    return null;
+  }
+  return entry.data;
+}
+
+function cacheSet(code, data) {
+  cache.set(code, { data, expiresAt: now() + CACHE_TTL_MS });
+}
+
+/** Invalidate a cache entry. CMS write paths should call this after
+ *  mutating either CyberiaClientHints or CyberiaInstanceConf for
+ *  the given code. */
+export function clientHintsInvalidate(code) {
+  if (code) {
+    cache.delete(code);
+  } else {
+    cache.clear();
+  }
+}
+
+/**
+ * Resolve the merged client-hints document for an instance code.
+ *
+ * @param {string} code
+ * @param {Object} options  Engine routing context.
+ * @param {string} [options.host='default'] DataBaseProviderService host key.
+ * @param {string} [options.path='/']       DataBaseProviderService path key.
+ * @returns {Promise<{data: object, source: 'cache'|'presentation-hints'|'instance-conf'|'defaults'}>}
+ */
+export async function resolveClientHints(code, options = {}) {
+  if (code) {
+    const cached = cacheGet(code);
+    if (cached) {
+      return { data: cached, source: 'cache' };
+    }
+  }
+
+  const host = options.host || 'default';
+  const path = options.path || '/';
+  const context = { host, path };
+  const id = resolveHostKeyContext(context);
+
+  let HintsModel = null;
+  let ConfModel = null;
+  try {
+    HintsModel = DataBaseProviderService.getModel('CyberiaClientHints', context);
+  } catch {
+    // model may not be mounted on this context
+  }
+  try {
+    ConfModel = DataBaseProviderService.getModel('CyberiaInstanceConf', context);
+  } catch {
+    // model may not be mounted on this context
+  }
+
+  if (!HintsModel && !ConfModel) {
+    logger.warn('client-hints: mongoose models not available for', id, '— returning defaults');
+    return { data: CYBERIA_CLIENT_HINTS_DEFAULTS, source: 'defaults' };
+  }
+
+  // 1. Preferred — CyberiaClientHints collection (src/api/cyberia-client-hints/cyberia-client-hints.model.js).
+  if (HintsModel && code) {
+    const hint = await HintsModel.findOne({ code }).lean().catch(() => null);
+    if (hint) {
+      const merged = buildClientHints(hint);
+      cacheSet(code, merged);
+      return { data: merged, source: 'presentation-hints' };
+    }
+  }
+
+  // 2. Compatibility read — for instances seeded before CyberiaClientHints
+  //    existed, look up the same code in CyberiaInstanceConf and read its
+  //    presentation-shaped fields directly.
+  if (ConfModel && code) {
+    const fromConf =
+      (await ConfModel.findOne({ code }).lean().catch(() => null)) ||
+      (await ConfModel.findById(code).lean().catch(() => null));
+    if (fromConf) {
+      const merged = buildClientHints(fromConf);
+      cacheSet(code, merged);
+      return { data: merged, source: 'instance-conf' };
+    }
+  }
+
+  // 3. Any available CyberiaClientHints document — used when the requested
+  //    code has no record yet but another instance (e.g. the one the Go
+  //    server is currently running) does.  This avoids pure built-in
+  //    defaults in fresh environments where only a different code is seeded.
+  if (HintsModel) {
+    const anyHint = await HintsModel.findOne({}).lean().catch(() => null);
+    if (anyHint) {
+      const merged = buildClientHints(anyHint);
+      // Cache under the requested code so subsequent requests are fast,
+      // but with a shorter TTL (5 s) so a proper seed wins quickly.
+      if (code) cache.set(code, { data: merged, expiresAt: now() + 5_000 });
+      return { data: merged, source: 'presentation-hints-fallback' };
+    }
+  }
+
+  // 4. Canonical defaults. Not cached — we do not poison the cache with
+  //    a default that could mask a later DB insert.
+  return { data: CYBERIA_CLIENT_HINTS_DEFAULTS, source: 'defaults' };
+}

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

@@ -0,0 +1,8 @@
+import { buildCrudController, serviceHandler } from '../../server/middlewares.js';
+import { CyberiaDialogueService } from './cyberia-dialogue.service.js';
+
+const CyberiaDialogueController = buildCrudController(CyberiaDialogueService, {
+  getByCode: serviceHandler(CyberiaDialogueService.getByCode, { crossOrigin: true, errorStatus: 404 }),
+});
+
+export { CyberiaDialogueController };

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

@@ -0,0 +1,36 @@
+import { Schema, model, Types } from 'mongoose';
+
+// https://mongoosejs.com/docs/2.7.x/docs/schematypes.html
+
+/**
+ * CyberiaDialogue — each document is one dialogue line that belongs to a
+ * named dialogue group (`code`).  One code groups many ordered lines.
+ *
+ * Schema fields:
+ *   code    – primary grouping key, e.g. "default-lain" or "wason-intro".
+ *             The C client fetches all lines for a given code in one request.
+ *   order   – zero-based display sequence within the code group.
+ *   speaker – display name shown above the dialogue line.
+ *   text    – the dialogue line itself.
+ *   mood    – optional emotion hint (neutral / angry / sad / happy / …).
+ */
+const CyberiaDialogueSchema = new Schema(
+  {
+    code: { type: String, required: true, index: true },
+    order: { type: Number, default: 0 },
+    speaker: { type: String, default: '' },
+    text: { type: String, required: true },
+    mood: { type: String, default: 'neutral' },
+  },
+  {
+    timestamps: true,
+  },
+);
+
+CyberiaDialogueSchema.index({ code: 1, order: 1 });
+
+const CyberiaDialogueModel = model('CyberiaDialogue', CyberiaDialogueSchema);
+
+const ProviderSchema = CyberiaDialogueSchema;
+
+export { CyberiaDialogueSchema, CyberiaDialogueModel, ProviderSchema };

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

@@ -0,0 +1,20 @@
+import express from 'express';
+import { registerCrudRoutes } from '../../server/middlewares.js';
+import { CyberiaDialogueController } from './cyberia-dialogue.controller.js';
+
+class CyberiaDialogueRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+    // Direct lookup by code — C client fetches dialogue by code (e.g. "default-lain")
+    router.get(`/code/:code`, async (req, res) => await CyberiaDialogueController.getByCode(req, res, options));
+    return registerCrudRoutes(router, CyberiaDialogueController, options);
+  }
+}
+
+const ApiRouter = (options) => CyberiaDialogueRouter.router(options);
+
+export { ApiRouter, CyberiaDialogueRouter };

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

@@ -0,0 +1,57 @@
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
+import { loggerFactory } from '../../server/logger.js';
+import { DataQuery } from '../../server/data-query.js';
+import { DefaultCyberiaDialogues } from '../cyberia-server-defaults/cyberia-server-defaults.js';
+
+const logger = loggerFactory(import.meta);
+
+class CyberiaDialogueService {
+  static post = async (req, res, options) => {
+    /** @type {import('./cyberia-dialogue.model.js').CyberiaDialogueModel} */
+    const CyberiaDialogue = DataBaseProviderService.getModel("CyberiaDialogue", options);
+    return await new CyberiaDialogue(req.body).save();
+  };
+  static get = async (req, res, options) => {
+    /** @type {import('./cyberia-dialogue.model.js').CyberiaDialogueModel} */
+    const CyberiaDialogue = DataBaseProviderService.getModel("CyberiaDialogue", options);
+    if (req.params.id) return await CyberiaDialogue.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([
+      CyberiaDialogue.find(query).sort(sort).limit(limit).skip(skip),
+      CyberiaDialogue.countDocuments(query),
+    ]);
+
+    const totalPages = Math.ceil(total / limit);
+    return { data, total, page, totalPages };
+  };
+  static put = async (req, res, options) => {
+    /** @type {import('./cyberia-dialogue.model.js').CyberiaDialogueModel} */
+    const CyberiaDialogue = DataBaseProviderService.getModel("CyberiaDialogue", options);
+    return await CyberiaDialogue.findByIdAndUpdate(req.params.id, req.body);
+  };
+  static delete = async (req, res, options) => {
+    /** @type {import('./cyberia-dialogue.model.js').CyberiaDialogueModel} */
+    const CyberiaDialogue = DataBaseProviderService.getModel("CyberiaDialogue", options);
+    if (req.params.id) return await CyberiaDialogue.findByIdAndDelete(req.params.id);
+    else return await CyberiaDialogue.deleteMany();
+  };
+  static getByCode = async (req, res, options) => {
+    /** @type {import('./cyberia-dialogue.model.js').CyberiaDialogueModel} */
+    const CyberiaDialogue = DataBaseProviderService.getModel("CyberiaDialogue", options);
+    const { code } = req.params;
+    if (!code) throw new Error('code parameter is required');
+    const data = await CyberiaDialogue.find({ code }).sort({ order: 1 }).lean();
+    if (data.length) return data;
+    // Fallback world greetings/quest dialogue come from the canonical defaults
+    // without persisting them; serve those so action NPCs always have lines
+    // (and thus the dlg_complete grant handshake fires).
+    const fallback = DefaultCyberiaDialogues.filter((d) => d.code === code).sort((a, b) => a.order - b.order);
+    if (fallback.length) return fallback;
+    throw new Error(`No dialogue found for code: ${code}`);
+  };
+}
+
+export { CyberiaDialogueService };

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

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

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

@@ -0,0 +1,25 @@
+import { Schema, model, Types } from 'mongoose';
+
+// https://mongoosejs.com/docs/2.7.x/docs/schematypes.html
+
+const CyberiaEntitySchema = new Schema({
+  entityType: { type: String, default: 'floor' },
+  initCellX: { type: Number, default: 0 },
+  initCellY: { type: Number, default: 0 },
+  dimX: { type: Number, default: 1 },
+  dimY: { type: Number, default: 1 },
+  color: { type: String, default: 'rgba(255, 0, 0, 1)' },
+  objectLayerItemIds: { type: [String], default: [] },
+  portalSubtype: { type: String, default: '' },
+  // Bot-specific fields (ignored for non-bot entities)
+  spawnRadius: { type: Number, default: 0 },
+  aggroRange: { type: Number, default: 0 },
+  maxLife: { type: Number, default: 0 },
+  lifeRegen: { type: Number, default: 0 },
+});
+
+const CyberiaEntityModel = model('CyberiaEntity', CyberiaEntitySchema);
+
+const ProviderSchema = CyberiaEntitySchema;
+
+export { CyberiaEntitySchema, CyberiaEntityModel, ProviderSchema };

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

@@ -0,0 +1,17 @@
+import express from 'express';
+import { registerCrudRoutes } from '../../server/middlewares.js';
+import { CyberiaEntityController } from './cyberia-entity.controller.js';
+
+class CyberiaEntityRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    return registerCrudRoutes(express.Router(), CyberiaEntityController, options);
+  }
+}
+
+const ApiRouter = (options) => CyberiaEntityRouter.router(options);
+
+export { ApiRouter, CyberiaEntityRouter };

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

@@ -0,0 +1,42 @@
+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 CyberiaEntityService {
+  static post = async (req, res, options) => {
+    /** @type {import('./cyberia-entity.model.js').CyberiaEntityModel} */
+    const CyberiaEntity = DataBaseProviderService.getModel("CyberiaEntity", options);
+    return await new CyberiaEntity(req.body).save();
+  };
+  static get = async (req, res, options) => {
+    /** @type {import('./cyberia-entity.model.js').CyberiaEntityModel} */
+    const CyberiaEntity = DataBaseProviderService.getModel("CyberiaEntity", options);
+    if (req.params.id) return await CyberiaEntity.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([
+      CyberiaEntity.find(query).sort(sort).limit(limit).skip(skip),
+      CyberiaEntity.countDocuments(query),
+    ]);
+
+    const totalPages = Math.ceil(total / limit);
+    return { data, total, page, totalPages };
+  };
+  static put = async (req, res, options) => {
+    /** @type {import('./cyberia-entity.model.js').CyberiaEntityModel} */
+    const CyberiaEntity = DataBaseProviderService.getModel("CyberiaEntity", options);
+    return await CyberiaEntity.findByIdAndUpdate(req.params.id, req.body);
+  };
+  static delete = async (req, res, options) => {
+    /** @type {import('./cyberia-entity.model.js').CyberiaEntityModel} */
+    const CyberiaEntity = DataBaseProviderService.getModel("CyberiaEntity", options);
+    if (req.params.id) return await CyberiaEntity.findByIdAndDelete(req.params.id);
+    else return await CyberiaEntity.deleteMany();
+  };
+}
+
+export { CyberiaEntityService };

package/src/api/cyberia-entity-type-default/cyberia-entity-type-default.controller.js

@@ -0,0 +1,6 @@
+import { buildCrudController } from '../../server/middlewares.js';
+import { CyberiaEntityTypeDefaultService } from './cyberia-entity-type-default.service.js';
+
+const CyberiaEntityTypeDefaultController = buildCrudController(CyberiaEntityTypeDefaultService);
+
+export { CyberiaEntityTypeDefaultController };