cyberia 3.2.5 → 3.2.12

package/src/api/cyberia-instance/cyberia-fallback-world.js

@@ -18,214 +18,80 @@
  * @module src/api/cyberia-instance/cyberia-fallback-world
  */
 
+import { connectPortals } from './cyberia-portal-connector.js';
+
 import {
-  connectPortals,
   generateObstacles,
   generateForeground,
-  colorToRgba,
-  findColor,
-  randInt,
+  generateResources,
+  generateFloorEntities,
+  generatePortalEntity,
+  generatePortalEntities,
+  generateBots,
   OccupancyGrid,
-  BOT_RANGE,
-  BOT_WEAPON_CHANCE,
-  PORTAL_DIM_RANGE,
-  PORTAL_COUNT_RANGE,
-  PORTAL_MODE_LIST,
-  PORTAL_MODE_COLOR_KEY,
-  EXTRA_PORTAL_MODES,
-  PORTAL_MODES,
-} from './cyberia-portal-connector.js';
+} from './cyberia-world-generator.js';
 
 import {
   CYBERIA_INSTANCE_CONF_DEFAULTS,
   ENTITY_TYPE_DEFAULTS,
-} from '../cyberia-instance-conf/cyberia-instance-conf.defaults.js';
-
-import { DefaultCyberiaItems } from '../../client/components/cyberia-portal/CommonCyberiaPortal.js';
+  RESOURCE_ENTITY_TYPE_DEFAULTS,
+  DefaultCyberiaItems,
+} from '../cyberia-server-defaults/cyberia-server-defaults.js';
+import {
+  CYBERIA_CLIENT_HINTS_DEFAULTS,
+  PALETTE,
+} from '../../client/components/cyberia/SharedDefaultsCyberia.js';
 
 // ── Defaults ─────────────────────────────────────────────────────────────────
 
 const DEFAULT_MAP_COUNT = 4;
 const DEFAULT_GRID_SIZE = 64;
-const DEFAULT_FLOOR_TILE_DIM = 4;
-const DEFAULT_BOT_DIM_RANGE = [2, 3];
-
-/** NPC skin pool — all items with type 'skin' from DefaultCyberiaItems. */
-const BOT_SKIN_POOL = DefaultCyberiaItems.filter((e) => e.item.type === 'skin').map((e) => e.item.id);
-
-// ── Floor generator ──────────────────────────────────────────────────────────
 
-/**
- * Generate floor tiles that cover the entire map grid.
- * Floor is NOT random — it tiles deterministically so every cell is covered.
- *
- * @param {{ gridX: number, gridY: number }} mapDims
- * @param {Array<{ key: string, r: number, g: number, b: number, a: number }>} colors
- * @param {object} [opts]
- * @param {number} [opts.tileDim=4]  Floor tile size in cells.
- * @returns {object[]}
- */
-function generateFloorEntities(mapDims, colors, opts = {}) {
-  const { tileDim = DEFAULT_FLOOR_TILE_DIM } = opts;
-  const floorDefault = ENTITY_TYPE_DEFAULTS.find((d) => d.entityType === 'floor');
-  const floorItemIds = floorDefault?.liveItemIds?.length ? [...floorDefault.liveItemIds] : [];
-  const floorColor = findColor(colors, 'FLOOR');
-  const rgba = floorColor ? colorToRgba(floorColor) : '';
-
-  const entities = [];
-  for (let y = 0; y < mapDims.gridY; y += tileDim) {
-    for (let x = 0; x < mapDims.gridX; x += tileDim) {
-      entities.push({
-        entityType: 'floor',
-        initCellX: x,
-        initCellY: y,
-        dimX: Math.min(tileDim, mapDims.gridX - x),
-        dimY: Math.min(tileDim, mapDims.gridY - y),
-        color: rgba,
-        objectLayerItemIds: floorItemIds,
-      });
-    }
+// ── Asset-id integrity ──────────────────────────────────────────────────────
+//
+// Every item id that the fallback world can place on a map must also be
+// present in DefaultCyberiaItems, otherwise the `import-default-items` seed
+// will not create an ObjectLayer for it and the runtime client will fall
+// back to a solid-colour rectangle instead of the intended sprite.
+//
+// auditFallbackItemIds() returns the set of unknown ids encountered in the
+// canonical defaults so callers (CLI, test harness, gRPC fallback path)
+// can surface drift immediately. Returns an empty array when in sync.
+
+const KNOWN_DEFAULT_ITEM_IDS = new Set(DefaultCyberiaItems.map((e) => e.item.id));
+
+function collectReferencedItemIds() {
+  const ids = new Set();
+  const push = (id) => { if (typeof id === 'string' && id.length > 0) ids.add(id); };
+
+  for (const e of ENTITY_TYPE_DEFAULTS) {
+    (e.liveItemIds || []).forEach(push);
+    (e.deadItemIds || []).forEach(push);
+    (e.dropItemIds || []).forEach(push);
+    (e.defaultObjectLayers || []).forEach((ol) => push(ol.itemId));
   }
-  return entities;
-}
-
-// ── Portal entity generator ──────────────────────────────────────────────────
-
-/**
- * Generate a portal entity at a random walkable position with random dimensions.
- *
- * @param {{ gridX: number, gridY: number }} mapDims
- * @param {Array<{ key: string, r: number, g: number, b: number, a: number }>} colors
- * @param {OccupancyGrid} [grid]  If provided, places portal only on walkable cells and marks them blocked.
- * @param {string} [portalSubtype]  One of PORTAL_MODE_LIST values. Determines the portal colour.
- * @returns {object|null}  Portal entity or null if no valid position found.
- */
-function generatePortalEntity(mapDims, colors, grid, portalSubtype) {
-  // Resolve colour from subtype-specific palette key, falling back to generic PORTAL
-  const colorKey = portalSubtype ? PORTAL_MODE_COLOR_KEY[portalSubtype] : 'PORTAL';
-  const portalColor = findColor(colors, colorKey) || findColor(colors, 'PORTAL');
-  const rgba = portalColor ? colorToRgba(portalColor) : 'rgba(0, 200, 200, 1)';
-  const dimX = randInt(PORTAL_DIM_RANGE[0], PORTAL_DIM_RANGE[1]);
-  const dimY = randInt(PORTAL_DIM_RANGE[0], PORTAL_DIM_RANGE[1]);
-
-  if (grid) {
-    const pos = grid.findPosition(dimX, dimY);
-    if (!pos) return null;
-    grid.block(pos.x, pos.y, dimX, dimY);
-    return {
-      entityType: 'portal',
-      portalSubtype: portalSubtype || 'inter-portal',
-      initCellX: pos.x,
-      initCellY: pos.y,
-      dimX,
-      dimY,
-      color: rgba,
-      objectLayerItemIds: [],
-    };
+  for (const r of RESOURCE_ENTITY_TYPE_DEFAULTS) {
+    (r.liveItemIds || []).forEach(push);
+    (r.deadItemIds || []).forEach(push);
+    (r.dropItemIds || []).forEach(push);
   }
-
-  const maxX = Math.max(0, mapDims.gridX - dimX);
-  const maxY = Math.max(0, mapDims.gridY - dimY);
-  return {
-    entityType: 'portal',
-    portalSubtype: portalSubtype || 'inter-portal',
-    initCellX: randInt(0, maxX),
-    initCellY: randInt(0, maxY),
-    dimX,
-    dimY,
-    color: rgba,
-    objectLayerItemIds: [],
-  };
+  return ids;
 }
 
 /**
- * Generate a random number of portal entities for a map, each with a
- * randomly assigned portal subtype (and corresponding colour).
+ * Audit every item id the fallback world can place against the canonical
+ * DefaultCyberiaItems registry.  Returns an array of missing ids; an empty
+ * array means the registry is in sync.
  *
- * @param {{ gridX: number, gridY: number }} mapDims
- * @param {Array<{ key: string, r: number, g: number, b: number, a: number }>} colors
- * @param {object} [opts]
- * @param {number} [opts.count]  Override count (ignores range).
- * @param {OccupancyGrid} [opts.grid]  If provided, places portals only on walkable cells.
- * @returns {object[]}
- */
-function generatePortalEntities(mapDims, colors, opts = {}) {
-  const count = opts.count ?? randInt(PORTAL_COUNT_RANGE[0], PORTAL_COUNT_RANGE[1]);
-  const entities = [];
-  for (let i = 0; i < count; i++) {
-    // First portal is always inter-portal (reserved for the ring topology);
-    // extra portals get a random non-ring subtype.
-    const subtype =
-      i === 0 ? PORTAL_MODES.INTER_PORTAL : EXTRA_PORTAL_MODES[Math.floor(Math.random() * EXTRA_PORTAL_MODES.length)];
-    const portal = generatePortalEntity(mapDims, colors, opts.grid, subtype);
-    if (portal) entities.push(portal);
-  }
-  return entities;
-}
-
-// ── Bot generator ────────────────────────────────────────────────────────────
-
-/**
- * Generate bot entities for a map.
- *
- * - Each bot picks a random skin from BOT_SKIN_POOL for visual variety.
- * - Random chance to also carry `atlas_pistol_mk2` weapon.
- * - Random count within BOT_RANGE, random positions, random dimensions.
- * - Uses the BOT palette color as fallback.
- *
- * @param {{ gridX: number, gridY: number }} mapDims
- * @param {Array<{ key: string, r: number, g: number, b: number, a: number }>} colors
- * @param {object} [opts]
- * @param {number} [opts.count]         Override count (ignores range).
- * @param {number} [opts.spawnRadius]
- * @param {number} [opts.aggroRange]
- * @param {number} [opts.maxLife]
- * @param {OccupancyGrid} [opts.grid]  If provided, places bots only on walkable cells.
- * @returns {object[]}
+ * @returns {string[]}
  */
-function generateBots(mapDims, colors, opts = {}) {
-  const count = opts.count ?? randInt(BOT_RANGE[0], BOT_RANGE[1]);
-  const { spawnRadius = 5, aggroRange = 10, maxLife = 100 } = opts;
-  const botColor = findColor(colors, 'BOT');
-  const rgba = botColor ? colorToRgba(botColor) : 'rgba(255, 128, 0, 1)';
-
-  const entities = [];
-  for (let i = 0; i < count; i++) {
-    const dim = randInt(DEFAULT_BOT_DIM_RANGE[0], DEFAULT_BOT_DIM_RANGE[1]);
-
-    let cellX, cellY;
-    if (opts.grid) {
-      const pos = opts.grid.findPosition(dim, dim);
-      if (!pos) continue;
-      opts.grid.block(pos.x, pos.y, dim, dim);
-      cellX = pos.x;
-      cellY = pos.y;
-    } else {
-      const maxX = Math.max(0, mapDims.gridX - dim);
-      const maxY = Math.max(0, mapDims.gridY - dim);
-      cellX = randInt(0, maxX);
-      cellY = randInt(0, maxY);
-    }
-
-    const skin = BOT_SKIN_POOL[Math.floor(Math.random() * BOT_SKIN_POOL.length)];
-    const hasWeapon = Math.random() < BOT_WEAPON_CHANCE;
-    const itemIds = hasWeapon ? [skin, 'atlas_pistol_mk2'] : [skin];
-
-    entities.push({
-      entityType: 'bot',
-      initCellX: cellX,
-      initCellY: cellY,
-      dimX: dim,
-      dimY: dim,
-      color: rgba,
-      objectLayerItemIds: itemIds,
-      spawnRadius,
-      aggroRange,
-      maxLife,
-      lifeRegen: 0,
-    });
+function auditFallbackItemIds() {
+  const referenced = collectReferencedItemIds();
+  const missing = [];
+  for (const id of referenced) {
+    if (!KNOWN_DEFAULT_ITEM_IDS.has(id)) missing.push(id);
   }
-  return entities;
+  return missing.sort();
 }
 
 // ── Single map generator ─────────────────────────────────────────────────────
@@ -235,12 +101,13 @@ function generateBots(mapDims, colors, opts = {}) {
  * Everything except floor tiles is randomized.
  *
  * @param {string} mapCode
- * @param {Array} colors             Palette from CYBERIA_INSTANCE_CONF_DEFAULTS.
+ * @param {Array} colors             Palette (PALETTE from SharedDefaultsCyberia).
  * @param {object} [opts]
  * @param {number} [opts.gridSize]
  * @param {number} [opts.obstacleCount]
  * @param {number} [opts.foregroundCount]
  * @param {number} [opts.botCount]
+ * @param {number} [opts.resourceCount]
  * @returns {object}  CyberiaMap-shaped plain object.
  */
 function generateFallbackMap(mapCode, colors, opts = {}) {
@@ -263,10 +130,13 @@ function generateFallbackMap(mapCode, colors, opts = {}) {
   // 5. Bots — placed on walkable cells (avoids obstacles and portals)
   const bots = generateBots(mapDims, colors, { count: opts.botCount, grid });
 
-  // 6. Foreground — decorative, no collision restriction
+  // 6. Resources — static exploitable entities placed on walkable cells
+  const resources = generateResources(mapDims, colors, { count: opts.resourceCount, grid });
+
+  // 7. Foreground — decorative, no collision restriction
   const foreground = generateForeground(mapDims, colors, { count: opts.foregroundCount });
 
-  const entities = [...floors, ...obstacles, ...portalEntities, ...foreground, ...bots];
+  const entities = [...floors, ...obstacles, ...portalEntities, ...foreground, ...bots, ...resources];
 
   return {
     code: mapCode,
@@ -296,6 +166,7 @@ function generateFallbackMap(mapCode, colors, opts = {}) {
  * @param {number} [opts.obstacleCount]       Obstacles per map (random if omitted).
  * @param {number} [opts.foregroundCount]     Foreground entities per map (random if omitted).
  * @param {number} [opts.botCount]            Bots per map (random if omitted).
+ * @param {number} [opts.resourceCount]        Resources per map (random if omitted).
  * @param {Array}  [opts.colors]              Override palette.
  * @returns {{
  *   instance: object,
@@ -313,9 +184,28 @@ function generateFallbackWorld(opts = {}) {
     obstacleCount,
     foregroundCount,
     botCount,
-    colors = CYBERIA_INSTANCE_CONF_DEFAULTS.colors,
+    resourceCount,
+    // Palette lives in SharedDefaultsCyberia (presentation-owned). The
+    // world generator only uses it to stamp a cosmetic rgba(...) string on
+    // entities so the browser editor / preview can render a coloured
+    // fallback before atlases load. The C client resolves real colours
+    // through domain/presentation_runtime — it does not read this value.
+    colors = PALETTE,
   } = opts;
 
+  // Surface item-id drift loudly on the very first build, so a missing
+  // `bin/cyberia run-workflow import-default-items` run shows up at startup
+  // instead of as silent grey rectangles later.
+  const missing = auditFallbackItemIds();
+  if (missing.length > 0) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[cyberia-fallback-world] item ids referenced by defaults but absent from DefaultCyberiaItems:',
+      missing.join(', '),
+      '— run `node bin/cyberia run-workflow import-default-items` after adding them.',
+    );
+  }
+
   // Generate map codes.
   const mapCodes = [];
   for (let i = 0; i < mapCount; i++) {
@@ -329,6 +219,7 @@ function generateFallbackWorld(opts = {}) {
       obstacleCount,
       foregroundCount,
       botCount,
+      resourceCount,
     }),
   );
 
@@ -352,17 +243,11 @@ function generateFallbackWorld(opts = {}) {
     portals,
     topology,
     config: CYBERIA_INSTANCE_CONF_DEFAULTS,
+    presentationHints: CYBERIA_CLIENT_HINTS_DEFAULTS,
     _fallback: true,
   };
 }
 
 // ── Public API ───────────────────────────────────────────────────────────────
 
-export {
-  generateFallbackWorld,
-  generateFallbackMap,
-  generateFloorEntities,
-  generatePortalEntity,
-  generatePortalEntities,
-  generateBots,
-};
+export { generateFallbackWorld, generateFallbackMap, auditFallbackItemIds };

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

@@ -3,8 +3,8 @@ import { CyberiaInstanceService } from './cyberia-instance.service.js';
 
 const logger = loggerFactory(import.meta);
 
-const CyberiaInstanceController = {
-  fallbackWorld: async (req, res, options) => {
+class CyberiaInstanceController {
+  static fallbackWorld = async (req, res, options) => {
     try {
       const result = await CyberiaInstanceService.fallbackWorld(req);
       return res.status(200).json({ status: 'success', data: result });
@@ -12,8 +12,8 @@ const CyberiaInstanceController = {
       logger.error(error, error.stack);
       return res.status(400).json({ status: 'error', message: error.message });
     }
-  },
-  portalConnect: async (req, res, options) => {
+  };
+  static portalConnect = async (req, res, options) => {
     try {
       const result = await CyberiaInstanceService.portalConnect(req, res, options);
       return res.status(200).json({ status: 'success', data: result });
@@ -21,8 +21,8 @@ const CyberiaInstanceController = {
       logger.error(error, error.stack);
       return res.status(400).json({ status: 'error', message: error.message });
     }
-  },
-  post: async (req, res, options) => {
+  };
+  static post = async (req, res, options) => {
     try {
       const result = await CyberiaInstanceService.post(req, res, options);
       return res.status(200).json({
@@ -36,8 +36,8 @@ const CyberiaInstanceController = {
         message: error.message,
       });
     }
-  },
-  get: async (req, res, options) => {
+  };
+  static get = async (req, res, options) => {
     try {
       const { page, limit } = req.query;
       const result = await CyberiaInstanceService.get(
@@ -56,8 +56,8 @@ const CyberiaInstanceController = {
         message: error.message,
       });
     }
-  },
-  put: async (req, res, options) => {
+  };
+  static put = async (req, res, options) => {
     try {
       const result = await CyberiaInstanceService.put(req, res, options);
       return res.status(200).json({
@@ -71,8 +71,8 @@ const CyberiaInstanceController = {
         message: error.message,
       });
     }
-  },
-  delete: async (req, res, options) => {
+  };
+  static delete = async (req, res, options) => {
     try {
       const result = await CyberiaInstanceService.delete(req, res, options);
       return res.status(200).json({
@@ -86,7 +86,7 @@ const CyberiaInstanceController = {
         message: error.message,
       });
     }
-  },
-};
+  };
+}
 
 export { CyberiaInstanceController };

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

@@ -52,6 +52,9 @@ const CyberiaInstanceSchema = new Schema(
     // Vertex set of the graph
     cyberiaMapCodes: { type: [String], default: [] },
 
+    // Instance-level object layer item IDs.
+    itemIds: { type: [String], default: [] },
+
     // Directed edge set of the graph
     portals: { type: [PortalEdgeSchema], default: [] },
 

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

@@ -5,59 +5,64 @@ import express from 'express';
 
 const logger = loggerFactory(import.meta);
 
-const CyberiaInstanceRouter = (options) => {
-  const router = express.Router();
-  const authMiddleware = options.authMiddleware;
-  // ── Custom actions (must come before generic /:id routes) ──────────────
-  router.get(`/fallback-world`, async (req, res) => await CyberiaInstanceController.fallbackWorld(req, res, options));
-  router.get(
-    `/:id/portal-connect`,
-    authMiddleware,
-    userGuard,
-    async (req, res) => await CyberiaInstanceController.portalConnect(req, res, options),
-  );
+class CyberiaInstanceRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+    // ── Custom actions (must come before generic /:id routes) ──────────────
+    router.get(`/fallback-world`, async (req, res) => await CyberiaInstanceController.fallbackWorld(req, res, options));
+    router.get(
+      `/:id/portal-connect`,
+      options.authMiddleware,
+      userGuard,
+      async (req, res) => await CyberiaInstanceController.portalConnect(req, res, options),
+    );
 
-  router.post(
-    `/:id`,
-    authMiddleware,
-    userGuard,
-    async (req, res) => await CyberiaInstanceController.post(req, res, options),
-  );
-  router.post(
-    `/`,
-    authMiddleware,
-    userGuard,
-    async (req, res) => await CyberiaInstanceController.post(req, res, options),
-  );
-  router.get(`/:id`, async (req, res) => await CyberiaInstanceController.get(req, res, options));
-  router.get(`/`, async (req, res) => await CyberiaInstanceController.get(req, res, options));
-  router.put(
-    `/:id`,
-    authMiddleware,
-    userGuard,
-    async (req, res) => await CyberiaInstanceController.put(req, res, options),
-  );
-  router.put(
-    `/`,
-    authMiddleware,
-    userGuard,
-    async (req, res) => await CyberiaInstanceController.put(req, res, options),
-  );
-  router.delete(
-    `/:id`,
-    authMiddleware,
-    userGuard,
-    async (req, res) => await CyberiaInstanceController.delete(req, res, options),
-  );
-  router.delete(
-    `/`,
-    authMiddleware,
-    adminGuard,
-    async (req, res) => await CyberiaInstanceController.delete(req, res, options),
-  );
-  return router;
-};
+    router.post(
+      `/:id`,
+      options.authMiddleware,
+      userGuard,
+      async (req, res) => await CyberiaInstanceController.post(req, res, options),
+    );
+    router.post(
+      `/`,
+      options.authMiddleware,
+      userGuard,
+      async (req, res) => await CyberiaInstanceController.post(req, res, options),
+    );
+    router.get(`/:id`, async (req, res) => await CyberiaInstanceController.get(req, res, options));
+    router.get(`/`, async (req, res) => await CyberiaInstanceController.get(req, res, options));
+    router.put(
+      `/:id`,
+      options.authMiddleware,
+      userGuard,
+      async (req, res) => await CyberiaInstanceController.put(req, res, options),
+    );
+    router.put(
+      `/`,
+      options.authMiddleware,
+      userGuard,
+      async (req, res) => await CyberiaInstanceController.put(req, res, options),
+    );
+    router.delete(
+      `/:id`,
+      options.authMiddleware,
+      userGuard,
+      async (req, res) => await CyberiaInstanceController.delete(req, res, options),
+    );
+    router.delete(
+      `/`,
+      options.authMiddleware,
+      adminGuard,
+      async (req, res) => await CyberiaInstanceController.delete(req, res, options),
+    );
+    return router;
+  }
+}
 
-const ApiRouter = CyberiaInstanceRouter;
+const ApiRouter = (options) => CyberiaInstanceRouter.router(options);
 
 export { ApiRouter, CyberiaInstanceRouter };