@underpostnet/cyberia 3.3.73 → 3.3.77

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

@@ -16,6 +16,12 @@
  *     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
@@ -31,6 +37,8 @@
 
 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,
@@ -189,7 +197,6 @@ function planFallbackCapture({
       ...(spawn.sourceMapCode ? { sourceMapCode: mapCodes.get(spawn.sourceMapCode) || spawn.sourceMapCode } : {}),
     },
     topologyMode: 'procedural',
-    itemIds: (world.instance.itemIds || []).map((entry) => ({ ...entry })),
   };
 
   const conf = { ...fillInstanceConfDefaults(world.config || {}), instanceCode };
@@ -219,57 +226,24 @@ function planFallbackCapture({
     codeMaps,
     skippedActionCodes,
     skippedQuestCodes,
-    itemIds: collectCaptureItemIds({ instance, conf, maps, actions: capturedActions, quests: capturedQuests }),
+    itemIds: collectCaptureItemIds({ maps, actions: capturedActions, quests: capturedQuests }),
   };
 }
 
 /**
- * Every ObjectLayer item id the captured instance needs an atlas for: what the
- * maps place, what the instance and conf declare, what the seeded skills and
- * entity-type defaults reference, and what the vendor/assembler/quest catalogs
- * draw icons for.
+ * 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({ instance, conf, maps, actions, quests }) {
+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();
-  const push = (id) => {
-    if (typeof id === 'string' && id.length > 0 && !id.startsWith('$')) ids.add(id);
-  };
-
-  for (const map of maps || []) {
-    for (const entity of map.entities || []) (entity.objectLayerItemIds || []).forEach(push);
-  }
-  for (const entry of instance?.itemIds || []) push(typeof entry === 'string' ? entry : entry?.id);
-
-  for (const entityDefault of conf?.entityDefaults || []) {
-    (entityDefault.liveItemIds || []).forEach(push);
-    (entityDefault.deadItemIds || []).forEach(push);
-    (entityDefault.dropItemIds || []).forEach(push);
-    for (const slot of entityDefault.defaultObjectLayers || []) push(slot.itemId);
-  }
-  for (const skillConfig of conf?.skillConfig || []) {
-    push(skillConfig.triggerItemId);
-    for (const skill of skillConfig.skills || []) push(skill.summonedEntityItemId);
-  }
-
-  for (const action of actions || []) {
-    for (const shopItem of action.shopItems || []) {
-      push(shopItem.itemId);
-      push(shopItem.priceItemId);
-    }
-    for (const recipe of action.craftRecipes || []) {
-      (recipe.ingredients || []).forEach((ingredient) => push(ingredient.itemId));
-      (recipe.outputItems || []).forEach((output) => push(output.itemId));
-    }
-  }
-  for (const quest of quests || []) {
-    for (const step of quest.steps || []) {
-      for (const objective of step.objectives || []) push(objective.itemId);
-    }
-    for (const reward of quest.rewards || []) push(reward.itemId);
-  }
-
+  // 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();
 }
 
@@ -309,7 +283,8 @@ async function seedMissingContentDefaults({ CyberiaSkill, CyberiaEntityTypeDefau
         liveItemIds: entityDefault.liveItemIds || [],
         deadItemIds: entityDefault.deadItemIds || [],
         dropItemIds: entityDefault.dropItemIds || [],
-        defaultObjectLayers: entityDefault.defaultObjectLayers || [],
+        inventoryItemsIds: entityDefault.inventoryItemsIds || [],
+        overrideItemsIdsState: entityDefault.overrideItemsIdsState || [],
         behavior: entityDefault.behavior || '',
       },
       'entityTypeDefaults',
@@ -329,10 +304,59 @@ async function seedMissingContentDefaults({ CyberiaSkill, CyberiaEntityTypeDefau
 }
 
 /**
- * Remove documents left over in this capture's own namespace by a previous,
- * larger capture (e.g. a world that used to have more maps). Only ever touches
- * codes prefixed with the instance code, and never runs in `keepFallbackCodes`
- * mode where the codes are the globally shared canonical ones.
+ * 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)}-`);
@@ -373,7 +397,8 @@ async function pruneStaleCaptureDocs({ models, instanceCode, plan }) {
  * @param {object} params
  * @param {object} params.models       `{ CyberiaInstance, CyberiaInstanceConf, CyberiaMap, CyberiaAction,
  *                                        CyberiaQuest, CyberiaSkill, CyberiaEntityTypeDefault,
- *                                        CyberiaDialogue, ObjectLayer }`
+ *                                        CyberiaDialogue, CyberiaMapAudioConf, CyberiaAudio,
+ *                                        ObjectLayer }`
  * @param {object} params.world        Result of `generateFallbackWorld()`.
  * @param {string} params.instanceCode
  * @param {boolean} [params.keepFallbackCodes=false]
@@ -437,6 +462,16 @@ async function captureFallbackWorld({ models, world, instanceCode, keepFallbackC
   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
@@ -452,11 +487,12 @@ async function captureFallbackWorld({ models, world, instanceCode, keepFallbackC
   );
   const missingObjectLayerItemIds = plan.itemIds.filter((id) => !presentItemIds.has(id));
 
-  return { plan, inserted, pruned, missingObjectLayerItemIds };
+  return { plan, inserted, pruned, audio, missingObjectLayerItemIds };
 }
 
 export {
   planFallbackCapture,
+  captureAudioConfig,
   captureFallbackWorld,
   collectCaptureItemIds,
   captureMapCode,

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

@@ -53,16 +53,16 @@ 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));
 
@@ -83,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);
@@ -239,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[],
@@ -262,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
@@ -284,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 ?? ''}`;
@@ -327,7 +311,6 @@ function generateFallbackWorld(opts = {}) {
     portals,
     topologyMode: 'procedural',
     playerSpawn: { ...DEFAULT_PLAYER_SPAWN },
-    itemIds: itemIds.map((entry) => ({ ...entry })),
   };
 
   return {
@@ -343,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';
 
@@ -370,6 +350,7 @@ function fallbackListInstance() {
 // ── Public API ───────────────────────────────────────────────────────────────
 
 export {
+  getFallbackMapCodes,
   generateFallbackWorld,
   generateFallbackMap,
   auditFallbackItemIds,

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 }

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

@@ -0,0 +1,98 @@
+/**
+ * What content an instance owns, and which skills follow from it.
+ *
+ * An instance is a set of maps plus the content bound to them. Everything else it needs —
+ * atlases to draw, skills to fire — follows from the item ids that content names. Deriving
+ * that set in one place is what keeps the export, the capture, the boot payload and the
+ * editor's report agreeing: they used to each answer "what belongs to this world" slightly
+ * differently, and a skill would export but not boot, or boot but not export.
+ */
+
+/** A '$'-prefixed id is a runtime placeholder the simulation resolves, never a document. */
+const isMaterialItemId = (itemId) => typeof itemId === 'string' && itemId.length > 0 && !itemId.startsWith('$');
+
+/**
+ * Every ObjectLayer item id an instance's own content names.
+ *
+ * Four sources, and they are the whole list: what its maps place, what its entity-type
+ * defaults wire, what its vendors and assemblers trade, and what its quests ask for or pay
+ * out. A skill trigger is not a source — skills are selected from this set, not folded into
+ * it — and neither is another instance's content.
+ *
+ * @param {object} content
+ * @param {Array<{entities?: Array<{objectLayerItemIds?: string[]}>}>} [content.maps]
+ * @param {Array<object>} [content.entityDefaults] - Resolved documents, not references.
+ * @param {Array<object>} [content.actions] - Vendor / assembler catalogs.
+ * @param {Array<object>} [content.quests]
+ * @returns {Set<string>} Item ids, placeholders excluded.
+ */
+function collectInstanceItemIds({ maps = [], entityDefaults = [], actions = [], quests = [] } = {}) {
+  const itemIds = new Set();
+  const push = (itemId) => {
+    if (isMaterialItemId(itemId)) itemIds.add(itemId);
+  };
+
+  for (const map of maps) {
+    for (const entity of map?.entities || []) (entity?.objectLayerItemIds || []).forEach(push);
+  }
+  for (const entityDefault of entityDefaults) {
+    for (const list of ['liveItemIds', 'deadItemIds', 'dropItemIds', 'inventoryItemsIds']) {
+      (entityDefault?.[list] || []).forEach(push);
+    }
+  }
+  for (const action of actions) {
+    for (const shopItem of action?.shopItems || []) {
+      push(shopItem?.itemId);
+      push(shopItem?.priceItemId);
+    }
+    for (const recipe of action?.craftRecipes || []) {
+      (recipe?.ingredients || []).forEach((ingredient) => push(ingredient?.itemId));
+      (recipe?.outputItems || []).forEach((output) => push(output?.itemId));
+    }
+  }
+  for (const quest of quests) {
+    for (const step of quest?.steps || []) {
+      for (const objective of step?.objectives || []) push(objective?.itemId);
+    }
+    for (const reward of quest?.rewards || []) push(reward?.itemId);
+  }
+  return itemIds;
+}
+
+/**
+ * The skills an instance runs: one per trigger item its content names.
+ *
+ * This is the whole membership rule, and it is why `hatchet` belongs to a world whose maps
+ * place no hatchet — a quest objective or a vendor's shelf names it, so an entity there can
+ * come to hold one and fire it. A skill for a trigger nothing in the world names is
+ * unreachable and is left out.
+ *
+ * @param {Array<{triggerItemId?: string}>} skills - Candidate CyberiaSkill documents.
+ * @param {Set<string>|string[]} itemIds - {@link collectInstanceItemIds} output.
+ * @returns {Array<object>} The subset that belongs, in the order given.
+ */
+function selectInstanceSkills(skills = [], itemIds = new Set()) {
+  const owned = itemIds instanceof Set ? itemIds : new Set(itemIds);
+  return skills.filter((skill) => skill?.triggerItemId && owned.has(skill.triggerItemId));
+}
+
+/**
+ * Item ids the given skills summon, which need atlases of their own.
+ *
+ * Folded back into the instance's item set after selection, never before: a summoned bullet
+ * is drawn by the world, but it does not make the world own a skill that summons it.
+ *
+ * @param {Array<{skills?: Array<{summonedEntityItemId?: string}>}>} skills
+ * @returns {Set<string>}
+ */
+function collectSummonedItemIds(skills = []) {
+  const itemIds = new Set();
+  for (const skill of skills) {
+    for (const definition of skill?.skills || []) {
+      if (isMaterialItemId(definition?.summonedEntityItemId)) itemIds.add(definition.summonedEntityItemId);
+    }
+  }
+  return itemIds;
+}
+
+export { collectInstanceItemIds, collectSummonedItemIds, isMaterialItemId, selectInstanceSkills };