@underpostnet/cyberia 3.3.73 → 3.3.77

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

@@ -1,22 +1,6 @@
-/**
- * Instance Map service — strategic-graph REST payloads for the client's
- * expanded Instance Map modal.
- *
- * Serves two lightweight views of an instance, decoupled from the gameplay
- * AOI stream:
- *   static  — graph topology plus authored map-cell presence, capability
- *             membership, and baseline stats for living presence (bots and
- *             resources; portals carry none). Fetched once when the modal
- *             opens.
- *   dynamic — per-player capability activity. Polled while the modal is open.
- *
- * Live player position is intentionally absent: engine-cyberia holds no
- * real-time simulation state (see cyberia-docs/ARCHITECTURE.md). The client
- * overlays its own predicted position on the graph.
- *
- * @module src/api/cyberia-instance/cyberia-instance-map.service.js
- */
+// The instance map serves authored topology and capabilities. AOI owns live stats.
 
+import { CyberiaEntityTypeDefaultService } from '../cyberia-entity-type-default/cyberia-entity-type-default.service.js';
 import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
 import { generateFallbackWorld } from './cyberia-fallback-world.js';
 import {
@@ -27,10 +11,10 @@ import {
 import { FileFactory } from '../file/file.service.js';
 import { loggerFactory } from '../../server/ops/logger.js';
 import {
-  CYBERIA_INSTANCE_CONF_DEFAULTS,
   DefaultCyberiaActions,
   DefaultCyberiaQuests,
   ENTITY_TYPE_DEFAULTS,
+  resolveEntityDefaultBuild,
 } from '../cyberia-server-defaults/cyberia-server-defaults.js';
 import { DefaultCyberiaItems } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
 
@@ -78,9 +62,6 @@ const entityPresenceStatus = (entity, objectLayerMetadata, behavior) => {
   }
 };
 
-// Behaviors whose entities never carry the sum-stats readout (mission/action
-// givers and fully static NPCs — mirrors the Go server's behavior semantics).
-const STATLESS_BEHAVIORS = new Set(['provider', 'provider-static', 'static']);
 
 const mergeEntityDefaults = (entityDefaults = []) => {
   const merged = entityDefaults.map((entityDefault) => ({
@@ -101,33 +82,10 @@ const mergeEntityDefaults = (entityDefaults = []) => {
   return merged;
 };
 
-// Mirrors game/entity_defaults.go: the most-specific live-item set wins, then
-// the first build for the entity type supplies the runtime fallback behavior.
-const entityBehavior = (entity, entityDefaults) => {
-  const itemIds = new Set(entity.objectLayerItemIds || []);
-  let firstTypeDefault;
-  let matchedDefault;
-  let matchedSize = 0;
-
-  for (const entityDefault of entityDefaults) {
-    if (entityDefault.entityType !== entity.entityType) continue;
-    if (!firstTypeDefault) firstTypeDefault = entityDefault;
-    const liveItemIds = entityDefault.liveItemIds || [];
-    if (0 === itemIds.size || 0 === liveItemIds.length) continue;
-    if (!liveItemIds.every((itemId) => itemIds.has(itemId))) continue;
-    if (liveItemIds.length > matchedSize) {
-      matchedDefault = entityDefault;
-      matchedSize = liveItemIds.length;
-    }
-  }
-  return (matchedDefault || firstTypeDefault)?.behavior || '';
-};
-
-const objectLayerStatsSum = (itemIds, objectLayerMetadata, sumStatsLimit) =>
-  Math.min(
-    (itemIds || []).reduce((sum, itemId) => sum + (objectLayerMetadata[itemId]?.statsSum || 0), 0),
-    sumStatsLimit,
-  );
+// One resolution rule for the whole platform — see resolveEntityDefaultBuild.
+const entityBehavior = (entity, entityDefaults) =>
+  resolveEntityDefaultBuild({ entityType: entity.entityType, itemIds: entity.objectLayerItemIds }, entityDefaults)
+    ?.behavior || '';
 
 const resolveObjectLayerMetadata = async (itemIds, options) => {
   if (!itemIds.length) return {};
@@ -139,49 +97,28 @@ const resolveObjectLayerMetadata = async (itemIds, options) => {
     return {};
   }
   const objectLayers = await ObjectLayer.find({ 'data.item.id': { $in: itemIds } })
-    .select('data.item.id data.item.type data.stats')
+    .select('data.item.id data.item.type')
     .lean();
   return Object.fromEntries(
     objectLayers.map((layer) => [
       layer.data.item.id,
       {
-        statsSum: Object.values(layer.data.stats || {}).reduce((sum, value) => sum + (Number(value) || 0), 0),
         type: layer.data.item.type,
       },
     ]),
   );
 };
 
-const resolveSumStatsLimit = async (instance, options) => {
-  const fallback = CYBERIA_INSTANCE_CONF_DEFAULTS.sumStatsLimit;
-  let CyberiaInstanceConf;
-  try {
-    CyberiaInstanceConf = DataBaseProviderService.getModel('CyberiaInstanceConf', options);
-  } catch {
-    return fallback;
-  }
-  const conf = await CyberiaInstanceConf.findOne({ instanceCode: instance.code }).select('sumStatsLimit').lean();
-  return Number.isFinite(conf?.sumStatsLimit) && conf.sumStatsLimit > 0 ? conf.sumStatsLimit : fallback;
-};
-
+// Only what this instance references: the conf names its entity-type defaults by _id, so a POI
+// never reads behavior out of another world's wiring.
 const resolveEntityDefaults = async (instance, options) => {
-  let configDefaults = [];
   try {
     const CyberiaInstanceConf = DataBaseProviderService.getModel('CyberiaInstanceConf', options);
     const conf = await CyberiaInstanceConf.findOne({ instanceCode: instance.code }).select('entityDefaults').lean();
-    configDefaults = conf?.entityDefaults || [];
+    return mergeEntityDefaults(await CyberiaEntityTypeDefaultService.resolve(conf?.entityDefaults, options));
   } catch {
-    configDefaults = [];
+    return mergeEntityDefaults();
   }
-
-  try {
-    const CyberiaEntityTypeDefault = DataBaseProviderService.getModel('CyberiaEntityTypeDefault', options);
-    const defaults = await CyberiaEntityTypeDefault.find({}).lean();
-    if (defaults.length > 0) return mergeEntityDefaults(defaults);
-  } catch {
-    // The editable own-model collection is optional for legacy deployments.
-  }
-  return mergeEntityDefaults(configDefaults);
 };
 
 const buildPresencePois = ({
@@ -191,11 +128,10 @@ const buildPresencePois = ({
   actions,
   objectLayerMetadata = {},
   entityDefaults = mergeEntityDefaults(),
-  sumStatsLimit = CYBERIA_INSTANCE_CONF_DEFAULTS.sumStatsLimit,
 }) => {
   const pois = new Map();
 
-  const getPoi = (mapCode, cellX, cellY, presenceStatus, sourcePriority = 0, statsSum = 0, showStatsValue = false) => {
+  const getPoi = (mapCode, cellX, cellY, presenceStatus, sourcePriority = 0) => {
     if (!mapCode || !Number.isFinite(cellX) || !Number.isFinite(cellY) || cellX < 0 || cellY < 0 || !presenceStatus)
       return null;
     const key = `${mapCode}:${cellX}:${cellY}`;
@@ -207,19 +143,7 @@ const buildPresencePois = ({
       presenceStatus,
       capabilities: [],
       sourcePriority,
-      statsSum: 0,
-      hasStatfulPresence: false,
-      hasStatlessPresence: false,
     };
-    if (sourcePriority >= 100) {
-      if (showStatsValue) {
-        poi.hasStatfulPresence = true;
-        poi.statsSum += statsSum;
-      } else {
-        poi.hasStatlessPresence = true;
-        poi.statsSum = 0;
-      }
-    }
     const priority = sourcePriority + (PRESENCE_PRIORITY[presenceStatus] || 0);
     const currentPriority = poi.sourcePriority + (PRESENCE_PRIORITY[poi.presenceStatus] || 0);
     if (priority > currentPriority) {
@@ -239,29 +163,14 @@ const buildPresencePois = ({
       const behavior = entityBehavior(entity, entityDefaults);
       const presenceStatus = entityPresenceStatus(entity, objectLayerMetadata, behavior);
       if (!presenceStatus) continue;
-      // Stats travel only with living presence (bots and resources); portal
-      // cells and provider/static-behavior entities never carry the readout.
-      const statless =
-        presenceStatus === PRESENCE_STATUS.portal ||
-        presenceStatus === PRESENCE_STATUS.portalRandom ||
-        STATLESS_BEHAVIORS.has(behavior);
-      getPoi(
-        map.code,
-        entity.initCellX ?? 0,
-        entity.initCellY ?? 0,
-        presenceStatus,
-        100,
-        statless ? 0 : objectLayerStatsSum(entity.objectLayerItemIds, objectLayerMetadata, sumStatsLimit),
-        !statless,
-      );
+      getPoi(map.code, entity.initCellX ?? 0, entity.initCellY ?? 0, presenceStatus, 100);
     }
   }
 
-  // Portal-cell presence mirrors the AOI: the portal's OWN outgoing edge
-  // decides random vs fixed (priority 200 overrides the authored entity
-  // classification, which may lack the runtime-assigned mode). Fixed-cell
-  // TARGET endpoints only guarantee a plain portal POI — their real mode, if
-  // any, is stamped by their own outgoing edge.
+  // Portal-cell presence follows the AOI: the portal's own outgoing edge
+  // decides random against fixed, and priority 200 beats the authored entity
+  // class. A fixed-cell target endpoint is only a plain portal POI; its own
+  // outgoing edge stamps the mode.
   for (const portal of instance.portals || []) {
     getPoi(
       portal.sourceMapCode,
@@ -283,14 +192,8 @@ const buildPresencePois = ({
     addCapability(poi, CAPABILITY_ACTION);
   }
 
-  // Display permission is explicit: a statless entity must never become a
-  // visible `stats 0` tab due to a numeric fallback or merged POI source.
   return [...pois.values()]
-    .map(({ sourcePriority, hasStatfulPresence, hasStatlessPresence, ...poi }) => ({
-      ...poi,
-      statsSum: hasStatfulPresence && !hasStatlessPresence && poi.capabilities.length === 0 ? poi.statsSum : 0,
-      showStatsValue: hasStatfulPresence && !hasStatlessPresence && poi.capabilities.length === 0,
-    }))
+    .map(({ sourcePriority, ...poi }) => poi)
     .sort(
       (left, right) =>
         left.mapCode.localeCompare(right.mapCode) || left.cellY - right.cellY || left.cellX - right.cellX,
@@ -310,7 +213,6 @@ const buildStaticPayload = ({
   fallback,
   objectLayerMetadata = {},
   entityDefaults = mergeEntityDefaults(),
-  sumStatsLimit = CYBERIA_INSTANCE_CONF_DEFAULTS.sumStatsLimit,
   previewCachedMapCodes = new Set(),
 }) => {
   const previewRoute = (mapCode) =>
@@ -323,11 +225,10 @@ const buildStaticPayload = ({
     gridY: m.gridY,
     // File id of the map's auto-captured Object Layer render (persisted maps).
     preview: m.preview ? String(m.preview) : '',
-    // Ready-to-fetch path of the node background. A captured File is served
-    // directly; otherwise the client hits the preview route, which renders on
-    // demand — and for a persisted map also stores the result as its `preview`
-    // File, so the next payload serves it through the default blob path.
-    // Fallback-world maps only advertise the route once a render succeeded.
+    // Path of the node background. A captured File is served directly. Without
+    // one the client hits the preview route, which renders on demand and, for a
+    // persisted map, stores the result as its `preview` File. A fallback-world
+    // map advertises the route only after a render succeeds.
     previewUrl: m.preview
       ? `/api/file/blob/${String(m.preview)}`
       : fallback
@@ -362,7 +263,6 @@ const buildStaticPayload = ({
       actions,
       objectLayerMetadata,
       entityDefaults,
-      sumStatsLimit,
     }),
   };
 };
@@ -416,10 +316,9 @@ const classifyActionProviders = (actions, questProviders) => {
 
 /**
  * Resolve the content-authority view of an instance: its map nodes plus the
- * quests/actions bound to those maps. Falls back to the in-memory procedural
- * world (and canonical default quests/actions) when the instance is not
- * persisted — mirroring the gRPC getFullInstance fallback that feeds
- * cyberia-server.
+ * quests and actions bound to those maps. An instance that is not persisted
+ * falls back to the procedural world and the default quests/actions, the same
+ * fallback getFullInstance serves to the simulation.
  */
 const resolveInstanceWorld = async (instanceCode, options) => {
   const CyberiaInstance = DataBaseProviderService.getModel('CyberiaInstance', options);
@@ -440,7 +339,7 @@ const resolveInstanceWorld = async (instanceCode, options) => {
     const resolved = await resolveObjectLayerMetadata(fallbackItemIds, options);
     const objectLayerMetadata = Object.fromEntries(
       Object.entries(resolved).map(([itemId, meta]) => {
-        return [itemId, { statsSum: meta.statsSum, type: meta.type }];
+        return [itemId, { type: meta.type }];
       }),
     );
 
@@ -457,11 +356,9 @@ const resolveInstanceWorld = async (instanceCode, options) => {
       actions: DefaultCyberiaActions.filter((a) => mapCodes.has(a.sourceMapCode)),
       objectLayerMetadata,
       entityDefaults: mergeEntityDefaults(),
-      sumStatsLimit: CYBERIA_INSTANCE_CONF_DEFAULTS.sumStatsLimit,
-      // The procedural world never passes through the browser editor, so its
-      // node backgrounds are rendered here and served from the in-memory
-      // preview cache (see instanceMapPreview).
-      previewCachedMapCodes: new Set(await cacheWorldMapPreviews(instanceCode, world.maps)),
+      // The procedural world has no editor pass, so its node backgrounds render
+      // here and are served from the in-memory preview cache.
+      previewCachedMapCodes: new Set(await cacheWorldMapPreviews(instanceCode, world.maps, { options })),
       fallback: true,
     };
   }
@@ -483,20 +380,17 @@ const resolveInstanceWorld = async (instanceCode, options) => {
     ...new Set(maps.flatMap((map) => (map.entities || []).flatMap((entity) => entity.objectLayerItemIds || []))),
   ];
   const objectLayerMetadata = await resolveObjectLayerMetadata(itemIds, options);
-  const sumStatsLimit = await resolveSumStatsLimit(instance, options);
   const entityDefaults = await resolveEntityDefaults(instance, options);
 
   const codeSet = new Set(mapCodes);
   return {
     instance,
     maps,
-    // Empty collections fall back to canonical defaults, matching the quest
-    // getByCode behaviour for unseeded databases.
+    // Empty collections fall back to the canonical defaults, as getByCode does.
     quests: dbQuests.length > 0 ? dbQuests : DefaultCyberiaQuests.filter((q) => codeSet.has(q.sourceMapCode)),
     actions: dbActions.length > 0 ? dbActions : DefaultCyberiaActions.filter((a) => codeSet.has(a.sourceMapCode)),
     objectLayerMetadata,
     entityDefaults,
-    sumStatsLimit,
     fallback: false,
   };
 };
@@ -532,7 +426,7 @@ class CyberiaInstanceMapService {
         if (stored?.data) return stored.data;
       }
 
-      const rendered = await renderMapPreviewPng(map);
+      const rendered = await renderMapPreviewPng(map, { options });
       if (rendered) {
         const file = await new File(FileFactory.create(rendered, `${mapCode}-preview.png`)).save();
         await CyberiaMap.updateOne({ _id: map._id }, { $set: { preview: file._id } });
@@ -543,10 +437,9 @@ class CyberiaInstanceMapService {
 
     let png = getCachedMapPreview(instanceCode, mapCode);
     if (!png) {
-      // Cold cache (first hit, or a restart since the modal last opened):
-      // regenerate the world so the preview exists, then serve it.
+      // Cold cache: regenerate the world so the preview exists, then serve it.
       const { maps } = await resolveInstanceWorld(instanceCode, options);
-      await cacheWorldMapPreviews(instanceCode, maps);
+      await cacheWorldMapPreviews(instanceCode, maps, { options });
       png = getCachedMapPreview(instanceCode, mapCode);
     }
     if (!png) throw new Error(`No cached preview for map "${mapCode}"`);

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

@@ -10,7 +10,7 @@ import { CyberiaInstanceMapService } from './cyberia-instance-map.service.js';
 import { CyberiaInstanceBootService } from './cyberia-instance-boot.service.js';
 
 const CyberiaInstanceController = buildCrudController(CyberiaInstanceService, {
-  // The C client fetches the instance map cross-origin (same as quest metadata).
+  // The game client fetches the instance map cross-origin, as it does quests.
   instanceMapStatic: serviceHandler(CyberiaInstanceMapService.getStatic, { crossOrigin: true, errorStatus: 404 }),
   instanceMapDynamic: serviceHandler(CyberiaInstanceMapService.getDynamic, { crossOrigin: true, errorStatus: 404 }),
   // Node background of a fallback-world map, rendered + cached server-side.
@@ -30,9 +30,6 @@ const CyberiaInstanceController = buildCrudController(CyberiaInstanceService, {
   portalConnect: serviceHandler(CyberiaInstanceService.portalConnect),
   // Moderator/admin-triggered world reload on a running cyberia-server.
   hotReload: serviceHandler(CyberiaInstanceService.hotReload, { errorStatus: 502 }),
-  // Fallback-world default items (volatile) + its own reload trigger.
-  fallbackDefaultItems: serviceHandler(CyberiaInstanceService.fallbackDefaultItems),
-  fallbackHotReload: serviceHandler(CyberiaInstanceService.fallbackHotReload, { errorStatus: 502 }),
   // Boot transport (REST fallback of the gRPC CyberiaDataService).
   bootPing: serviceHandler(CyberiaInstanceBootService.ping),
   bootObjectLayerBatch: serviceHandler(CyberiaInstanceBootService.objectLayerBatch, { errorStatus: 500 }),

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

@@ -68,20 +68,6 @@ const CyberiaInstanceSchema = new Schema(
     // Vertex set of the graph
     cyberiaMapCodes: { type: [String], default: [] },
 
-    // Instance-level object layer item IDs. Each entry binds an item id to the
-    // instance and flags whether it seeds every player's starting inventory
-    // (defaultPlayerInventory → merged into the player entityDefault's
-    // defaultObjectLayers when the world is served to cyberia-server).
-    itemIds: {
-      type: [
-        {
-          id: { type: String, required: true },
-          defaultPlayerInventory: { type: Boolean, default: false },
-        },
-      ],
-      default: [],
-    },
-
     // Directed edge set of the graph
     portals: { type: [PortalEdgeSchema], default: [] },
 

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

@@ -12,9 +12,9 @@ class CyberiaInstanceRouter {
     const router = express.Router();
     // ── Custom actions (must come before generic /:id routes) ──────────────
     // Boot transport — REST fallback of the gRPC CyberiaDataService, consumed
-    // server-to-server by cyberia-server (ENGINE_API_BASE_URL) when the engine
-    // gRPC server (ENGINE_GRPC_ADDRESS) is not enabled. Unauthenticated for
-    // parity with the internal-network insecure gRPC channel.
+    // server-to-server by cyberia-server (its --data-server-url) when the engine
+    // gRPC server is not enabled for the deploy. Unauthenticated for parity with
+    // the internal-network insecure gRPC channel.
     router.get(`/boot/ping`, async (req, res) => await CyberiaInstanceController.bootPing(req, res, options));
     router.get(
       `/boot/object-layers`,
@@ -38,19 +38,6 @@ class CyberiaInstanceRouter {
       async (req, res) => await CyberiaInstanceController.bootFullInstance(req, res, options),
     );
     router.get(`/fallback-world`, async (req, res) => await CyberiaInstanceController.fallbackWorld(req, res, options));
-    // Fallback-world default items — volatile, process-local (never persisted).
-    // The read is open (same as /fallback-world); staging them and triggering a
-    // rebuild is elevated privilege, like every other hot-reload path.
-    router.get(
-      `/fallback-world/default-items`,
-      async (req, res) => await CyberiaInstanceController.fallbackDefaultItems(req, res, options),
-    );
-    router.post(
-      `/fallback-world/hot-reload`,
-      options.authMiddleware,
-      moderatorGuard,
-      async (req, res) => await CyberiaInstanceController.fallbackHotReload(req, res, options),
-    );
     // Instance Map — static topology/presence plus dynamic player capability activity.
     router.get(
       `/instance-map/:instanceCode/static`,

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

@@ -7,8 +7,6 @@ import {
   fallbackListInstance,
   DEFAULT_FALLBACK_INSTANCE_CODE,
 } from './cyberia-fallback-world.js';
-import { getFallbackDefaultItems, setFallbackDefaultItems } from './cyberia-fallback-default-items.js';
-import { CYBERIA_INSTANCE_CONF_DEFAULTS } from '../cyberia-server-defaults/cyberia-server-defaults.js';
 import { triggerHotReload } from '../../projects/cyberia/hot-reload-trigger.js';
 
 const logger = loggerFactory(import.meta);
@@ -45,7 +43,9 @@ class CyberiaInstanceService {
     /** @type {import('./cyberia-instance.model.js').CyberiaInstanceModel} */
     const CyberiaInstance = DataBaseProviderService.getModel('CyberiaInstance', options);
     const populateCreator = { path: 'creator', model: 'User', select: '_id username' };
-    if (req.params.id) return await CyberiaInstance.findById(req.params.id).populate(populateCreator);
+    // Instances are addressed by code, the key the engine navigates by.
+    if (req.params.id)
+      return await CyberiaInstance.findOne(DataQuery.naturalKeyFilter('code', req.params.id)).populate(populateCreator);
 
     // Parse query parameters using DataQuery helper
     const { query, sort, skip, limit, page } = DataQuery.parse(req.query);
@@ -185,49 +185,9 @@ class CyberiaInstanceService {
       botCount: q.botCount ? parseInt(q.botCount, 10) : undefined,
       obstacleCount: q.obstacleCount ? parseInt(q.obstacleCount, 10) : undefined,
       foregroundCount: q.foregroundCount ? parseInt(q.foregroundCount, 10) : undefined,
-      itemIds: getFallbackDefaultItems(),
     });
   };
 
-  /**
-   * Current fallback-world default items — the volatile set the
-   * FallbackWorldEngine view last pushed, or `[]` when the engine is running on
-   * pure code defaults. Lets the view reopen showing what this process serves.
-   *
-   * `entityDefaultItemIds` are the ids the code defaults already ship in an
-   * entity's `defaultObjectLayers`. Selecting one of them and leaving
-   * `defaultPlayerInventory` unchecked REMOVES it (see
-   * applyInstanceDefaultPlayerInventory), so the editor needs to be able to warn
-   * before an operator silently strips the player's starting skin or weapon.
-   */
-  static fallbackDefaultItems = async () => {
-    const entityDefaultItemIds = new Set();
-    for (const entityDefault of CYBERIA_INSTANCE_CONF_DEFAULTS.entityDefaults || []) {
-      for (const layer of entityDefault.defaultObjectLayers || []) {
-        if (layer.itemId) entityDefaultItemIds.add(layer.itemId);
-      }
-    }
-    return { itemIds: getFallbackDefaultItems(), entityDefaultItemIds: [...entityDefaultItemIds].sort() };
-  };
-
-  /**
-   * Stage the fallback world's default items, then ask a running cyberia-server
-   * to rebuild. The items are not persisted (see cyberia-fallback-default-items):
-   * they are staged here first so the rebuild's `getFullInstance` re-fetch picks
-   * them up, which is what makes them reach the server at all.
-   *
-   * `instanceCode` is intentionally left empty — the target world is addressed by
-   * `serverUrl` (origin, or origin + variant sub-path), and naming the synthetic
-   * `fallback` code would be rejected by any server serving a real instance code.
-   */
-  static fallbackHotReload = async (req) => {
-    const { serverUrl, mode, itemIds } = req.body || {};
-    if (!serverUrl) throw new Error('serverUrl is required');
-
-    const staged = setFallbackDefaultItems(itemIds || []);
-    const { transport, result, grpcError } = await triggerHotReload({ serverUrl, instanceCode: '', mode });
-    return { transport, itemIds: staged, grpcError, ...result };
-  };
 }
 
 export { CyberiaInstanceService };

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

@@ -483,7 +483,6 @@ function generateBots(mapDims, colors, opts = {}) {
       cellY = randInt(0, maxY);
     }
 
-    // const skin = BOT_SKIN_POOL[Math.floor(Math.random() * BOT_SKIN_POOL.length)];
     const skin = 'kishins';
     const hasWeapon = nextRandom() < BOT_WEAPON_CHANCE;
     const itemIds = hasWeapon ? [skin, 'atlas_pistol_mk2'] : [skin];
@@ -506,16 +505,13 @@ function generateBots(mapDims, colors, opts = {}) {
 }
 
 /**
- * Action-provider NPC bots — the fixed-position entities that back the
- * default mission system. One passive bot is placed per `CyberiaAction`
- * whose `sourceMapCode` matches `mapCode`, at the action's
- * (`sourceCellX`, `sourceCellY`). The Go server binds each bot back to its
- * action by these coordinates, so the positions here are the single source
- * of truth shared with `DefaultCyberiaActions`.
+ * Action-provider NPC bots, the fixed-position entities behind the mission
+ * system. One passive bot per `CyberiaAction` whose `sourceMapCode` matches
+ * `mapCode`, at the action's (`sourceCellX`, `sourceCellY`). The server binds
+ * a bot to its action by these coordinates.
  *
- * The NPC skin is derived from the action's first `default-<skin>` dialogue
- * code (e.g. `default-wason` → skin `wason`) — there is no separate
- * provideItemId; the bot's own active skin is what 'talk' objectives match.
+ * The NPC skin comes from the action's first `default-<skin>` dialogue code
+ * (`default-wason` → skin `wason`). A 'talk' objective matches that skin.
  *
  * @param {string} mapCode
  * @param {Array<{ key: string, r: number, g: number, b: number, a: number }>} colors
@@ -546,9 +542,8 @@ function generateActionProviderBots(mapCode, colors, opts = {}) {
 
     if (opts.grid) opts.grid.block(cellX, cellY, dim, dim);
 
-    // Passive quest-giver NPC: no aggro, and a small wander radius so it
-    // drifts near its source cell but stays easy to find. The Go server binds
-    // it by its spawn-centre (the initial cell), so the bind survives movement.
+    // Passive quest-giver NPC: no aggro and a small wander radius. The server
+    // binds it by its spawn cell, so the bind survives the drift.
     entities.push({
       entityType: 'bot',
       initCellX: cellX,