@underpostnet/cyberia 3.2.80 → 3.3.0

package/src/api/cyberia-instance/cyberia-random-source.js

@@ -0,0 +1,80 @@
+/**
+ * Swappable random source for procedural world generation.
+ *
+ * The world generator and portal connector draw all randomness through
+ * `nextRandom()` instead of `Math.random()` directly. By default it IS
+ * `Math.random`, so live/editor generation stays random. The fallback world
+ * temporarily installs a seeded PRNG so the SAME layout is produced on every
+ * call — the instance-map `/static` POIs and the `/preview` image are built by
+ * independent HTTP requests (and survive server restarts), so they must agree
+ * on where every entity sits.
+ *
+ * @module src/api/cyberia-instance/cyberia-random-source.js
+ */
+
+let source = Math.random;
+
+/** Draw the next float in [0, 1). Routes through the installed source. */
+const nextRandom = () => source();
+
+/**
+ * mulberry32 — a small, fast, well-distributed seeded PRNG. Deterministic:
+ * the same seed always yields the same sequence.
+ * @param {number} seed 32-bit unsigned integer
+ * @returns {() => number}
+ */
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function () {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Derive a stable 32-bit seed from a string (FNV-1a). */
+function hashSeed(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < String(str).length; i++) {
+    h ^= String(str).charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+/**
+ * Install a deterministic seeded source. Accepts a number or a string
+ * (hashed to a 32-bit seed). Call `resetRandomSource()` to restore Math.random.
+ * @param {number|string} seed
+ */
+function seedRandomSource(seed) {
+  const s = typeof seed === 'number' ? seed >>> 0 : hashSeed(seed);
+  source = mulberry32(s);
+}
+
+/** Restore the default `Math.random` source. */
+function resetRandomSource() {
+  source = Math.random;
+}
+
+/**
+ * Run `fn` with a deterministic seeded source, restoring the previous source
+ * afterward even if `fn` throws. Returns `fn`'s result.
+ * @template T
+ * @param {number|string} seed
+ * @param {() => T} fn
+ * @returns {T}
+ */
+function withSeededRandom(seed, fn) {
+  const prev = source;
+  seedRandomSource(seed);
+  try {
+    return fn();
+  } finally {
+    source = prev;
+  }
+}
+
+export { nextRandom, seedRandomSource, resetRandomSource, withSeededRandom, hashSeed };

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

@@ -23,6 +23,7 @@ import {
 } from '../cyberia-server-defaults/cyberia-server-defaults.js';
 
 import { DefaultCyberiaItems, ITEM_TYPES } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
+import { nextRandom } from './cyberia-random-source.js';
 
 import { PORTAL_MODES, PORTAL_MODE_COLOR_KEY, EXTRA_PORTAL_MODES } from './cyberia-portal-connector.js';
 
@@ -51,7 +52,7 @@ const findColor = (colors, key) => colors.find((c) => c.key === key);
  * @param {number} max
  * @returns {number}
  */
-const randInt = (min, max) => min + Math.floor(Math.random() * (max - min + 1));
+const randInt = (min, max) => min + Math.floor(nextRandom() * (max - min + 1));
 
 // ── Entity count ranges ──────────────────────────────────────────────────────
 // [min, max] — actual count is random within range on each generation call.
@@ -438,7 +439,7 @@ function generatePortalEntities(mapDims, colors, opts = {}) {
     // 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)];
+      i === 0 ? PORTAL_MODES.INTER_PORTAL : EXTRA_PORTAL_MODES[Math.floor(nextRandom() * EXTRA_PORTAL_MODES.length)];
     const portal = generatePortalEntity(mapDims, colors, opts.grid, subtype);
     if (portal) entities.push(portal);
   }
@@ -484,7 +485,7 @@ function generateBots(mapDims, colors, opts = {}) {
 
     // const skin = BOT_SKIN_POOL[Math.floor(Math.random() * BOT_SKIN_POOL.length)];
     const skin = 'kishins';
-    const hasWeapon = Math.random() < BOT_WEAPON_CHANCE;
+    const hasWeapon = nextRandom() < BOT_WEAPON_CHANCE;
     const itemIds = hasWeapon ? [skin, 'atlas_pistol_mk2'] : [skin];
 
     entities.push({

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

@@ -148,6 +148,7 @@ const CyberiaInstanceConfSchema = new Schema(
     // ── Player defaults ──────────────────────────────────────────────
     defaultPlayerWidth: { type: Number, default: D.defaultPlayerWidth },
     defaultPlayerHeight: { type: Number, default: D.defaultPlayerHeight },
+    playerBaseSpeed: { type: Number, default: D.playerBaseSpeed },
     playerBaseLifeRegenMin: { type: Number, default: D.playerBaseLifeRegenMin },
     playerBaseLifeRegenMax: { type: Number, default: D.playerBaseLifeRegenMax },
     sumStatsLimit: { type: Number, default: D.sumStatsLimit },

package/src/api/cyberia-server-defaults/cyberia-server-defaults.js

@@ -591,6 +591,76 @@ export const DefaultCyberiaActions = [
     dialogCode: 'default-agent',
     questDialogueCodes: [{ questCode: 'bounty-quest-alpha', dialogCode: 'quest-talk-agent' }],
   },
+  {
+    // Shop capability: an action carrying shopItems is a vendor. The client
+    // surfaces a Shop tab for it and the simulation validates every purchase
+    // against this catalog (price item + quantity).
+    code: 'loc-fallback-map-0-18-16',
+    label: 'Punk',
+    sourceMapCode: 'fallback-map-0',
+    sourceCellX: 18,
+    sourceCellY: 16,
+    dialogCode: 'default-punk',
+    shopItems: [{ itemId: 'tim-knife', priceItemId: 'coin', priceQty: 10 }],
+  },
+  {
+    // Assembler capability: an action carrying craftRecipes is a fabrication
+    // terminal. The client surfaces an Assembly tab for it and the simulation
+    // validates every synthesis against these recipes (ingredients → outputs).
+    // Every id here is obtainable inside the fallback world — wood from the
+    // resource nodes, coin from field drops — so the loop is playable on a
+    // fresh spawn with no seeding.
+    code: 'loc-fallback-map-0-15-16',
+    label: 'Eiri',
+    sourceMapCode: 'fallback-map-0',
+    sourceCellX: 15,
+    sourceCellY: 16,
+    dialogCode: 'default-eiri',
+    craftRecipes: [
+      {
+        outputItems: [{ itemId: 'hatchet', qty: 1 }],
+        ingredients: [
+          { itemId: 'wood-drop-1', qty: 2 },
+          { itemId: 'coin', qty: 5 },
+        ],
+        craftTimeMs: 3000,
+      },
+      {
+        outputItems: [{ itemId: 'tim-knife', qty: 1 }],
+        ingredients: [
+          { itemId: 'wood-drop-2', qty: 1 },
+          { itemId: 'wood-drop-1', qty: 1 },
+          { itemId: 'coin', qty: 10 },
+        ],
+        craftTimeMs: 5000,
+      },
+      {
+        // Multi-output: one blade breaks down into three component stacks, so
+        // the assembly UI and the arrival flights are exercised with more than
+        // a single result slot. Closes the loop with Punk's shop — buy a knife,
+        // salvage it back into parts.
+        outputItems: [
+          { itemId: 'wood-drop-1', qty: 2 },
+          { itemId: 'wood-drop-2', qty: 1 },
+          { itemId: 'coin', qty: 5 },
+        ],
+        ingredients: [{ itemId: 'tim-knife', qty: 1 }],
+        craftTimeMs: 2000,
+      },
+    ],
+  },
+  {
+    // Storage capability: an action carrying storageSlots is a personal vault.
+    // The client surfaces a Storage tab whose square grid is sized from the
+    // capacity (25 → 5x5) and the simulation owns the contents.
+    code: 'loc-fallback-map-0-12-22',
+    label: 'Kaneki',
+    sourceMapCode: 'fallback-map-0',
+    sourceCellX: 12,
+    sourceCellY: 22,
+    dialogCode: 'default-kaneki',
+    storageSlots: 25,
+  },
   {
     code: 'loc-fallback-map-0-15-22',
     label: 'Lain',
@@ -839,7 +909,6 @@ export const ENTITY_TYPE_DEFAULTS = Object.freeze([
       { itemId: 'anon', active: true, quantity: 1 },
       { itemId: 'atlas_pistol_mk2', active: true, quantity: 1 },
       { itemId: 'coin', active: false, quantity: 0 },
-      { itemId: 'eiri', active: false, quantity: 1 },
     ],
   },
   {
@@ -868,6 +937,19 @@ export const ENTITY_TYPE_DEFAULTS = Object.freeze([
   { entityType: ENTITY_TYPES.bot, liveItemIds: ['wason'], deadItemIds: [DEFAULT_DEAD_ITEM_ID], behavior: 'provider' },
   { entityType: ENTITY_TYPES.bot, liveItemIds: ['alex'], deadItemIds: [DEFAULT_DEAD_ITEM_ID], behavior: 'provider' },
   { entityType: ENTITY_TYPES.bot, liveItemIds: ['agent'], deadItemIds: [DEFAULT_DEAD_ITEM_ID], behavior: 'provider' },
+  { entityType: ENTITY_TYPES.bot, liveItemIds: ['punk'], deadItemIds: [DEFAULT_DEAD_ITEM_ID], behavior: 'provider' },
+  {
+    entityType: ENTITY_TYPES.bot,
+    liveItemIds: ['eiri'],
+    deadItemIds: [DEFAULT_DEAD_ITEM_ID],
+    behavior: 'provider-static',
+  },
+  {
+    entityType: ENTITY_TYPES.bot,
+    liveItemIds: ['kaneki'],
+    deadItemIds: [DEFAULT_DEAD_ITEM_ID],
+    behavior: 'provider-static',
+  },
   {
     entityType: ENTITY_TYPES.bot,
     liveItemIds: ['lain'],
@@ -954,6 +1036,10 @@ export const CYBERIA_INSTANCE_CONF_DEFAULTS = {
   defaultPlayerHeight: 2,
   playerBaseLifeRegenMin: 0.5,
   playerBaseLifeRegenMax: 1.5,
+  // Movement speed for the player entity only, in grid cells per second. Bots,
+  // projectiles and every other entity keep entityBaseSpeed. 0 falls back to
+  // entityBaseSpeed.
+  playerBaseSpeed: 8,
   sumStatsLimit: 500,
   maxActiveLayers: 4,
   initialLifeFraction: 1.0,

package/src/api/object-layer/object-layer.model.js

@@ -3,6 +3,8 @@
  * @module src/api/object-layer/object-layer.model.js
  * @namespace CyberiaObjectLayerModel
  */
+import crypto from 'crypto';
+import stringify from 'fast-json-stable-stringify';
 import { Schema, model } from 'mongoose';
 /**
  * @typedef {Object} Stats
@@ -132,8 +134,19 @@ const ObjectLayerSchema = new Schema(
     toObject: { virtuals: true },
   },
 );
-// Index for faster querying
-ObjectLayerSchema.index({ 'data.item.id': 1 });
+/**
+ * Name of the `data.item.id` index. Kept stable across the non-unique → unique
+ * upgrade so {@link ObjectLayerModel.ensureUniqueItemIdIndex} can detect and
+ * replace the legacy definition instead of leaving two overlapping indexes.
+ * @memberof CyberiaObjectLayerModel
+ */
+const ITEM_ID_INDEX_NAME = 'data.item.id_1';
+// `data.item.id` is the natural key: exactly one document per item id.
+// autoIndex runs at model-compile time, so on a collection that still holds
+// legacy duplicates (or a legacy non-unique index) this build fails and is
+// logged by the model's `error` listener. ensureUniqueItemIdIndex() then
+// dedupes and rebuilds it, after which autoIndex agrees and stays quiet.
+ObjectLayerSchema.index({ 'data.item.id': 1 }, { name: ITEM_ID_INDEX_NAME, unique: true });
 ObjectLayerSchema.index({ 'data.item.type': 1 });
 // Add text index for searchable fields
 ObjectLayerSchema.index(
@@ -158,6 +171,186 @@ ObjectLayerSchema.pre('save', function () {
   }
   // cid (object layer data JSON) and data.render.cid (atlas PNG) are optional – default to ''
 });
+
+/**
+ * Computes the canonical SHA-256 of an object layer `data` sub-document using
+ * deterministic JSON serialisation. Single source of truth for the hash;
+ * `ObjectLayerEngine.computeSha256` delegates here.
+ *
+ * @param {Object} data - The `data` sub-document (item, stats, ledger, render).
+ * @returns {string} Hex-encoded SHA-256 hash.
+ * @memberof CyberiaObjectLayerModel
+ */
+const computeObjectLayerSha256 = (data) => crypto.createHash('sha256').update(stringify(data)).digest('hex');
+
+const isMergeableObject = (value) => {
+  if (value === null || typeof value !== 'object') return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+};
+
+/**
+ * An incoming attribute only wins when it actually carries a value. `null`,
+ * `undefined` and `''` mean "not provided by this writer" — importers emit them
+ * whenever a stage is skipped or degraded (IPFS unreachable, atlas not
+ * generated, saga metadata with no render yet), and they must never erase a
+ * value another writer already persisted. `false` and `0` are real values.
+ *
+ * @param {*} value - Candidate attribute value.
+ * @returns {boolean} Whether the value should override the stored one.
+ * @memberof CyberiaObjectLayerModel
+ */
+const hasValue = (value) => value !== null && value !== undefined && value !== '';
+
+/**
+ * Deep-merges `incoming` over `existing`, keeping the last attribute that
+ * actually carries a value. Plain objects merge key by key; every other value
+ * (scalars, arrays, ObjectIds, Dates, Buffers) is replaced atomically.
+ *
+ * @param {*} existing - Currently persisted value.
+ * @param {*} incoming - Value received from the writer.
+ * @returns {*} The merged value.
+ * @memberof CyberiaObjectLayerModel
+ */
+function mergeObjectLayerData(existing, incoming) {
+  if (isMergeableObject(incoming)) {
+    if (!isMergeableObject(existing)) return incoming;
+    const merged = { ...existing };
+    for (const key of Object.keys(incoming)) merged[key] = mergeObjectLayerData(existing[key], incoming[key]);
+    return merged;
+  }
+  return hasValue(incoming) ? incoming : existing;
+}
+
+/**
+ * Document fields an upsert may carry. `sha256` is excluded on purpose: it is
+ * always recomputed from the merged `data`, so it can never drift from the
+ * payload the writer hashed before merging.
+ * @memberof CyberiaObjectLayerModel
+ */
+const UPSERTABLE_FIELDS = ['data', 'cid', 'objectLayerRenderFramesId', 'atlasSpriteSheetId'];
+
+/**
+ * Collapses any pre-existing duplicates of a given `data.item.id` down to a
+ * single document, keeping the oldest one so `_id` references held elsewhere
+ * (instances, inventories, atlas metadata) stay valid.
+ *
+ * @param {import('mongoose').Model} Model - The bound ObjectLayer model.
+ * @param {string} itemId - The item id to collapse.
+ * @returns {Promise<{ survivor: Object|null, removedIds: Array }>} Survivor and removed document ids.
+ * @memberof CyberiaObjectLayerModel
+ */
+async function collapseItemIdDuplicates(Model, itemId) {
+  const [survivor, ...duplicates] = await Model.find({ 'data.item.id': itemId }).sort({ createdAt: 1, _id: 1 });
+  if (!survivor || duplicates.length === 0) return { survivor: survivor || null, removedIds: [] };
+
+  const removedIds = duplicates.map((duplicate) => duplicate._id);
+  await Model.deleteMany({ _id: { $in: removedIds } });
+
+  // Orphaned render frames have no other cleanup path once their owner is gone.
+  const renderFramesIds = duplicates.map((duplicate) => duplicate.objectLayerRenderFramesId).filter(Boolean);
+  if (renderFramesIds.length > 0 && Model.db.models.ObjectLayerRenderFrames) {
+    await Model.db.models.ObjectLayerRenderFrames.deleteMany({ _id: { $in: renderFramesIds } });
+  }
+
+  return { survivor, removedIds };
+}
+
+/**
+ * Resolves the canonical document for an item id. While a legacy collection can
+ * still hold duplicates, an unsorted `findOne` may hand back a document that the
+ * next upsert collapses away, so readers and writers must agree on the same
+ * survivor: the oldest one.
+ *
+ * @param {string} itemId - The `data.item.id` to look up.
+ * @returns {import('mongoose').Query} Query resolving to the canonical document or `null`.
+ * @memberof CyberiaObjectLayerModel
+ */
+ObjectLayerSchema.statics.findByItemId = function (itemId) {
+  return this.findOne({ 'data.item.id': itemId }).sort({ createdAt: 1, _id: 1 });
+};
+
+/**
+ * Dedupes the whole collection by `data.item.id`.
+ *
+ * @returns {Promise<Array>} Ids of the removed duplicate documents.
+ * @memberof CyberiaObjectLayerModel
+ */
+ObjectLayerSchema.statics.dedupeByItemId = async function () {
+  const duplicated = await this.aggregate([
+    { $group: { _id: '$data.item.id', count: { $sum: 1 } } },
+    { $match: { count: { $gt: 1 } } },
+  ]);
+  const removedIds = [];
+  for (const { _id: itemId } of duplicated) {
+    if (itemId === null || itemId === undefined) continue;
+    const { removedIds: removed } = await collapseItemIdDuplicates(this, itemId);
+    removedIds.push(...removed);
+  }
+  return removedIds;
+};
+
+/**
+ * Idempotent migration that enforces the one-document-per-`data.item.id`
+ * invariant at the storage layer: dedupes first, then upgrades the legacy
+ * non-unique index to a unique one. Safe to rerun; a no-op once applied.
+ *
+ * @returns {Promise<{ removedIds: Array, indexUpgraded: boolean }>} Migration outcome.
+ * @memberof CyberiaObjectLayerModel
+ */
+ObjectLayerSchema.statics.ensureUniqueItemIdIndex = async function () {
+  const removedIds = await this.dedupeByItemId();
+
+  const indexes = await this.collection.indexes().catch(() => []);
+  const current = indexes.find((index) => index.name === ITEM_ID_INDEX_NAME);
+  if (current?.unique) return { removedIds, indexUpgraded: false };
+
+  if (current) await this.collection.dropIndex(ITEM_ID_INDEX_NAME);
+  await this.collection.createIndex({ 'data.item.id': 1 }, { name: ITEM_ID_INDEX_NAME, unique: true });
+  return { removedIds, indexUpgraded: true };
+};
+
+/**
+ * The single write path for object layers keyed by item id.
+ *
+ * Guarantees that exactly one document exists per `data.item.id`: pre-existing
+ * duplicates are collapsed onto the oldest document, which is then updated in
+ * place. Attributes are merged with {@link mergeObjectLayerData}, so a writer
+ * that omits a value (or sends `null` / `''` because a stage was skipped) keeps
+ * whatever a previous writer stored instead of erasing it. `sha256` is always
+ * recomputed from the merged result.
+ *
+ * @param {Object} payload - Document payload; `data.item.id` is required.
+ * @param {Object} payload.data - Object layer data (item, stats, ledger, render).
+ * @param {Object} [options] - Upsert options.
+ * @param {Object} [options.setOnInsert=null] - Partial document applied only when the item is new,
+ *   for fields a writer wants to seed but never refresh (mirrors Mongo's `$setOnInsert`).
+ * @returns {Promise<Object>} The single surviving ObjectLayer document.
+ * @memberof CyberiaObjectLayerModel
+ */
+ObjectLayerSchema.statics.upsertByItemId = async function (payload, { setOnInsert = null } = {}) {
+  const itemId = payload?.data?.item?.id;
+  if (!itemId) throw new Error('ObjectLayer.upsertByItemId requires data.item.id');
+
+  const { survivor } = await collapseItemIdDuplicates(this, itemId);
+
+  if (!survivor) {
+    const inserted = setOnInsert ? mergeObjectLayerData(setOnInsert, payload) : payload;
+    return await this.create({ ...inserted, sha256: computeObjectLayerSha256(inserted.data) });
+  }
+
+  const existing = survivor.toObject({ virtuals: false, depopulate: true });
+  const update = {};
+  for (const field of UPSERTABLE_FIELDS) {
+    if (!(field in payload)) continue;
+    const merged = mergeObjectLayerData(existing[field], payload[field]);
+    if (merged !== undefined) update[field] = merged;
+  }
+  update.sha256 = computeObjectLayerSha256(update.data ?? existing.data);
+
+  return await this.findByIdAndUpdate(survivor._id, { $set: update }, { returnDocument: 'after' });
+};
+
 // Create and export the model
 const ObjectLayerModel = model('ObjectLayer', ObjectLayerSchema);
 const ProviderSchema = ObjectLayerSchema;
@@ -197,4 +390,12 @@ class ObjectLayerDto {
     },
   };
 }
-export { ObjectLayerSchema, ObjectLayerModel, ProviderSchema, ObjectLayerDto };
+export {
+  ObjectLayerSchema,
+  ObjectLayerModel,
+  ProviderSchema,
+  ObjectLayerDto,
+  computeObjectLayerSha256,
+  mergeObjectLayerData,
+  ITEM_ID_INDEX_NAME,
+};

package/src/api/object-layer/object-layer.service.js

@@ -215,9 +215,6 @@ class ObjectLayerService {
       }
     }
 
-    // Compute final SHA-256 with all CIDs
-    bodyData.sha256 = ObjectLayerEngine.computeSha256(bodyData.data);
-
     // Pin data JSON to IPFS
     try {
       const itemId = bodyData.data.item.id;
@@ -232,17 +229,7 @@ class ObjectLayerService {
     }
 
     // Atomic create/replace – ObjectLayer is fully populated with all CIDs
-    let newObjectLayer;
-    const existingByItemId = await ObjectLayer.findOne({ 'data.item.id': bodyData.data.item.id });
-    if (existingByItemId) {
-      newObjectLayer = await ObjectLayer.findByIdAndUpdate(existingByItemId._id, bodyData, {
-        returnDocument: 'after',
-      }).populate('objectLayerRenderFramesId');
-    } else {
-      newObjectLayer = await (await new ObjectLayer(bodyData).save()).populate('objectLayerRenderFramesId');
-    }
-
-    return newObjectLayer;
+    return await (await ObjectLayer.upsertByItemId(bodyData)).populate('objectLayerRenderFramesId');
   };
 
   /**

package/src/cli/baremetal.js

@@ -5,9 +5,8 @@
  */
 
 import { fileURLToPath } from 'url';
-import { getNpmRootPath, getUnderpostRootPath } from '../server/conf.js';
+import { getNpmRootPath } from '../server/environment.js';
 import { pbcopy, shellExec } from '../server/process.js';
-import dotenv from 'dotenv';
 import { loggerFactory, loggerMiddleware } from '../server/logger.js';
 import fs from 'fs-extra';
 import path from 'path';

package/src/cli/cloud-init.js

@@ -8,7 +8,7 @@
 import { shellExec } from '../server/process.js';
 import fs from 'fs-extra';
 import { loggerFactory } from '../server/logger.js';
-import { getNpmRootPath } from '../server/conf.js';
+import { getNpmRootPath } from '../server/environment.js';
 import Underpost from '../index.js';
 
 const logger = loggerFactory(import.meta);