@underpostnet/cyberia 3.3.0 → 3.3.76

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

@@ -0,0 +1,502 @@
+/**
+ * Fallback-world capture — materialise the in-memory procedural world into
+ * MongoDB so it can be exported, versioned, and re-imported like any authored
+ * instance.
+ *
+ * The fallback world (cyberia-fallback-world.js) is never persisted: every
+ * engine process rebuilds it from code defaults at boot and serves it whenever
+ * a requested instance is absent. Capturing it means writing everything that
+ * in-memory world serves under a real instance code:
+ *
+ *   - CyberiaInstance      — map graph, portal edges, player spawn, item ids
+ *   - CyberiaMap           — one document per generated map (entities included)
+ *   - CyberiaInstanceConf  — the world's simulation config
+ *   - CyberiaSkill / CyberiaEntityTypeDefault / CyberiaDialogue /
+ *     CyberiaAction / CyberiaQuest — the content collections the fallback path
+ *     reads from code defaults INSTEAD of Mongo; a persisted instance reads
+ *     them from Mongo, so they must exist there for the capture to serve the
+ *     same world (see instance-data.js#fetchFullInstance).
+ *   - CyberiaMapAudioConf — one per captured map. The client asks for audio by
+ *     map code, so a namespaced capture would otherwise play nothing.
+ *
+ * CyberiaAudio assets are NOT captured: an asset is global, identified by its
+ * code, and imported once by `cyberia audio --import`. The capture reports the
+ * codes it bound that no asset carries yet.
+ *
+ * ObjectLayer/atlas assets are NOT generated here — they come from the asset
+ * pipeline (`bin/cyberia ol <ids> --import`). The capture reports the missing
+ * ids so the caller can stop before writing an incomplete backup.
+ *
+ * Map and content codes are namespaced under the instance code by default, so
+ * two captures never overwrite each other's documents (map/action/quest codes
+ * are globally unique). `keepFallbackCodes` preserves the raw
+ * `fallback-map-*` / canonical action-quest codes instead.
+ *
+ * @module src/api/cyberia-instance/cyberia-fallback-capture
+ */
+
+import { loggerFactory } from '../../server/ops/logger.js';
+import { collectReferencedItemIds } from './cyberia-fallback-world.js';
+import { collectInstanceItemIds } from './cyberia-instance-items.js';
+import { fallbackAudioConfig } from '../../projects/cyberia/seed-audio.js';
+import {
+  DefaultCyberiaActions,
+  DefaultCyberiaQuests,
+  DefaultCyberiaDialogues,
+  DefaultSkillConfig,
+  ENTITY_TYPE_DEFAULTS,
+  fillInstanceConfDefaults,
+} from '../cyberia-server-defaults/cyberia-server-defaults.js';
+
+const logger = loggerFactory(import.meta);
+
+const FALLBACK_MAP_CODE_PREFIX = 'fallback-map-';
+
+/** Mongo document keys that must never travel inside a `$set` payload. */
+const DOC_METADATA_KEYS = ['_id', '__v', 'createdAt', 'updatedAt'];
+
+const stripDocMetadata = (doc, extraKeys = []) => {
+  const out = { ...doc };
+  for (const key of [...DOC_METADATA_KEYS, ...extraKeys]) delete out[key];
+  return out;
+};
+
+const escapeRegExp = (value) => String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Namespaced map code for a captured fallback map (`fallback-map-2` → `X-map-2`). */
+function captureMapCode(mapCode, instanceCode) {
+  const suffix = mapCode.startsWith(FALLBACK_MAP_CODE_PREFIX)
+    ? mapCode.slice(FALLBACK_MAP_CODE_PREFIX.length)
+    : mapCode;
+  return `${instanceCode}-map-${suffix}`;
+}
+
+/** Namespaced action/quest code for a captured world. */
+const captureContentCode = (code, instanceCode) => `${instanceCode}-${code}`;
+
+/**
+ * Build the code translation tables for one capture.
+ *
+ * @param {object} world      Result of `generateFallbackWorld()`.
+ * @param {string} instanceCode
+ * @param {boolean} keepFallbackCodes
+ * @returns {{ mapCodes: Map<string,string>, questCodes: Map<string,string>, actionCodes: Map<string,string> }}
+ */
+function buildCaptureCodeMaps({ world, instanceCode, keepFallbackCodes, actions, quests }) {
+  const mapCodes = new Map();
+  const rememberMapCode = (code) => {
+    if (!code || mapCodes.has(code)) return;
+    mapCodes.set(code, keepFallbackCodes ? code : captureMapCode(code, instanceCode));
+  };
+
+  for (const code of world.instance?.cyberiaMapCodes || []) rememberMapCode(code);
+  for (const map of world.maps || []) rememberMapCode(map.code);
+  for (const portal of world.instance?.portals || []) {
+    rememberMapCode(portal.sourceMapCode);
+    rememberMapCode(portal.targetMapCode);
+  }
+
+  const contentCodes = (docs) =>
+    new Map(
+      (docs || [])
+        .filter((doc) => doc?.code)
+        .map((doc) => [doc.code, keepFallbackCodes ? doc.code : captureContentCode(doc.code, instanceCode)]),
+    );
+
+  return { mapCodes, actionCodes: contentCodes(actions), questCodes: contentCodes(quests) };
+}
+
+/**
+ * Translate one default action into its captured form. Returns `null` when the
+ * action lives on a map this world does not contain — a persisted instance
+ * only ever serves actions bound to its own maps.
+ */
+function captureAction(action, { mapCodes, actionCodes, questCodes }) {
+  const sourceMapCode = mapCodes.get(action.sourceMapCode);
+  if (!sourceMapCode) return null;
+  return {
+    ...action,
+    code: actionCodes.get(action.code) || action.code,
+    sourceMapCode,
+    questDialogueCodes: (action.questDialogueCodes || []).map((entry) => ({
+      ...entry,
+      questCode: questCodes.get(entry.questCode) || entry.questCode,
+    })),
+  };
+}
+
+/** Translate one default quest into its captured form (`null` = foreign map). */
+function captureQuest(quest, { mapCodes, questCodes }) {
+  const sourceMapCode = mapCodes.get(quest.sourceMapCode);
+  if (!sourceMapCode) return null;
+  const translate = (codes) => (codes || []).map((code) => questCodes.get(code) || code);
+  return {
+    ...quest,
+    code: questCodes.get(quest.code) || quest.code,
+    sourceMapCode,
+    prerequisiteCodes: translate(quest.prerequisiteCodes),
+    unlocksQuestCodes: translate(quest.unlocksQuestCodes),
+  };
+}
+
+/**
+ * Pure planner: turn an in-memory fallback world into the exact set of
+ * documents a capture writes. No I/O — the whole translation is testable
+ * without a database.
+ *
+ * @param {object}   params
+ * @param {object}   params.world              Result of `generateFallbackWorld()`.
+ * @param {string}   params.instanceCode       Code the capture is stored under.
+ * @param {boolean}  [params.keepFallbackCodes=false]
+ * @param {Array}    [params.actions=DefaultCyberiaActions]
+ * @param {Array}    [params.quests=DefaultCyberiaQuests]
+ * @returns {{
+ *   instance: object, conf: object, maps: object[], actions: object[], quests: object[],
+ *   codeMaps: object, skippedActionCodes: string[], skippedQuestCodes: string[], itemIds: string[]
+ * }}
+ */
+function planFallbackCapture({
+  world,
+  instanceCode,
+  keepFallbackCodes = false,
+  actions = DefaultCyberiaActions,
+  quests = DefaultCyberiaQuests,
+}) {
+  if (!world?.instance || !Array.isArray(world.maps)) throw new Error('planFallbackCapture: invalid world');
+  if (!instanceCode) throw new Error('planFallbackCapture: instanceCode is required');
+
+  const codeMaps = buildCaptureCodeMaps({ world, instanceCode, keepFallbackCodes, actions, quests });
+  const { mapCodes } = codeMaps;
+
+  const maps = world.maps.map((map) => ({
+    code: mapCodes.get(map.code) || map.code,
+    name: map.name || mapCodes.get(map.code) || map.code,
+    description: map.description || '',
+    gridX: map.gridX,
+    gridY: map.gridY,
+    cellWidth: map.cellWidth,
+    cellHeight: map.cellHeight,
+    entities: (map.entities || []).map((entity) => ({ ...entity })),
+    tags: ['fallback', 'procedural', 'captured'],
+  }));
+
+  const spawn = world.instance.playerSpawn || {};
+  const instance = {
+    code: instanceCode,
+    name: instanceCode,
+    description: 'Captured procedural fallback world',
+    tags: ['fallback', 'procedural', 'captured'],
+    cyberiaMapCodes: (world.instance.cyberiaMapCodes || []).map((code) => mapCodes.get(code) || code),
+    portals: (world.instance.portals || []).map((portal) => ({
+      ...portal,
+      sourceMapCode: mapCodes.get(portal.sourceMapCode) || portal.sourceMapCode,
+      targetMapCode: mapCodes.get(portal.targetMapCode) || portal.targetMapCode,
+    })),
+    playerSpawn: {
+      ...spawn,
+      ...(spawn.sourceMapCode ? { sourceMapCode: mapCodes.get(spawn.sourceMapCode) || spawn.sourceMapCode } : {}),
+    },
+    topologyMode: 'procedural',
+  };
+
+  const conf = { ...fillInstanceConfDefaults(world.config || {}), instanceCode };
+
+  const capturedActions = [];
+  const skippedActionCodes = [];
+  for (const action of actions) {
+    const captured = captureAction(action, codeMaps);
+    if (captured) capturedActions.push(captured);
+    else skippedActionCodes.push(action.code);
+  }
+
+  const capturedQuests = [];
+  const skippedQuestCodes = [];
+  for (const quest of quests) {
+    const captured = captureQuest(quest, codeMaps);
+    if (captured) capturedQuests.push(captured);
+    else skippedQuestCodes.push(quest.code);
+  }
+
+  return {
+    instance,
+    conf,
+    maps,
+    actions: capturedActions,
+    quests: capturedQuests,
+    codeMaps,
+    skippedActionCodes,
+    skippedQuestCodes,
+    itemIds: collectCaptureItemIds({ maps, actions: capturedActions, quests: capturedQuests }),
+  };
+}
+
+/**
+ * Every ObjectLayer item id the captured instance needs an atlas for: the canonical world's
+ * own ids, plus what this instance names — its maps, its entity-type defaults, and the
+ * vendor/assembler/quest catalogs the interact modal draws icons for.
+ *
+ * @returns {string[]} Sorted, de-duplicated item ids.
+ */
+function collectCaptureItemIds({ maps, actions, quests, entityDefaults = [] }) {
+  // The canonical world's own ids — every fallback default, including the skill triggers and
+  // summoned entities DefaultSkillConfig names. What the captured instance adds on top follows
+  // the same rule the export and the boot payload use.
+  const ids = collectReferencedItemIds();
+  // The conf references its entity-type defaults by _id, so the documents arrive resolved.
+  for (const itemId of collectInstanceItemIds({ maps, entityDefaults, actions, quests })) ids.add(itemId);
+  return [...ids].sort();
+}
+
+/**
+ * Insert the content collections the fallback path serves from code defaults.
+ *
+ * Insert-only: an existing document is left exactly as the operator (or an
+ * earlier import) left it, so a capture never silently rewrites content shared
+ * with other instances. Returns per-collection insert counts.
+ */
+async function seedMissingContentDefaults({ CyberiaSkill, CyberiaEntityTypeDefault, CyberiaDialogue }) {
+  const inserted = { skills: 0, entityTypeDefaults: 0, dialogues: 0 };
+
+  const insertIfMissing = async (Model, filter, doc, counterKey) => {
+    if (!Model) return;
+    const existing = await Model.findOne(filter).lean();
+    if (existing) return;
+    await Model.create(doc);
+    inserted[counterKey]++;
+  };
+
+  for (const skill of DefaultSkillConfig) {
+    await insertIfMissing(
+      CyberiaSkill,
+      { triggerItemId: skill.triggerItemId },
+      { triggerItemId: skill.triggerItemId, logicEventIds: skill.logicEventIds || [], skills: skill.skills || [] },
+      'skills',
+    );
+  }
+
+  for (const entityDefault of ENTITY_TYPE_DEFAULTS) {
+    await insertIfMissing(
+      CyberiaEntityTypeDefault,
+      { entityType: entityDefault.entityType, liveItemIds: entityDefault.liveItemIds || [] },
+      {
+        entityType: entityDefault.entityType,
+        liveItemIds: entityDefault.liveItemIds || [],
+        deadItemIds: entityDefault.deadItemIds || [],
+        dropItemIds: entityDefault.dropItemIds || [],
+        inventoryItemsIds: entityDefault.inventoryItemsIds || [],
+        overrideItemsIdsState: entityDefault.overrideItemsIdsState || [],
+        behavior: entityDefault.behavior || '',
+      },
+      'entityTypeDefaults',
+    );
+  }
+
+  for (const dialogue of DefaultCyberiaDialogues) {
+    await insertIfMissing(
+      CyberiaDialogue,
+      { code: dialogue.code, order: dialogue.order },
+      { ...dialogue },
+      'dialogues',
+    );
+  }
+
+  return inserted;
+}
+
+/**
+ * Write the audio configuration of the captured maps.
+ *
+ * Audio reaches the client per map code, so a world captured under namespaced codes needs its
+ * bindings rewritten under those codes — the same reason the actions and quests are re-coded.
+ * Only codes an imported asset actually carries are bound: a binding to an absent asset would be
+ * a dangling name, and the caller is told which ones are missing instead.
+ *
+ * @param {object} params
+ * @param {object} params.models - `{ CyberiaMapAudioConf, CyberiaAudio }`.
+ * @param {object} params.plan - Result of `planFallbackCapture()`.
+ * @returns {Promise<{audioConfs: number, missingAudioCodes: string[]}>}
+ */
+async function captureAudioConfig({ models, plan }) {
+  const { CyberiaMapAudioConf, CyberiaAudio } = models;
+  if (!CyberiaMapAudioConf) return { audioConfs: 0, missingAudioCodes: [] };
+
+  const config = fallbackAudioConfig();
+  const bound = new Set(
+    [...config.events.map(({ audioCode }) => audioCode), ...config.maps.map(({ defaultMusic }) => defaultMusic)].filter(
+      Boolean,
+    ),
+  );
+  const present = new Set(
+    CyberiaAudio
+      ? (await CyberiaAudio.find({ code: { $in: [...bound] } }, { code: 1 }).lean()).map((doc) => doc.code)
+      : [],
+  );
+  const events = config.events.filter(({ audioCode }) => present.has(audioCode));
+
+  let audioConfs = 0;
+  for (const map of config.maps) {
+    const mapCode = plan.codeMaps.mapCodes.get(map.mapCode);
+    if (!mapCode) continue;
+    await CyberiaMapAudioConf.findOneAndUpdate(
+      { mapCode },
+      {
+        $set: {
+          defaultMusic: present.has(map.defaultMusic) ? map.defaultMusic : '',
+          settings: config.settings,
+          events,
+        },
+      },
+      { upsert: true },
+    );
+    audioConfs++;
+  }
+  return { audioConfs, missingAudioCodes: [...bound].filter((code) => !present.has(code)).sort() };
+}
+
+/**
+ * Remove documents that a larger previous capture left in this capture's own
+ * namespace. Touches only codes prefixed with the instance code, and never runs
+ * in `keepFallbackCodes` mode, where the codes are the shared canonical ones.
+ */
+async function pruneStaleCaptureDocs({ models, instanceCode, plan }) {
+  const namespace = new RegExp(`^${escapeRegExp(instanceCode)}-`);
+  const pruned = { maps: 0, actions: 0, quests: 0 };
+
+  const prune = async (Model, keepCodes, counterKey) => {
+    if (!Model) return;
+    const result = await Model.deleteMany({ code: { $regex: namespace, $nin: keepCodes } });
+    pruned[counterKey] = result?.deletedCount || 0;
+  };
+
+  await prune(
+    models.CyberiaMap,
+    plan.maps.map((map) => map.code),
+    'maps',
+  );
+  await prune(
+    models.CyberiaAction,
+    plan.actions.map((action) => action.code),
+    'actions',
+  );
+  await prune(
+    models.CyberiaQuest,
+    plan.quests.map((quest) => quest.code),
+    'quests',
+  );
+
+  return pruned;
+}
+
+/**
+ * Materialise an in-memory fallback world into MongoDB under `instanceCode`.
+ *
+ * Idempotent: every write is an upsert keyed by the document's natural code,
+ * so re-running a capture converges on the same state. Nothing is deleted
+ * except stale documents inside this capture's own code namespace.
+ *
+ * @param {object} params
+ * @param {object} params.models       `{ CyberiaInstance, CyberiaInstanceConf, CyberiaMap, CyberiaAction,
+ *                                        CyberiaQuest, CyberiaSkill, CyberiaEntityTypeDefault,
+ *                                        CyberiaDialogue, CyberiaMapAudioConf, CyberiaAudio,
+ *                                        ObjectLayer }`
+ * @param {object} params.world        Result of `generateFallbackWorld()`.
+ * @param {string} params.instanceCode
+ * @param {boolean} [params.keepFallbackCodes=false]
+ * @returns {Promise<{plan: object, inserted: object, pruned: object, missingObjectLayerItemIds: string[]}>}
+ */
+async function captureFallbackWorld({ models, world, instanceCode, keepFallbackCodes = false }) {
+  const plan = planFallbackCapture({ world, instanceCode, keepFallbackCodes });
+
+  // Conf first: the instance document carries the ObjectId ref to it.
+  const confDoc = await models.CyberiaInstanceConf.findOneAndUpdate(
+    { instanceCode },
+    { $set: stripDocMetadata(plan.conf, ['instanceCode']) },
+    { upsert: true, returnDocument: 'after' },
+  );
+  logger.info('Captured CyberiaInstanceConf', { instanceCode });
+
+  for (const map of plan.maps) {
+    await models.CyberiaMap.findOneAndUpdate(
+      { code: map.code },
+      { $set: stripDocMetadata(map, ['code']) },
+      { upsert: true },
+    );
+  }
+  logger.info(`Captured ${plan.maps.length} CyberiaMap document(s)`, { codes: plan.maps.map((m) => m.code) });
+
+  await models.CyberiaInstance.findOneAndUpdate(
+    { code: instanceCode },
+    {
+      $set: {
+        ...stripDocMetadata(plan.instance, ['code']),
+        ...(confDoc?._id ? { conf: confDoc._id } : {}),
+      },
+      $setOnInsert: { status: 'unlisted' },
+    },
+    { upsert: true },
+  );
+  logger.info('Captured CyberiaInstance', { code: instanceCode, maps: plan.instance.cyberiaMapCodes.length });
+
+  for (const action of plan.actions) {
+    await models.CyberiaAction.findOneAndUpdate(
+      { code: action.code },
+      { $set: stripDocMetadata(action, ['code']) },
+      { upsert: true },
+    );
+  }
+  for (const quest of plan.quests) {
+    await models.CyberiaQuest.findOneAndUpdate(
+      { code: quest.code },
+      { $set: stripDocMetadata(quest, ['code']) },
+      { upsert: true },
+    );
+  }
+  logger.info(`Captured ${plan.actions.length} CyberiaAction and ${plan.quests.length} CyberiaQuest document(s)`);
+  if (plan.skippedActionCodes.length > 0 || plan.skippedQuestCodes.length > 0) {
+    logger.warn('Skipped mission content bound to maps outside the captured world', {
+      actions: plan.skippedActionCodes,
+      quests: plan.skippedQuestCodes,
+    });
+  }
+
+  const inserted = await seedMissingContentDefaults(models);
+  logger.info('Seeded missing content defaults', inserted);
+
+  const audio = await captureAudioConfig({ models, plan });
+  logger.info(`Captured ${audio.audioConfs} CyberiaMapAudioConf document(s)`);
+  if (audio.missingAudioCodes.length > 0) {
+    logger.warn(
+      'Audio codes with no imported CyberiaAudio document were left unbound — ' +
+        'run `node bin/cyberia run-workflow seed-audio` to record and import them',
+      { codes: audio.missingAudioCodes },
+    );
+  }
+
+  // `keepFallbackCodes` reuses the globally shared canonical codes, so nothing
+  // in that namespace belongs exclusively to this capture.
+  const pruned = keepFallbackCodes
+    ? { maps: 0, actions: 0, quests: 0 }
+    : await pruneStaleCaptureDocs({ models, instanceCode, plan });
+  if (pruned.maps || pruned.actions || pruned.quests)
+    logger.info('Pruned stale documents from a previous capture', pruned);
+
+  const presentItemIds = new Set(
+    (await models.ObjectLayer.find({ 'data.item.id': { $in: plan.itemIds } }, { 'data.item.id': 1 }).lean()).map(
+      (doc) => doc.data?.item?.id,
+    ),
+  );
+  const missingObjectLayerItemIds = plan.itemIds.filter((id) => !presentItemIds.has(id));
+
+  return { plan, inserted, pruned, audio, missingObjectLayerItemIds };
+}
+
+export {
+  planFallbackCapture,
+  captureAudioConfig,
+  captureFallbackWorld,
+  collectCaptureItemIds,
+  captureMapCode,
+  captureContentCode,
+  seedMissingContentDefaults,
+  FALLBACK_MAP_CODE_PREFIX,
+};

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

@@ -53,19 +53,26 @@ import {
 const DEFAULT_MAP_COUNT = 4;
 const DEFAULT_GRID_SIZE = 64;
 
+const getFallbackMapCodes = (mapCount = DEFAULT_MAP_COUNT) =>
+  Array.from({ length: mapCount }, (_, index) => `fallback-map-${index}`);
+
 // ── 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.
+// Every item id the fallback world can place must also be in
+// DefaultCyberiaItems. Otherwise the `import-default-items` seed creates no
+// ObjectLayer for it and the client draws a solid-colour rectangle.
 //
-// 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.
+// auditFallbackItemIds() returns the unknown ids, empty when in sync.
 
 const KNOWN_DEFAULT_ITEM_IDS = new Set(DefaultCyberiaItems.map((e) => e.item.id));
 
+/**
+ * Every item id the canonical defaults can place, equip, summon, sell, or
+ * craft. Shared with the fallback-world capture, which must resolve an atlas
+ * for each of them before writing a backup.
+ *
+ * @returns {Set<string>}
+ */
 function collectReferencedItemIds() {
   const ids = new Set();
   const push = (id) => {
@@ -76,7 +83,7 @@ function collectReferencedItemIds() {
     (e.liveItemIds || []).forEach(push);
     (e.deadItemIds || []).forEach(push);
     (e.dropItemIds || []).forEach(push);
-    (e.defaultObjectLayers || []).forEach((ol) => push(ol.itemId));
+    (e.inventoryItemsIds || []).forEach(push);
   }
   for (const r of RESOURCE_ENTITY_TYPE_DEFAULTS) {
     (r.liveItemIds || []).forEach(push);
@@ -232,11 +239,6 @@ function generateFallbackMap(mapCode, colors, opts = {}) {
  * @param {number} [opts.resourceCount]        Resources per map (random if omitted).
  * @param {number} [opts.staticCount]          Static decorators per map (random if omitted).
  * @param {Array}  [opts.colors]              Override palette.
- * @param {Array<{id: string, defaultPlayerInventory: boolean}>} [opts.itemIds=[]]
- *   Instance-level default items, mirroring `CyberiaInstance.itemIds`. Entries
- *   flagged `defaultPlayerInventory` are merged into the player entity default
- *   by `applyInstanceDefaultPlayerInventory`; every id is also resolved to an
- *   atlas at boot. Layout is unaffected, so this stays outside the world seed.
  * @returns {{
  *   instance: object,
  *   maps: object[],
@@ -255,18 +257,13 @@ function generateFallbackWorld(opts = {}) {
     botCount,
     resourceCount,
     staticCount,
-    // 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.
+    // Palette from SharedDefaultsCyberia. The generator only stamps a cosmetic
+    // rgba(...) string on entities, for previews drawn before atlases load. The
+    // game client resolves its own colours and ignores this value.
     colors = PALETTE,
-    itemIds = [],
   } = 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.
+  // Report item-id drift at the first build, not as grey rectangles later.
   const missing = auditFallbackItemIds();
   if (missing.length > 0) {
     // eslint-disable-next-line no-console
@@ -277,18 +274,12 @@ function generateFallbackWorld(opts = {}) {
     );
   }
 
-  // Generate map codes.
-  const mapCodes = [];
-  for (let i = 0; i < mapCount; i++) {
-    mapCodes.push(`fallback-map-${i}`);
-  }
+  const mapCodes = getFallbackMapCodes(mapCount);
 
-  // Deterministic layout: seed the shared random source so every call
-  // reproduces the SAME world. The instance-map `/static` POIs and the
-  // `/preview` node image are built by independent requests (and survive
-  // restarts) — they must agree on where every entity sits, so a resource POI
-  // lands exactly where the preview draws that resource. The seed folds in the
-  // layout-affecting options so a custom count set stays internally consistent.
+  // Deterministic layout: the seeded random source makes every call reproduce
+  // the same world. The `/static` POIs and the `/preview` image come from
+  // independent requests and must agree on where each entity sits. The seed
+  // folds in the layout options, so a custom count set stays consistent.
   const seed = `cyberia-fallback-world-v1:${mapCount}:${gridSize ?? ''}:${obstacleCount ?? ''}:${
     foregroundCount ?? ''
   }:${botCount ?? ''}:${resourceCount ?? ''}:${staticCount ?? ''}`;
@@ -320,7 +311,6 @@ function generateFallbackWorld(opts = {}) {
     portals,
     topologyMode: 'procedural',
     playerSpawn: { ...DEFAULT_PLAYER_SPAWN },
-    itemIds: itemIds.map((entry) => ({ ...entry })),
   };
 
   return {
@@ -336,12 +326,9 @@ function generateFallbackWorld(opts = {}) {
 
 // ── Selection-view fallback instance ─────────────────────────────────────────
 //
-// A dummy, never-persisted instance surfaced in the world/instance selection
-// list so it is never empty: it points at the always-on TEST variant (a real
-// deployed world in the mmo-server multiInstance block). Shaped like a
-// CyberiaInstance list row — only the fields InstanceSelectionView reads
-// (code/name/description/tags/status/thumbnail). Injected into the instance list
-// return by CyberiaInstanceService.get when the caller opts in (?fallback=true).
+// A never-persisted instance row that keeps the selection list non-empty. It
+// points at the always-on TEST variant and carries only the fields the
+// selection view reads. CyberiaInstanceService.get injects it on ?fallback=true.
 
 const DEFAULT_FALLBACK_INSTANCE_CODE = 'TEST';
 
@@ -363,9 +350,11 @@ function fallbackListInstance() {
 // ── Public API ───────────────────────────────────────────────────────────────
 
 export {
+  getFallbackMapCodes,
   generateFallbackWorld,
   generateFallbackMap,
   auditFallbackItemIds,
+  collectReferencedItemIds,
   fallbackListInstance,
   DEFAULT_FALLBACK_INSTANCE_CODE,
 };

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

@@ -1,11 +1,11 @@
 /**
  * REST boot service — the /api/cyberia-instance/boot/* fallback transport.
  *
- * Serves the exact CyberiaDataService payloads (world load, hot reload) over
- * REST so cyberia-server can boot from ENGINE_API_BASE_URL when the engine
- * gRPC server (ENGINE_GRPC_ADDRESS) is not enabled for the deploy. All data
- * assembly lives in src/projects/cyberia/instance-data.js, shared with
- * src/grpc/cyberia/grpc-server.js so both transports stay equivalent.
+ * Serves the CyberiaDataService payloads (world load, hot reload) over REST, so
+ * the game server can boot from its --data-server-url when the engine gRPC
+ * server is off for the deploy. The data assembly lives in
+ * src/projects/cyberia/instance-data.js, shared with
+ * src/grpc/cyberia/grpc-server.js, so both transports stay equivalent.
  *
  * Endpoints (all GET, internal server-to-server, mirroring the RPCs):
  *   /boot/ping                         → { serverTimeMs }