cyberia 3.0.1 → 3.0.2

package/src/api/ipfs/ipfs.service.js

@@ -0,0 +1,193 @@
+import { DataBaseProvider } from '../../db/DataBaseProvider.js';
+import { loggerFactory } from '../../server/logger.js';
+import { DataQuery } from '../../server/data-query.js';
+import { IpfsClient } from '../../server/ipfs-client.js';
+import { IpfsDto } from './ipfs.model.js';
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * Create (or upsert) an IPFS pin record for a given user + CID pair.
+ * This is a helper consumed by other services (ObjectLayer, AtlasSpriteSheet, …)
+ * so they don't need to know about the Ipfs model directly.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.cid      – IPFS Content Identifier.
+ * @param {string}  opts.userId   – Mongoose ObjectId string of the owning user.
+ * @param {object}  opts.options  – Router options ({ host, path }) for DB lookup.
+ * @returns {Promise<import('mongoose').Document>}
+ */
+const createPinRecord = async ({ cid, userId, options }) => {
+  const Ipfs = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Ipfs;
+
+  // Upsert: if a record for this user + CID already exists, just touch it.
+  const record = await Ipfs.findOneAndUpdate(
+    { cid, userId },
+    { cid, userId },
+    { upsert: true, new: true, setDefaultsOnInsert: true },
+  );
+
+  logger.info(`IPFS pin record upserted – CID: ${cid}, userId: ${userId}`);
+  return record;
+};
+
+/**
+ * Remove all DB pin records for a CID, then best-effort unpin from IPFS node/cluster.
+ * Always deletes the DB records first so that even if the IPFS node is unreachable
+ * the database stays clean.
+ *
+ * @param {string} cid     – IPFS Content Identifier to clean up.
+ * @param {object} options – Router options ({ host, path }) for DB lookup.
+ * @returns {Promise<void>}
+ */
+const removePinRecordsAndUnpin = async (cid, options) => {
+  const Ipfs = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Ipfs;
+
+  // 1. Remove all DB pin records for this CID first
+  await Ipfs.deleteMany({ cid });
+  logger.info(`Removed all IPFS pin records for CID: ${cid}`);
+
+  // 2. Best-effort unpin from IPFS node/cluster (ignore "not pinned" errors)
+  try {
+    await IpfsClient.unpinCid(cid);
+  } catch (err) {
+    logger.warn(`Best-effort IPFS unpin failed for CID ${cid}: ${err.message}`);
+  }
+};
+
+const IpfsService = {
+  /** Expose helpers so other modules can import them directly. */
+  createPinRecord,
+  removePinRecordsAndUnpin,
+
+  // ──────────────────────────────────────────────
+  //  Standard CRUD
+  // ──────────────────────────────────────────────
+
+  post: async (req, res, options) => {
+    /** @type {import('./ipfs.model.js').IpfsModel} */
+    const Ipfs = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Ipfs;
+
+    // Accept { cid, userId? } in body.
+    // If userId is omitted, fall back to the authenticated user.
+    const body = { ...req.body };
+    if (!body.userId && req.auth && req.auth.user) {
+      body.userId = req.auth.user._id;
+    }
+    // Strip pinType if sent by legacy clients
+    delete body.pinType;
+
+    return await new Ipfs(body).save();
+  },
+
+  get: async (req, res, options) => {
+    /** @type {import('./ipfs.model.js').IpfsModel} */
+    const Ipfs = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Ipfs;
+
+    if (req.params.id) {
+      return await Ipfs.findById(req.params.id).select(IpfsDto.select.get()).populate(IpfsDto.populate.user());
+    }
+
+    const { query, sort, skip, limit, page } = DataQuery.parse(req.query);
+
+    const [data, total] = await Promise.all([
+      Ipfs.find(query)
+        .select(IpfsDto.select.get())
+        .sort(sort)
+        .limit(limit)
+        .skip(skip)
+        .populate(IpfsDto.populate.user()),
+      Ipfs.countDocuments(query),
+    ]);
+
+    const totalPages = Math.ceil(total / limit);
+    return { data, total, page, totalPages };
+  },
+
+  put: async (req, res, options) => {
+    /** @type {import('./ipfs.model.js').IpfsModel} */
+    const Ipfs = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Ipfs;
+    return await Ipfs.findByIdAndUpdate(req.params.id, req.body, { new: true });
+  },
+
+  delete: async (req, res, options) => {
+    /** @type {import('./ipfs.model.js').IpfsModel} */
+    const Ipfs = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Ipfs;
+
+    if (req.params.id) {
+      const record = await Ipfs.findById(req.params.id);
+      if (record) {
+        // Remove DB record first, then best-effort unpin
+        await Ipfs.findByIdAndDelete(req.params.id);
+        try {
+          // Only unpin from IPFS if no other records reference this CID
+          const remaining = await Ipfs.countDocuments({ cid: record.cid });
+          if (remaining === 0) {
+            await IpfsClient.unpinCid(record.cid);
+          }
+        } catch (err) {
+          logger.warn(`Failed to unpin CID ${record.cid} from IPFS node: ${err.message}`);
+        }
+        return record;
+      }
+      return null;
+    }
+
+    return await Ipfs.deleteMany();
+  },
+
+  // ──────────────────────────────────────────────
+  //  Pin / Unpin helpers (called via controller)
+  // ──────────────────────────────────────────────
+
+  /**
+   * POST /ipfs/pin  – add content to IPFS, pin it, and create a DB record.
+   * Body: { data: <string|object>, userId? }
+   */
+  pin: async (req, res, options) => {
+    const userId = req.body.userId || (req.auth && req.auth.user ? req.auth.user._id : undefined);
+    if (!userId) throw new Error('userId is required to create a pin record');
+
+    const content = typeof req.body.data === 'string' ? req.body.data : JSON.stringify(req.body.data);
+    const result = await IpfsClient.addToIpfs(Buffer.from(content, 'utf-8'), req.body.filename || 'data');
+
+    if (!result) throw new Error('IPFS node is unreachable – content was not pinned');
+
+    const record = await createPinRecord({
+      cid: result.cid,
+      userId,
+      options,
+    });
+
+    return { cid: result.cid, size: result.size, record };
+  },
+
+  /**
+   * DELETE /ipfs/pin/:cid  – unpin a CID and remove the DB record for the current user.
+   */
+  unpin: async (req, res, options) => {
+    const Ipfs = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Ipfs;
+    const userId = req.auth && req.auth.user ? req.auth.user._id : undefined;
+    const cid = req.params.cid || req.params.id;
+
+    const record = await Ipfs.findOne({ cid, ...(userId ? { userId } : {}) });
+    if (!record) throw new Error(`No pin record found for CID ${cid}`);
+
+    // Remove DB record first
+    await Ipfs.findByIdAndDelete(record._id);
+
+    // Only unpin from the IPFS node when nobody else has a record for this CID
+    const remaining = await Ipfs.countDocuments({ cid });
+    if (remaining === 0) {
+      try {
+        await IpfsClient.unpinCid(cid);
+      } catch (err) {
+        logger.warn(`Best-effort IPFS unpin failed for CID ${cid}: ${err.message}`);
+      }
+    }
+
+    return { success: true, cid };
+  },
+};
+
+export { IpfsService, createPinRecord, removePinRecordsAndUnpin };

package/src/api/object-layer/README.md

@@ -24,12 +24,14 @@ Key features:
 
 - Walks the asset directory structure and processes PNG/GIF files.
 - Produces `frame_matrix` and `map_color` arrays from images.
+- **Procedurally generates object layers** from semantic item-id descriptors with deterministic seeds and temporal coherence.
 - Saves processed objects to the `ObjectLayer` model with top-level references to `ObjectLayerRenderFrames`.
 - Creates separate `ObjectLayerRenderFrames` documents for render data.
 - Links ObjectLayers to AtlasSpriteSheet documents via top-level `atlasSpriteSheetId`.
 - Generates unique UUID v4 seeds (via `crypto.randomUUID()`) for SHA256 hash uniqueness.
 - Generates SHA256 hash using `fast-json-stable-stringify` for deterministic serialization.
 - Reconstructs PNG frames from stored tile data for debugging.
+- Writes static asset PNGs, atlas sprite sheets, and metadata to the conventional directory structure.
 
 ## Getting Started
 
@@ -68,6 +70,104 @@ cyberia ol --import skin,floor
 cyberia ol --import all
 ```
 
+### Procedural generation with `--generate`
+
+Produces semantically consistent object layers with controlled, reproducible variation and short-term temporal coherence (consecutive frames stay visually consistent). Uses the parametric shape generator and object layer engine under the hood.
+
+```bash
+# Generate a desert floor tile (single frame, auto seed)
+cyberia ol floor-desert --generate
+
+# Full control: 3 frames, explicit seed, density
+cyberia ol floor-desert --generate --count 3 --seed fx-42 --frame-index 0 --frame-count 3 --density 0.5
+
+# Grass terrain, sparse, 5 frames
+cyberia ol floor-grass --generate --seed meadow-7 --frame-count 5 --density 0.3
+
+# Water surface, dense, high element count
+cyberia ol floor-water --generate --seed ocean-1 --count 5 --density 0.8 --frame-count 4
+
+# Stone cobblestone
+cyberia ol floor-stone --generate --seed cobble-99 --count 4 --density 0.6
+
+# Lava flow, 3-frame animation
+cyberia ol floor-lava --generate --seed magma-3 --frame-count 3 --density 0.7
+```
+
+**`--generate` options:**
+
+| Option | Default | Description |
+|---|---|---|
+| `--seed <str>` | auto UUID | Deterministic seed string. Same seed → same output. |
+| `--count <n>` | `3` | Shape element count multiplier per layer. |
+| `--frame-index <n>` | `0` | Starting frame index. |
+| `--frame-count <n>` | `1` | Number of consecutive frames to generate. |
+| `--density <f>` | `0.5` | Overall density factor (`0`–`1`). Lower = sparser. |
+
+**Available semantic item-id prefixes:**
+
+| Prefix | Type | Tags | Palette |
+|---|---|---|---|
+| `floor-desert` | floor | sand, dune, arid | warm ochres, sand tones |
+| `floor-grass` | floor | grass, meadow, earth | greens, earth browns |
+| `floor-water` | floor | water, ocean, wave | blues, foam whites |
+| `floor-stone` | floor | stone, rock, cobble | greys, warm/cool stone |
+| `floor-lava` | floor | lava, magma, fire | reds, oranges, dark crust |
+| `skin-*` | skin | character, body | skin tones, clothing darks |
+
+#### How generation works
+
+Each item-id maps to a **semantic descriptor** that provides `semanticTags`, `paletteHints`, `preferredShapes`, and named **layer specs** (e.g. `base`, `dunes`, `rocks`, `tufts` for `floor-desert`).
+
+**Seed derivation** — deterministic at every level:
+
+```
+layerSeed  = hash(seed + ':' + itemId + ':' + layerKey)
+frameSeed  = hash(layerSeed + ':' + frameIndex)
+```
+
+**Temporal coherence** — shape topology (which shapes, how many, where) is locked to `layerSeed` and never changes between frames. Only smooth, low-frequency noise perturbations (position jitter, slight rotation/scale wobble) are derived from `frameSeed`, so frame N and N+1 differ by ~2% of cells.
+
+**Layer naming** — every generated layer gets an id: `<itemId>-<layerKey>` (e.g. `floor-desert-dunes`).
+
+**Generation pipeline per layer:**
+
+1. Pick generator type (`noise-field` for base fills, `shape` for element placement).
+2. Select palette colors deterministically from `paletteHints` with per-element `colorShift`.
+3. For shape layers: pick shape via weighted `preferredShapes`, compute stable base transform `(x, y, scale, rotation)`, apply frame-level smooth noise.
+4. Stamp shapes onto a 24×24 grid via `intCoords` rasterization from the parametric shape generator.
+5. Composite all layers into a final `frame_matrix` + unified `colors` palette.
+
+**Variability factors per layer:**
+`scaleVariance`, `rotationVariance`, `colorShift`, `jitter`, `noiseLevel`, `detailLevel`, `sparsity` — small, deterministic variations that keep each generation unique but semantically coherent.
+
+#### What `--generate` persists
+
+The full pipeline runs automatically:
+
+1. **Static assets** — PNGs written to `./src/client/public/cyberia/assets/{type}/{itemId}/{dirCode}/{frame}.png` + `metadata.json`.
+2. **MongoDB** — `ObjectLayerRenderFrames` + `ObjectLayer` documents created with SHA-256 hash.
+3. **Atlas sprite sheet** — generated, saved to `File` + `AtlasSpriteSheet` collections, and linked via `atlasSpriteSheetId`.
+
+#### Reproducibility example
+
+Running the same command twice produces byte-identical output:
+
+```bash
+# Run 1
+cyberia ol floor-desert --generate --seed fx-42 --count 3 --frame-count 2
+
+# Run 2 (identical output)
+cyberia ol floor-desert --generate --seed fx-42 --count 3 --frame-count 2
+```
+
+Different seeds produce different but semantically consistent results:
+
+```bash
+cyberia ol floor-desert --generate --seed fx-42   # variant A
+cyberia ol floor-desert --generate --seed fx-99   # variant B (same style, different arrangement)
+```
+
 ## Visualize a processed frame
 
 Reconstructs and opens a PNG from the database-stored frame data. Requires item-id as the first positional argument, followed by direction and frame index in the format `[direction]_[frameIndex]`.
@@ -178,6 +278,45 @@ cyberia ol anon --to-atlas-sprite-sheet
 cyberia ol anon --show-atlas-sprite-sheet
 ```
 
+### Procedural Generation Pipeline
+
+Generate an object layer entirely from a semantic descriptor — no source PNGs needed:
+
+```bash
+# 1. Generate a 3-frame desert floor with explicit seed
+cyberia ol floor-desert --generate --seed fx-42 --frame-count 3 --density 0.5
+
+# 2. Inspect the generated frame
+cyberia ol floor-desert --show-frame 08_0
+
+# 3. View the auto-generated atlas
+cyberia ol floor-desert --show-atlas-sprite-sheet
+```
+
+### Batch Procedural Generation
+
+Generate a full tileset family with consistent seeds:
+
+```bash
+cyberia ol floor-desert --generate --seed world-1 --frame-count 3
+cyberia ol floor-grass  --generate --seed world-1 --frame-count 3
+cyberia ol floor-water  --generate --seed world-1 --frame-count 4
+cyberia ol floor-stone  --generate --seed world-1 --frame-count 2
+cyberia ol floor-lava   --generate --seed world-1 --frame-count 3
+```
+
+### Exploring Seed Variations
+
+```bash
+# Same item, different seeds — compare visual output
+cyberia ol floor-desert --generate --seed alpha  --frame-count 1
+cyberia ol floor-desert --generate --seed beta   --frame-count 1
+cyberia ol floor-desert --generate --seed gamma  --frame-count 1
+
+# Inspect each
+cyberia ol floor-desert --show-frame 08_0
+```
+
 ### Debugging Asset Issues
 
 ```bash

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

@@ -21,6 +21,8 @@ const ObjectLayerController = {
   },
   get: async (req, res, options) => {
     try {
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      res.setHeader('Cross-Origin-Resource-Policy', 'cross-origin');
       const result = await ObjectLayerService.get(req, res, options);
       return res.status(200).json({
         status: 'success',
@@ -37,6 +39,7 @@ const ObjectLayerController = {
   generateWebp: async (req, res, options) => {
     try {
       const result = await ObjectLayerService.generateWebp(req, res, options);
+      res.setHeader('Access-Control-Allow-Origin', '*');
       res.setHeader('Cross-Origin-Resource-Policy', 'cross-origin');
       res.setHeader('Content-Type', 'image/webp');
       res.setHeader(

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

@@ -52,6 +52,8 @@ const ItemSchema = new Schema(
  * @property {Data.Stats} data.stats - Statistical attributes of the object layer
  * @property {Data.Item} data.item - Item information this layer represents
  * @property {string} data.seed - Random UUID for unique state generation
+ * @property {string} [data.atlasSpriteSheetCid] - IPFS Content Identifier for the consolidated atlas sprite sheet PNG
+ * @property {string} [cid] - IPFS Content Identifier for the object layer data JSON (fast-json-stable-stringify)
  * @property {Types.ObjectId} objectLayerRenderFramesId - Reference to ObjectLayerRenderFrames document
  * @property {Types.ObjectId} atlasSpriteSheetId - Reference to AtlasSpriteSheet document
  * @property {string} sha256 - SHA-256 hash of the object layer data
@@ -72,7 +74,9 @@ const ObjectLayerSchema = new Schema(
           'Please provide a valid UUID v4',
         ],
       },
+      atlasSpriteSheetCid: { type: String, default: '', trim: true },
     },
+    cid: { type: String, default: '', trim: true },
     objectLayerRenderFramesId: { type: Schema.Types.ObjectId, ref: 'ObjectLayerRenderFrames' },
     atlasSpriteSheetId: { type: Schema.Types.ObjectId, ref: 'AtlasSpriteSheet' },
     sha256: {
@@ -115,6 +119,7 @@ ObjectLayerSchema.pre('save', function (next) {
   if (!this.data.stats || !this.data.item || !this.data.seed || !this.sha256) {
     throw new Error('Missing required fields');
   }
+  // cid (object layer data JSON) and data.atlasSpriteSheetCid (atlas PNG) are optional – default to ''
   next();
 });
 
@@ -126,7 +131,14 @@ const ProviderSchema = ObjectLayerSchema;
 const ObjectLayerDto = {
   select: {
     get: () => {
-      return { _id: 1, 'data.item': 1 };
+      return {
+        _id: 1,
+        'data.item': 1,
+        'data.atlasSpriteSheetCid': 1,
+        cid: 1,
+        objectLayerRenderFramesId: 1,
+        atlasSpriteSheetId: 1,
+      };
     },
     getMetadata: () => {
       return {
@@ -134,6 +146,8 @@ const ObjectLayerDto = {
         'data.item': 1,
         'data.stats': 1,
         'data.seed': 1,
+        'data.atlasSpriteSheetCid': 1,
+        cid: 1,
         objectLayerRenderFramesId: 1,
         atlasSpriteSheetId: 1,
         sha256: 1,

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

@@ -20,16 +20,12 @@ const ObjectLayerRouter = (options) => {
     `/generate-webp/:itemType/:itemId/:directionCode`,
     async (req, res) => await ObjectLayerController.generateWebp(req, res, options),
   );
-  router.get(`/render/:id`, authMiddleware, async (req, res) => await ObjectLayerController.get(req, res, options));
-  router.get(`/metadata/:id`, authMiddleware, async (req, res) => await ObjectLayerController.get(req, res, options));
-  router.get(
-    `/frame-counts/:id`,
-    authMiddleware,
-    async (req, res) => await ObjectLayerController.get(req, res, options),
-  );
-  router.get(`/:id`, authMiddleware, async (req, res) => await ObjectLayerController.get(req, res, options));
-  router.get(`/:id`, authMiddleware, async (req, res) => await ObjectLayerController.get(req, res, options));
-  router.get(`/`, authMiddleware, async (req, res) => await ObjectLayerController.get(req, res, options));
+  router.get(`/render/:id`, async (req, res) => await ObjectLayerController.get(req, res, options));
+  router.get(`/metadata/:id`, async (req, res) => await ObjectLayerController.get(req, res, options));
+  router.get(`/frame-counts/:id`, async (req, res) => await ObjectLayerController.get(req, res, options));
+  router.get(`/:id`, async (req, res) => await ObjectLayerController.get(req, res, options));
+  router.get(`/:id`, async (req, res) => await ObjectLayerController.get(req, res, options));
+  router.get(`/`, async (req, res) => await ObjectLayerController.get(req, res, options));
   router.put(
     `/:id/frame-image/:itemType/:itemId/:directionCode`,
     authMiddleware,