@underpostnet/cyberia 3.2.80

package/src/api/cyberia-entity-type-default/cyberia-entity-type-default.model.js

@@ -0,0 +1,67 @@
+import { Schema, model } from 'mongoose';
+
+// https://mongoosejs.com/docs/2.7.x/docs/schematypes.html
+
+// CyberiaEntityTypeDefault — DB-backed, editable mirror of the per-entity-type
+// item defaults that ship in cyberia-server-defaults.js (ENTITY_TYPE_DEFAULTS).
+// A document binds an entity category (entityType) to the item ids the runtime
+// rotates through by lifecycle state:
+//   liveItemIds          — ObjectLayer item ids while the entity is alive.
+//   deadItemIds          — ids swapped in on death / ghost state.
+//   dropItemIds          — ids granted to the killer on depletion (resources).
+//   defaultObjectLayers  — seed inventory rows ({ itemId, active, quantity }).
+//
+// Resolution rule (authoritative): defaults are looked up by the entity's ACTIVE
+// itemId (usually the skin) — the system finds the document whose `liveItemIds`
+// contains that itemId, then applies the document's deadItemIds / dropItemIds /
+// defaultObjectLayers to drive what is shown as the entity's state changes.
+//
+// Resolution (subset matching): a document matches an entity when ALL of its
+// `liveItemIds` are present in the entity's active item ids, and the MOST SPECIFIC
+// match wins — the document requiring the largest item set. This lets the same
+// skin map to different defaults by its full active set, e.g.
+//   { bot, liveItemIds:[purple, atlas_pistol_mk2], behavior:hostile }
+//   { bot, liveItemIds:[purple],                    behavior:passive }
+// where a purple bot carrying the pistol is hostile and a bare purple bot is
+// passive. The Go simulation (game/entity_defaults.go) implements the same rule.
+//
+// Invariants:
+//   - `entityType` is a label, not a unique key — a category appears in many
+//     documents.
+//   - There is NO per-itemId uniqueness: the same itemId may appear in the
+//     `liveItemIds` of many documents (different entity types, or the same type
+//     at different specificity levels). `liveItemIds` is indexed (non-unique
+//     multikey) only for fast membership lookups.
+
+const ObjectLayerDefaultSchema = new Schema(
+  {
+    itemId: { type: String, required: true, trim: true },
+    active: { type: Boolean, default: false },
+    quantity: { type: Number, default: 0 },
+  },
+  { _id: false },
+);
+
+const CyberiaEntityTypeDefaultSchema = new Schema(
+  {
+    entityType: { type: String, required: true, trim: true },
+    liveItemIds: { type: [{ type: String, trim: true }], index: true },
+    deadItemIds: [{ type: String, trim: true }],
+    dropItemIds: [{ type: String, trim: true }],
+    defaultObjectLayers: [ObjectLayerDefaultSchema],
+    // Canonical entity behavior bound to entities matched by liveItemIds (see
+    // SharedDefaultsCyberia.ENTITY_BEHAVIORS). Empty = let the runtime derive it
+    // (armed → hostile, else passive). The Go simulation resolves this with the
+    // same liveItemIds matching used for the live/dead/drop sets.
+    behavior: { type: String, trim: true },
+  },
+  {
+    timestamps: true,
+  },
+);
+
+const CyberiaEntityTypeDefaultModel = model('CyberiaEntityTypeDefault', CyberiaEntityTypeDefaultSchema);
+
+const ProviderSchema = CyberiaEntityTypeDefaultSchema;
+
+export { CyberiaEntityTypeDefaultSchema, CyberiaEntityTypeDefaultModel, ProviderSchema };

package/src/api/cyberia-entity-type-default/cyberia-entity-type-default.router.js

@@ -0,0 +1,17 @@
+import express from 'express';
+import { registerCrudRoutes } from '../../server/middlewares.js';
+import { CyberiaEntityTypeDefaultController } from './cyberia-entity-type-default.controller.js';
+
+class CyberiaEntityTypeDefaultRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    return registerCrudRoutes(express.Router(), CyberiaEntityTypeDefaultController, options);
+  }
+}
+
+const ApiRouter = (options) => CyberiaEntityTypeDefaultRouter.router(options);
+
+export { ApiRouter, CyberiaEntityTypeDefaultRouter };

package/src/api/cyberia-entity-type-default/cyberia-entity-type-default.service.js

@@ -0,0 +1,46 @@
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
+import { loggerFactory } from '../../server/logger.js';
+import { DataQuery } from '../../server/data-query.js';
+
+const logger = loggerFactory(import.meta);
+
+class CyberiaEntityTypeDefaultService {
+  // No per-itemId uniqueness: resolution is by subset containment (most-specific
+  // match wins), so the same itemId may appear in many documents — e.g.
+  // [purple, atlas_pistol_mk2]→hostile alongside [purple]→passive. See the model.
+
+  static post = async (req, res, options) => {
+    /** @type {import('./cyberia-entity-type-default.model.js').CyberiaEntityTypeDefaultModel} */
+    const CyberiaEntityTypeDefault = DataBaseProviderService.getModel('CyberiaEntityTypeDefault', options);
+    return await new CyberiaEntityTypeDefault(req.body).save();
+  };
+  static get = async (req, res, options) => {
+    /** @type {import('./cyberia-entity-type-default.model.js').CyberiaEntityTypeDefaultModel} */
+    const CyberiaEntityTypeDefault = DataBaseProviderService.getModel('CyberiaEntityTypeDefault', options);
+    if (req.params.id) return await CyberiaEntityTypeDefault.findById(req.params.id);
+
+    // Parse query parameters using DataQuery helper
+    const { query, sort, skip, limit, page } = DataQuery.parse(req.query);
+
+    const [data, total] = await Promise.all([
+      CyberiaEntityTypeDefault.find(query).sort(sort).limit(limit).skip(skip),
+      CyberiaEntityTypeDefault.countDocuments(query),
+    ]);
+
+    const totalPages = Math.ceil(total / limit);
+    return { data, total, page, totalPages };
+  };
+  static put = async (req, res, options) => {
+    /** @type {import('./cyberia-entity-type-default.model.js').CyberiaEntityTypeDefaultModel} */
+    const CyberiaEntityTypeDefault = DataBaseProviderService.getModel('CyberiaEntityTypeDefault', options);
+    return await CyberiaEntityTypeDefault.findByIdAndUpdate(req.params.id, req.body);
+  };
+  static delete = async (req, res, options) => {
+    /** @type {import('./cyberia-entity-type-default.model.js').CyberiaEntityTypeDefaultModel} */
+    const CyberiaEntityTypeDefault = DataBaseProviderService.getModel('CyberiaEntityTypeDefault', options);
+    if (req.params.id) return await CyberiaEntityTypeDefault.findByIdAndDelete(req.params.id);
+    else return await CyberiaEntityTypeDefault.deleteMany();
+  };
+}
+
+export { CyberiaEntityTypeDefaultService };

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

@@ -0,0 +1,337 @@
+/**
+ * Fallback World Generator — pure-function module.
+ *
+ * Produces a complete in-memory multi-map world with portal topology,
+ * floor tiles, obstacles, foreground, and bots.  Nothing is persisted
+ * to MongoDB — the result is regenerated on every call.
+ *
+ * Everything that can be random IS random (counts within ranges,
+ * positions, dimensions).  The floor is the exception: it deterministically
+ * covers the entire map grid so there are no gaps.
+ *
+ * Shared by:
+ *   - gRPC server (getFullInstance fallback path)
+ *   - CyberiaInstanceService (API / GUI fallback endpoint)
+ *
+ * All exported functions are stateless and synchronous.
+ *
+ * @module src/api/cyberia-instance/cyberia-fallback-world
+ */
+
+import { connectPortals } from './cyberia-portal-connector.js';
+
+import {
+  generateObstacles,
+  generateForeground,
+  generateResources,
+  generateStatic,
+  generateFloorEntities,
+  generatePortalEntity,
+  generatePortalEntities,
+  generateBots,
+  generateActionProviderBots,
+  OccupancyGrid,
+} from './cyberia-world-generator.js';
+
+import {
+  CYBERIA_INSTANCE_CONF_DEFAULTS,
+  DEFAULT_PLAYER_SPAWN,
+  ENTITY_TYPE_DEFAULTS,
+  RESOURCE_ENTITY_TYPE_DEFAULTS,
+  DefaultSkillConfig,
+} from '../cyberia-server-defaults/cyberia-server-defaults.js';
+import {
+  CYBERIA_CLIENT_HINTS_DEFAULTS,
+  DefaultCyberiaItems,
+  PALETTE,
+} from '../../client/components/cyberia/SharedDefaultsCyberia.js';
+
+// ── Defaults ─────────────────────────────────────────────────────────────────
+
+const DEFAULT_MAP_COUNT = 4;
+const DEFAULT_GRID_SIZE = 64;
+
+// ── Asset-id integrity ──────────────────────────────────────────────────────
+//
+// Every item id that the fallback world can place on a map must also be
+// present in DefaultCyberiaItems, otherwise the `import-default-items` seed
+// will not create an ObjectLayer for it and the runtime client will fall
+// back to a solid-colour rectangle instead of the intended sprite.
+//
+// auditFallbackItemIds() returns the set of unknown ids encountered in the
+// canonical defaults so callers (CLI, test harness, gRPC fallback path)
+// can surface drift immediately. Returns an empty array when in sync.
+
+const KNOWN_DEFAULT_ITEM_IDS = new Set(DefaultCyberiaItems.map((e) => e.item.id));
+
+function collectReferencedItemIds() {
+  const ids = new Set();
+  const push = (id) => {
+    if (typeof id === 'string' && id.length > 0) ids.add(id);
+  };
+
+  for (const e of ENTITY_TYPE_DEFAULTS) {
+    (e.liveItemIds || []).forEach(push);
+    (e.deadItemIds || []).forEach(push);
+    (e.dropItemIds || []).forEach(push);
+    (e.defaultObjectLayers || []).forEach((ol) => push(ol.itemId));
+  }
+  for (const r of RESOURCE_ENTITY_TYPE_DEFAULTS) {
+    (r.liveItemIds || []).forEach(push);
+    (r.deadItemIds || []).forEach(push);
+    (r.dropItemIds || []).forEach(push);
+  }
+  // Skill trigger items and the entities they summon must also resolve to an
+  // ObjectLayer. Runtime placeholders ('$active_skin', …) are resolved by the
+  // server and are intentionally excluded.
+  for (const sk of DefaultSkillConfig) {
+    push(sk.triggerItemId);
+    for (const s of sk.skills || []) {
+      if (typeof s.summonedEntityItemId === 'string' && !s.summonedEntityItemId.startsWith('$')) {
+        push(s.summonedEntityItemId);
+      }
+    }
+  }
+  return ids;
+}
+
+/**
+ * Audit every item id the fallback world can place against the canonical
+ * DefaultCyberiaItems registry.  Returns an array of missing ids; an empty
+ * array means the registry is in sync.
+ *
+ * @returns {string[]}
+ */
+function auditFallbackItemIds() {
+  const referenced = collectReferencedItemIds();
+  const missing = [];
+  for (const id of referenced) {
+    if (!KNOWN_DEFAULT_ITEM_IDS.has(id)) missing.push(id);
+  }
+  return missing.sort();
+}
+
+// ── Single map generator ─────────────────────────────────────────────────────
+
+/** AABB overlap test for two entities in cell space. */
+function entitiesOverlap(a, b) {
+  return (
+    a.initCellX < b.initCellX + b.dimX &&
+    a.initCellX + a.dimX > b.initCellX &&
+    a.initCellY < b.initCellY + b.dimY &&
+    a.initCellY + a.dimY > b.initCellY
+  );
+}
+
+/**
+ * Generate a complete in-memory map with all entity types.
+ * Everything except floor tiles is randomized.
+ *
+ * @param {string} mapCode
+ * @param {Array} colors             Palette (PALETTE from SharedDefaultsCyberia).
+ * @param {object} [opts]
+ * @param {number} [opts.gridSize]
+ * @param {number} [opts.obstacleCount]
+ * @param {number} [opts.foregroundCount]
+ * @param {number} [opts.botCount]
+ * @param {number} [opts.resourceCount]
+ * @param {number} [opts.staticCount]
+ * @returns {object}  CyberiaMap-shaped plain object.
+ */
+function generateFallbackMap(mapCode, colors, opts = {}) {
+  const gridSize = opts.gridSize || DEFAULT_GRID_SIZE;
+  const mapDims = { gridX: gridSize, gridY: gridSize };
+
+  // 1. Floor — deterministic full coverage
+  const floors = generateFloorEntities(mapDims, colors);
+
+  // 2. Action-provider NPCs — fixed cells from DefaultCyberiaActions. Built
+  //    first so their mission cells are guaranteed clear and walkable.
+  const actionProviders = generateActionProviderBots(mapCode, colors);
+
+  // 3. Obstacles — random, minus any overlapping an action-provider cell so
+  //    the mission NPCs always stand on walkable ground.
+  const obstacles = generateObstacles(mapDims, colors, { count: opts.obstacleCount }).filter(
+    (o) => !actionProviders.some((ap) => entitiesOverlap(o, ap)),
+  );
+
+  // 4. Build occupancy grid from obstacles, then reserve action-provider cells.
+  const grid = new OccupancyGrid(gridSize, gridSize);
+  grid.addObstacles(obstacles);
+  for (const ap of actionProviders) grid.block(ap.initCellX, ap.initCellY, ap.dimX, ap.dimY);
+
+  // 5. Portals — placed on walkable cells only, then blocked so bots avoid them
+  const portalEntities = generatePortalEntities(mapDims, colors, { grid });
+
+  // 6. Bots — placed on walkable cells (avoids obstacles, portals, NPCs)
+  const bots = generateBots(mapDims, colors, { count: opts.botCount, grid });
+
+  // 7. Resources — static exploitable entities placed on walkable cells
+  const resources = generateResources(mapDims, colors, { count: opts.resourceCount, grid });
+
+  // 8. Foreground — decorative, no collision restriction
+  const foreground = generateForeground(mapDims, colors, { count: opts.foregroundCount });
+
+  // 9. Statics — non-moving, passable decorators; depth-sorted with entities.
+  const statics = generateStatic(mapDims, colors, { count: opts.staticCount });
+
+  const entities = [
+    ...floors,
+    ...obstacles,
+    ...portalEntities,
+    ...foreground,
+    ...actionProviders,
+    ...bots,
+    ...resources,
+    ...statics,
+  ];
+
+  return {
+    code: mapCode,
+    name: `Fallback ${mapCode}`,
+    gridX: gridSize,
+    gridY: gridSize,
+    cellWidth: 32,
+    cellHeight: 32,
+    entities,
+  };
+}
+
+// ── Full world generator ─────────────────────────────────────────────────────
+
+/**
+ * Generate a complete in-memory fallback world: multiple maps connected
+ * by a portal ring topology.
+ *
+ * Returns a plain-object structure matching what a real CyberiaInstance
+ * + CyberiaMap query would return, so consumers can treat it identically.
+ *
+ * Nothing is persisted to MongoDB.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.mapCount=4]          Number of maps to generate.
+ * @param {number} [opts.gridSize=64]         Grid size per map.
+ * @param {number} [opts.obstacleCount]       Obstacles per map (random if omitted).
+ * @param {number} [opts.foregroundCount]     Foreground entities per map (random if omitted).
+ * @param {number} [opts.botCount]            Bots per map (random if omitted).
+ * @param {number} [opts.resourceCount]        Resources per map (random if omitted).
+ * @param {number} [opts.staticCount]          Static decorators per map (random if omitted).
+ * @param {Array}  [opts.colors]              Override palette.
+ * @returns {{
+ *   instance: object,
+ *   maps: object[],
+ *   portals: object[],
+ *   topology: string,
+ *   config: object,
+ *   _fallback: true
+ * }}
+ */
+function generateFallbackWorld(opts = {}) {
+  const {
+    mapCount = DEFAULT_MAP_COUNT,
+    gridSize,
+    obstacleCount,
+    foregroundCount,
+    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.
+    colors = PALETTE,
+  } = opts;
+
+  // Surface item-id drift loudly on the very first build, so a missing
+  // `bin/cyberia run-workflow import-default-items` run shows up at startup
+  // instead of as silent grey rectangles later.
+  const missing = auditFallbackItemIds();
+  if (missing.length > 0) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[cyberia-fallback-world] item ids referenced by defaults but absent from DefaultCyberiaItems:',
+      missing.join(', '),
+      '— run `node bin/cyberia run-workflow import-default-items` after adding them.',
+    );
+  }
+
+  // Generate map codes.
+  const mapCodes = [];
+  for (let i = 0; i < mapCount; i++) {
+    mapCodes.push(`fallback-map-${i}`);
+  }
+
+  // Generate each map (all randomized independently).
+  const maps = mapCodes.map((code) =>
+    generateFallbackMap(code, colors, {
+      gridSize,
+      obstacleCount,
+      foregroundCount,
+      botCount,
+      resourceCount,
+      staticCount,
+    }),
+  );
+
+  // Connect maps with portal topology using the portal connector module.
+  const { portals, topology } = connectPortals(mapCodes, maps);
+
+  // Build the instance shell (never persisted — no mongoId).
+  const instance = {
+    code: 'fallback',
+    name: 'Fallback Instance',
+    description: 'Auto-generated procedural world (not persisted)',
+    tags: ['fallback', 'procedural'],
+    cyberiaMapCodes: mapCodes,
+    portals,
+    topologyMode: 'procedural',
+    playerSpawn: { ...DEFAULT_PLAYER_SPAWN },
+  };
+
+  return {
+    instance,
+    maps,
+    portals,
+    topology,
+    config: CYBERIA_INSTANCE_CONF_DEFAULTS,
+    presentationHints: CYBERIA_CLIENT_HINTS_DEFAULTS,
+    _fallback: true,
+  };
+}
+
+// ── 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).
+
+const DEFAULT_FALLBACK_INSTANCE_CODE = 'TEST';
+
+function fallbackListInstance() {
+  return {
+    _id: `fallback-${DEFAULT_FALLBACK_INSTANCE_CODE.toLowerCase()}`,
+    code: DEFAULT_FALLBACK_INSTANCE_CODE,
+    name: 'Test Grounds',
+    description: 'Always-on sandbox world — drop in to explore a procedurally generated instance.',
+    tags: ['fallback', 'test', 'sandbox'],
+    status: 'published',
+    thumbnail: null,
+    cyberiaMapCodes: [],
+    creator: null,
+    _fallback: true,
+  };
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+export {
+  generateFallbackWorld,
+  generateFallbackMap,
+  auditFallbackItemIds,
+  fallbackListInstance,
+  DEFAULT_FALLBACK_INSTANCE_CODE,
+};

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

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ *
+ * Endpoints (all GET, internal server-to-server, mirroring the RPCs):
+ *   /boot/ping                         → { serverTimeMs }
+ *   /boot/object-layers[?itemType=x]   → ObjectLayerMessage[]        (getObjectLayerBatch)
+ *   /boot/object-layer/:itemId         → ObjectLayerMessage | 404    (getObjectLayer)
+ *   /boot/map/:mapCode[?instanceCode=] → { map } | 404               (getMapData)
+ *   /boot/full-instance[/:instanceCode]→ full world payload           (getFullInstance)
+ *   /boot/object-layer-manifest        → { entries }                  (getObjectLayerManifest)
+ */
+
+import {
+  fetchFullInstance,
+  fetchMapData,
+  fetchObjectLayer,
+  fetchObjectLayerBatch,
+  fetchObjectLayerManifest,
+  getInstanceModels,
+  pingData,
+} from '../../projects/cyberia/instance-data.js';
+
+class CyberiaInstanceBootService {
+  static ping = async () => pingData();
+
+  static objectLayerBatch = async (req, res, options) =>
+    await fetchObjectLayerBatch(getInstanceModels(options), req.query.itemType);
+
+  static objectLayer = async (req, res, options) => {
+    const msg = await fetchObjectLayer(getInstanceModels(options), req.params.itemId);
+    if (!msg) throw new Error(`ObjectLayer "${req.params.itemId}" not found`);
+    return msg;
+  };
+
+  static mapData = async (req, res, options) => {
+    const result = await fetchMapData(getInstanceModels(options), {
+      mapCode: req.params.mapCode,
+      instanceCode: req.query.instanceCode,
+    });
+    if (!result) throw new Error(`Map "${req.params.mapCode}" not found`);
+    return result;
+  };
+
+  static fullInstance = async (req, res, options) =>
+    await fetchFullInstance(getInstanceModels(options), req.params.instanceCode);
+
+  static objectLayerManifest = async (req, res, options) =>
+    await fetchObjectLayerManifest(getInstanceModels(options));
+}
+
+export { CyberiaInstanceBootService };