cyberia 3.1.3 → 3.2.5

package/src/server/semantic-layer-generator.js

@@ -1,12 +1,16 @@
 /**
- * Semantic Layer Generator for Cyberia Online.
+ * Semantic Layer Generator for Cyberia Online — Router / Dispatcher.
  *
- * Produces semantically consistent object layers with controlled, reproducible
- * variation and short-term temporal coherence (consecutive frames stay consistent).
- *
- * Uses the shape-generator primitives (createRng, seedToInt, createNoise2D, generateShape)
- * and object-layer engine (createObjectLayerDocuments, buildImgFromTile) to produce
- * frame matrices that can be persisted to MongoDB / IPFS / static assets.
+ * This module is the public API surface.  It:
+ *   1. Owns the semantic registry (registerSemantic / lookupSemantic).
+ *   2. Provides the shared utility functions used by category submodules.
+ *   3. Implements the default shape/noise-field generation pipeline
+ *      (generateFrame / generateMultiFrame).
+ *   4. Delegates to descriptor-attached custom generators when present
+ *      (e.g. skin uses template-based pixel painting via customMultiFrameGenerator).
+ *   5. Loads category submodules at initialisation:
+ *        • semantic-layer-generator-floor.js — all floor-* descriptors
+ *        • semantic-layer-generator-skin.js  — skin-* descriptors
  *
  * @module src/server/semantic-layer-generator.js
  * @namespace SemanticLayerGenerator
@@ -17,6 +21,9 @@ import crypto from 'crypto';
 import { createRng, seedToInt, createNoise2D, generateShape, listShapes } from './shape-generator.js';
 import { loggerFactory } from './logger.js';
 
+import { registerFloorSemantics } from './semantic-layer-generator-floor.js';
+import { registerSkinSemantics } from './semantic-layer-generator-skin.js';
+
 const logger = loggerFactory(import.meta);
 
 /* ═══════════════════════════════════════════════════════════════════════════
@@ -25,39 +32,34 @@ const logger = loggerFactory(import.meta);
 
 /**
  * Produces a deterministic 32-bit integer hash from an arbitrary string.
- * Used to derive per-layer and per-frame seeds.
  * @param {string} str
  * @returns {number}
  * @memberof SemanticLayerGenerator
  */
+function hashString(str) {
+  let h = 0;
+  for (let i = 0; i < str.length; i++) {
+    h = (Math.imul(31, h) + str.charCodeAt(i)) | 0;
+  }
+  return h;
+}
+
 /**
  * Derives a deterministic UUID v4 from an arbitrary seed string.
- * Uses SHA-256 to hash the seed, then formats 16 bytes as a valid UUID v4
- * (version nibble = 4, variant bits = 10xx).
  * @param {string} seed
- * @returns {string} A valid UUID v4 string.
+ * @returns {string}
  * @memberof SemanticLayerGenerator
  */
 function seedToUUIDv4(seed) {
   const hash = crypto.createHash('sha256').update(seed).digest();
-  // Set version nibble (byte 6, high nibble) to 0100 (version 4)
   hash[6] = (hash[6] & 0x0f) | 0x40;
-  // Set variant bits (byte 8, high 2 bits) to 10xx
   hash[8] = (hash[8] & 0x3f) | 0x80;
   const hex = hash.toString('hex');
   return [hex.slice(0, 8), hex.slice(8, 12), hex.slice(12, 16), hex.slice(16, 20), hex.slice(20, 32)].join('-');
 }
 
-function hashString(str) {
-  let h = 0;
-  for (let i = 0; i < str.length; i++) {
-    h = (Math.imul(31, h) + str.charCodeAt(i)) | 0;
-  }
-  return h;
-}
-
 /**
- * Derives a per-layer seed:  layerSeed = hash(seed + ':' + itemId + ':' + layerKey)
+ * Derives a per-layer seed.
  * @param {string} seed
  * @param {string} itemId
  * @param {string} layerKey
@@ -69,7 +71,7 @@ function deriveLayerSeed(seed, itemId, layerKey) {
 }
 
 /**
- * Derives a per-frame seed:  frameSeed = hash(layerSeed + ':' + frameIndex)
+ * Derives a per-frame seed.
  * @param {number} layerSeed
  * @param {number} frameIndex
  * @returns {number}
@@ -81,34 +83,34 @@ function deriveFrameSeed(layerSeed, frameIndex) {
 
 /* ═══════════════════════════════════════════════════════════════════════════
  *  SEMANTIC REGISTRY
- *  Maps item-id prefixes to semantic descriptors that drive generation.
  * ═══════════════════════════════════════════════════════════════════════════ */
 
 /**
  * @typedef {Object} SemanticDescriptor
- * @property {string[]} semanticTags      - Conceptual tags (e.g. ['sand','dune']).
- * @property {number[][]} paletteHints    - Array of RGBA palette colors.
- * @property {Object<string,number>} preferredShapes - Shape key → relative weight.
- * @property {Object<string,LayerSpec>} layers - Named layer specifications.
- * @property {string} itemType            - Object layer type (floor, skin, weapon…).
+ * @property {string[]}               semanticTags              Conceptual tags.
+ * @property {number[][]}             paletteHints              RGBA palette colours.
+ * @property {Object<string,number>}  preferredShapes           Shape key → weight.
+ * @property {Object<string,LayerSpec>} layers                  Named layer specs.
+ * @property {string}                 itemType                  floor | skin | weapon | skill | coin
+ * @property {Function}               [customMultiFrameGenerator] Overrides the default multi-frame pipeline.
  * @memberof SemanticLayerGenerator
  */
 
 /**
  * @typedef {Object} LayerSpec
- * @property {string}   generator       - 'shape' | 'noise-field' | 'sprite'
- * @property {string[]} shapes          - Candidate shape keys for this layer.
- * @property {number}   count           - Number of elements to place.
- * @property {number}   scaleVariance   - Max ± scale deviation (0..1).
- * @property {number}   rotationVariance- Max ± rotation deviation in degrees.
- * @property {number}   colorShift      - Max RGBA channel shift per element.
- * @property {number}   jitter          - Positional jitter amount (0..1).
- * @property {number}   noiseLevel      - Noise displacement applied to shapes.
- * @property {number}   detailLevel     - Point count multiplier for shapes.
- * @property {number}   sparsity        - Fraction of grid cells left empty (0..1).
- * @property {number}   [frameJitter]   - Per-frame positional wobble for temporal coherence.
- * @property {number}   [frameRotation] - Per-frame rotation wobble in degrees.
- * @property {number}   [frameScale]    - Per-frame scale wobble.
+ * @property {string}   generator          'shape' | 'noise-field' | 'template-zone'
+ * @property {string[]} [shapes]
+ * @property {number}   [count]
+ * @property {number}   [scaleVariance]
+ * @property {number}   [rotationVariance]
+ * @property {number}   [colorShift]
+ * @property {number}   [jitter]
+ * @property {number}   [noiseLevel]
+ * @property {number}   [detailLevel]
+ * @property {number}   [sparsity]
+ * @property {number}   [frameJitter]
+ * @property {number}   [frameRotation]
+ * @property {number}   [frameScale]
  * @memberof SemanticLayerGenerator
  */
 
@@ -137,7 +139,6 @@ export function registerSemantic(prefix, descriptor) {
  */
 export function lookupSemantic(itemId) {
   if (semanticRegistry[itemId]) return semanticRegistry[itemId];
-  // Longest prefix match
   let best = null;
   let bestLen = 0;
   for (const prefix of Object.keys(semanticRegistry)) {
@@ -149,385 +150,9 @@ export function lookupSemantic(itemId) {
   return best;
 }
 
-/* ── Built-in semantic descriptors ─────────────────────────────────────── */
-
-registerSemantic('floor-desert', {
-  semanticTags: ['sand', 'dune', 'arid', 'dry'],
-  paletteHints: [
-    [210, 180, 120, 255], // warm sand
-    [194, 160, 100, 255], // darker sand
-    [230, 205, 150, 255], // light sand
-    [180, 140, 80, 255], // ochre
-    [160, 120, 70, 255], // deep ochre
-    [120, 90, 55, 255], // rock brown
-    [100, 80, 50, 255], // shadow
-    [240, 220, 175, 255], // highlight
-  ],
-  preferredShapes: { ellipse: 3, circle: 2, cactus: 1, star: 0.5 },
-  itemType: 'floor',
-  layers: {
-    base: {
-      generator: 'noise-field',
-      shapes: ['ellipse'],
-      count: 0,
-      scaleVariance: 0,
-      rotationVariance: 0,
-      colorShift: 8,
-      jitter: 0,
-      noiseLevel: 0.3,
-      detailLevel: 1,
-      sparsity: 0,
-      frameJitter: 0,
-      frameRotation: 0,
-      frameScale: 0,
-    },
-    dunes: {
-      generator: 'shape',
-      shapes: ['ellipse', 'circle'],
-      count: 5,
-      scaleVariance: 0.3,
-      rotationVariance: 15,
-      colorShift: 12,
-      jitter: 0.08,
-      noiseLevel: 0.15,
-      detailLevel: 1.2,
-      sparsity: 0.3,
-      frameJitter: 0.005,
-      frameRotation: 0.5,
-      frameScale: 0.005,
-    },
-    rocks: {
-      generator: 'shape',
-      shapes: ['star', 'circle'],
-      count: 3,
-      scaleVariance: 0.4,
-      rotationVariance: 45,
-      colorShift: 15,
-      jitter: 0.12,
-      noiseLevel: 0.2,
-      detailLevel: 1,
-      sparsity: 0.5,
-      frameJitter: 0.002,
-      frameRotation: 0.3,
-      frameScale: 0.003,
-    },
-    tufts: {
-      generator: 'shape',
-      shapes: ['cactus', 'star'],
-      count: 2,
-      scaleVariance: 0.25,
-      rotationVariance: 20,
-      colorShift: 10,
-      jitter: 0.1,
-      noiseLevel: 0.1,
-      detailLevel: 0.8,
-      sparsity: 0.6,
-      frameJitter: 0.008,
-      frameRotation: 1.0,
-      frameScale: 0.006,
-    },
-  },
-});
-
-registerSemantic('floor-grass', {
-  semanticTags: ['grass', 'meadow', 'green', 'earth'],
-  paletteHints: [
-    [80, 140, 60, 255], // base green
-    [60, 120, 45, 255], // dark green
-    [110, 170, 80, 255], // light green
-    [90, 130, 55, 255], // mid green
-    [130, 100, 65, 255], // earth
-    [70, 110, 40, 255], // shadow green
-    [150, 190, 100, 255], // highlight
-    [100, 85, 50, 255], // dark earth
-  ],
-  preferredShapes: { ellipse: 3, circle: 2, heart: 0.5 },
-  itemType: 'floor',
-  layers: {
-    base: {
-      generator: 'noise-field',
-      shapes: ['circle'],
-      count: 0,
-      scaleVariance: 0,
-      rotationVariance: 0,
-      colorShift: 10,
-      jitter: 0,
-      noiseLevel: 0.25,
-      detailLevel: 1,
-      sparsity: 0,
-      frameJitter: 0,
-      frameRotation: 0,
-      frameScale: 0,
-    },
-    blades: {
-      generator: 'shape',
-      shapes: ['ellipse', 'heart'],
-      count: 6,
-      scaleVariance: 0.35,
-      rotationVariance: 40,
-      colorShift: 15,
-      jitter: 0.1,
-      noiseLevel: 0.12,
-      detailLevel: 1.0,
-      sparsity: 0.25,
-      frameJitter: 0.01,
-      frameRotation: 2.0,
-      frameScale: 0.005,
-    },
-    patches: {
-      generator: 'shape',
-      shapes: ['circle', 'ellipse'],
-      count: 3,
-      scaleVariance: 0.3,
-      rotationVariance: 30,
-      colorShift: 12,
-      jitter: 0.08,
-      noiseLevel: 0.15,
-      detailLevel: 0.9,
-      sparsity: 0.4,
-      frameJitter: 0.003,
-      frameRotation: 0.5,
-      frameScale: 0.003,
-    },
-  },
-});
-
-registerSemantic('floor-water', {
-  semanticTags: ['water', 'ocean', 'wave', 'liquid'],
-  paletteHints: [
-    [40, 100, 180, 255], // deep blue
-    [60, 130, 200, 255], // mid blue
-    [90, 160, 220, 255], // light blue
-    [120, 190, 230, 255], // highlight
-    [30, 80, 150, 255], // dark blue
-    [70, 140, 210, 255], // wave crest
-    [150, 210, 240, 255], // foam
-    [20, 60, 120, 255], // abyss
-  ],
-  preferredShapes: { ellipse: 3, circle: 2 },
-  itemType: 'floor',
-  layers: {
-    base: {
-      generator: 'noise-field',
-      shapes: ['ellipse'],
-      count: 0,
-      scaleVariance: 0,
-      rotationVariance: 0,
-      colorShift: 12,
-      jitter: 0,
-      noiseLevel: 0.35,
-      detailLevel: 1,
-      sparsity: 0,
-      frameJitter: 0,
-      frameRotation: 0,
-      frameScale: 0,
-    },
-    waves: {
-      generator: 'shape',
-      shapes: ['ellipse'],
-      count: 4,
-      scaleVariance: 0.3,
-      rotationVariance: 10,
-      colorShift: 18,
-      jitter: 0.06,
-      noiseLevel: 0.2,
-      detailLevel: 1.2,
-      sparsity: 0.2,
-      frameJitter: 0.015,
-      frameRotation: 1.5,
-      frameScale: 0.008,
-    },
-    foam: {
-      generator: 'shape',
-      shapes: ['circle'],
-      count: 3,
-      scaleVariance: 0.5,
-      rotationVariance: 0,
-      colorShift: 10,
-      jitter: 0.15,
-      noiseLevel: 0.1,
-      detailLevel: 0.7,
-      sparsity: 0.5,
-      frameJitter: 0.012,
-      frameRotation: 0.5,
-      frameScale: 0.01,
-    },
-  },
-});
-
-registerSemantic('floor-stone', {
-  semanticTags: ['stone', 'rock', 'cobble', 'grey'],
-  paletteHints: [
-    [140, 140, 145, 255], // base grey
-    [120, 118, 125, 255], // dark grey
-    [165, 165, 170, 255], // light grey
-    [100, 98, 105, 255], // shadow
-    [180, 180, 185, 255], // highlight
-    [90, 85, 80, 255], // dark rock
-    [155, 150, 148, 255], // warm grey
-    [110, 108, 115, 255], // cool grey
-  ],
-  preferredShapes: { circle: 3, ellipse: 2, star: 1, 'pixel-art': 0.5 },
-  itemType: 'floor',
-  layers: {
-    base: {
-      generator: 'noise-field',
-      shapes: ['circle'],
-      count: 0,
-      scaleVariance: 0,
-      rotationVariance: 0,
-      colorShift: 6,
-      jitter: 0,
-      noiseLevel: 0.2,
-      detailLevel: 1,
-      sparsity: 0,
-      frameJitter: 0,
-      frameRotation: 0,
-      frameScale: 0,
-    },
-    cobbles: {
-      generator: 'shape',
-      shapes: ['circle', 'ellipse', 'pixel-art'],
-      count: 6,
-      scaleVariance: 0.35,
-      rotationVariance: 90,
-      colorShift: 10,
-      jitter: 0.06,
-      noiseLevel: 0.15,
-      detailLevel: 1.0,
-      sparsity: 0.2,
-      frameJitter: 0.001,
-      frameRotation: 0.2,
-      frameScale: 0.001,
-    },
-    cracks: {
-      generator: 'shape',
-      shapes: ['star'],
-      count: 2,
-      scaleVariance: 0.5,
-      rotationVariance: 180,
-      colorShift: 20,
-      jitter: 0.1,
-      noiseLevel: 0.25,
-      detailLevel: 0.8,
-      sparsity: 0.6,
-      frameJitter: 0.0,
-      frameRotation: 0.0,
-      frameScale: 0.0,
-    },
-  },
-});
-
-registerSemantic('floor-lava', {
-  semanticTags: ['lava', 'magma', 'fire', 'hot'],
-  paletteHints: [
-    [200, 50, 20, 255], // hot red
-    [230, 100, 30, 255], // orange
-    [255, 180, 50, 255], // bright yellow
-    [160, 30, 10, 255], // dark red
-    [80, 20, 10, 255], // cooled rock
-    [50, 15, 8, 255], // dark crust
-    [240, 140, 40, 255], // glow
-    [120, 25, 12, 255], // mid lava
-  ],
-  preferredShapes: { circle: 3, ellipse: 2, cactus: 1 },
-  itemType: 'floor',
-  layers: {
-    base: {
-      generator: 'noise-field',
-      shapes: ['circle'],
-      count: 0,
-      scaleVariance: 0,
-      rotationVariance: 0,
-      colorShift: 15,
-      jitter: 0,
-      noiseLevel: 0.4,
-      detailLevel: 1,
-      sparsity: 0,
-      frameJitter: 0,
-      frameRotation: 0,
-      frameScale: 0,
-    },
-    flow: {
-      generator: 'shape',
-      shapes: ['ellipse', 'circle'],
-      count: 5,
-      scaleVariance: 0.35,
-      rotationVariance: 25,
-      colorShift: 20,
-      jitter: 0.1,
-      noiseLevel: 0.2,
-      detailLevel: 1.1,
-      sparsity: 0.2,
-      frameJitter: 0.02,
-      frameRotation: 2.0,
-      frameScale: 0.01,
-    },
-    crust: {
-      generator: 'shape',
-      shapes: ['star', 'cactus'],
-      count: 3,
-      scaleVariance: 0.4,
-      rotationVariance: 60,
-      colorShift: 10,
-      jitter: 0.08,
-      noiseLevel: 0.15,
-      detailLevel: 0.9,
-      sparsity: 0.4,
-      frameJitter: 0.005,
-      frameRotation: 0.5,
-      frameScale: 0.004,
-    },
-  },
-});
-
-registerSemantic('skin-', {
-  semanticTags: ['character', 'body', 'humanoid'],
-  paletteHints: [
-    [180, 140, 110, 255],
-    [160, 120, 90, 255],
-    [200, 160, 130, 255],
-    [140, 100, 70, 255],
-    [100, 70, 50, 255],
-    [60, 60, 80, 255],
-    [80, 80, 100, 255],
-    [220, 180, 150, 255],
-  ],
-  preferredShapes: { 'skull-bone': 2, circle: 2, ellipse: 1 },
-  itemType: 'skin',
-  layers: {
-    body: {
-      generator: 'shape',
-      shapes: ['ellipse', 'circle'],
-      count: 4,
-      scaleVariance: 0.3,
-      rotationVariance: 10,
-      colorShift: 12,
-      jitter: 0.05,
-      noiseLevel: 0.1,
-      detailLevel: 1.2,
-      sparsity: 0.2,
-      frameJitter: 0.003,
-      frameRotation: 0.5,
-      frameScale: 0.003,
-    },
-    detail: {
-      generator: 'shape',
-      shapes: ['skull-bone', 'star'],
-      count: 2,
-      scaleVariance: 0.2,
-      rotationVariance: 5,
-      colorShift: 8,
-      jitter: 0.03,
-      noiseLevel: 0.08,
-      detailLevel: 1.5,
-      sparsity: 0.5,
-      frameJitter: 0.002,
-      frameRotation: 0.3,
-      frameScale: 0.002,
-    },
-  },
-});
+/* ── Load category submodules at startup ────────────────────────────────── */
+registerFloorSemantics(registerSemantic);
+registerSkinSemantics(registerSemantic);
 
 /* ═══════════════════════════════════════════════════════════════════════════
  *  COLOR UTILITIES
@@ -537,7 +162,7 @@ registerSemantic('skin-', {
  * Picks a palette color deterministically from the hint palette.
  * @param {number[][]} palette
  * @param {function():number} rng
- * @param {number} colorShift - Max channel deviation.
+ * @param {number} colorShift
  * @returns {number[]} RGBA array.
  * @memberof SemanticLayerGenerator
  */
@@ -569,7 +194,6 @@ function clamp(v, min, max) {
 
 /**
  * Picks a shape key from candidate list, weighted by the descriptor's preferredShapes.
- * Falls back to uniform if no weights match.
  * @param {string[]} candidates
  * @param {Object<string,number>} weights
  * @param {function():number} rng
@@ -577,13 +201,9 @@ function clamp(v, min, max) {
  * @memberof SemanticLayerGenerator
  */
 function pickShape(candidates, weights, rng) {
-  // Filter to only shapes that actually exist in the shape registry
   const available = listShapes();
   const valid = candidates.filter((c) => available.includes(c));
-  if (valid.length === 0) {
-    // fallback to any available shape
-    return available[Math.floor(rng() * available.length)];
-  }
+  if (valid.length === 0) return available[Math.floor(rng() * available.length)];
   const w = valid.map((k) => weights[k] ?? 1);
   const total = w.reduce((s, v) => s + v, 0);
   let r = rng() * total;
@@ -596,46 +216,33 @@ function pickShape(candidates, weights, rng) {
 
 /* ═══════════════════════════════════════════════════════════════════════════
  *  FRAME MATRIX GENERATION
- *  Converts generated shape layers into a 24×24 frame_matrix compatible
- *  with the ObjectLayerEngine frame format.
  * ═══════════════════════════════════════════════════════════════════════════ */
 
-const GRID_DIM = 24; // standard object layer grid (24 rows × 24 cols)
+const GRID_DIM = 24;
 
 /**
  * Generates a noise-field base layer as a 24×24 frame matrix.
- * Uses low-frequency 2D noise seeded per-frame for temporal coherence.
- * @param {number[][]} palette
- * @param {number} layerSeedInt
- * @param {number} frameIndex
- * @param {LayerSpec} spec
- * @param {number} density
- * @returns {{frameMatrix: number[][], colors: number[][]}}
  * @memberof SemanticLayerGenerator
  */
 function generateNoiseFieldLayer(palette, layerSeedInt, frameIndex, spec, density) {
   const frameSeedInt = deriveFrameSeed(layerSeedInt, frameIndex);
   const rng = createRng(frameSeedInt);
-  const noise = createNoise2D(createRng(layerSeedInt)); // topology from layerSeed, not frameSeed
+  const noise = createNoise2D(createRng(layerSeedInt));
 
   const colors = [];
   const frameMatrix = [];
 
-  // Pre-pick a small set of colors for the base
   const baseColors = [];
-  const colorRng = createRng(layerSeedInt + 7); // stable color selection
+  const colorRng = createRng(layerSeedInt + 7);
   for (let i = 0; i < Math.min(palette.length, 4); i++) {
     baseColors.push(pickColor(palette, colorRng, spec.colorShift));
   }
-
-  // Register base colors
   const colorIndices = baseColors.map((c) => {
     colors.push(c);
     return colors.length - 1;
   });
 
   const noiseFreq = 0.15 + spec.noiseLevel * 0.3;
-  // Frame-level noise offset for smooth temporal variation
   const frameOffsetX = frameIndex * 0.05;
   const frameOffsetY = frameIndex * 0.03;
 
@@ -643,8 +250,7 @@ function generateNoiseFieldLayer(palette, layerSeedInt, frameIndex, spec, densit
     const row = [];
     for (let x = 0; x < GRID_DIM; x++) {
       const n = noise((x + frameOffsetX) * noiseFreq, (y + frameOffsetY) * noiseFreq);
-      // Map noise [-1,1] → color index
-      const normalized = (n + 1) / 2; // 0..1
+      const normalized = (n + 1) / 2;
       const idx = Math.min(colorIndices.length - 1, Math.floor(normalized * colorIndices.length));
       row.push(colorIndices[idx]);
     }
@@ -656,18 +262,9 @@ function generateNoiseFieldLayer(palette, layerSeedInt, frameIndex, spec, densit
 
 /**
  * Stamps a parametric shape onto a frame matrix at a given position/scale.
- * @param {number[][]} frameMatrix  - Mutable 24×24 matrix.
- * @param {number[][]} colors       - Mutable color palette.
- * @param {string} shapeKey
- * @param {Object} transform        - { x, y, scale, rotation }
- * @param {number[]} color           - RGBA color for this stamp.
- * @param {number} noiseLevel
- * @param {number} detailLevel
- * @param {string} seed              - String seed for shape generation.
  * @memberof SemanticLayerGenerator
  */
 function stampShape(frameMatrix, colors, shapeKey, transform, color, noiseLevel, detailLevel, seed) {
-  // Generate shape using intCoords for pixel-level placement
   const gridSize = Math.max(4, Math.round(GRID_DIM * transform.scale));
   const result = generateShape(shapeKey, {
     intCoords: [gridSize, gridSize],
@@ -677,7 +274,6 @@ function stampShape(frameMatrix, colors, shapeKey, transform, color, noiseLevel,
     count: Math.round(80 * detailLevel),
   });
 
-  // Register color
   const existingIdx = colors.findIndex(
     (c) => c[0] === color[0] && c[1] === color[1] && c[2] === color[2] && c[3] === color[3],
   );
@@ -689,7 +285,6 @@ function stampShape(frameMatrix, colors, shapeKey, transform, color, noiseLevel,
     colorIdx = colors.length - 1;
   }
 
-  // Compute offset to center the shape at (transform.x, transform.y)
   const offsetX = Math.round(transform.x * GRID_DIM - gridSize / 2);
   const offsetY = Math.round(transform.y * GRID_DIM - gridSize / 2);
 
@@ -708,40 +303,40 @@ function stampShape(frameMatrix, colors, shapeKey, transform, color, noiseLevel,
 
 /**
  * @typedef {Object} GenerateLayerOptions
- * @property {string}  itemId       - The item identifier (e.g. 'floor-desert').
- * @property {string}  seed         - Master seed string (e.g. 'fx-42').
- * @property {number}  frameIndex   - Current frame index (0-based).
- * @property {number}  [count=3]    - Number of shape elements per layer (multiplier).
- * @property {number}  [density=0.5]- Overall density factor (0..1).
+ * @property {string} itemId
+ * @property {string} seed
+ * @property {number} [frameIndex=0]
+ * @property {number} [count=3]
+ * @property {number} [density=0.5]
  * @memberof SemanticLayerGenerator
  */
 
 /**
  * @typedef {Object} GeneratedLayer
- * @property {string}   layerId       - Composite id: <itemId>-<layerKey>.
- * @property {string}   layerKey      - The layer name (e.g. 'dunes', 'rocks').
- * @property {Object[]} keys          - Content entries placed in this layer.
- * @property {number[][]} frameMatrix - 24×24 color-index matrix.
- * @property {number[][]} colors      - Shared color palette.
+ * @property {string}     layerId
+ * @property {string}     layerKey
+ * @property {Object[]}   keys
+ * @property {number[][]} frameMatrix
+ * @property {number[][]} colors
  * @memberof SemanticLayerGenerator
  */
 
 /**
  * @typedef {Object} GenerationResult
- * @property {string}   itemId
- * @property {string}   seed
- * @property {number}   frameIndex
+ * @property {string}         itemId
+ * @property {string}         seed
+ * @property {number}         frameIndex
  * @property {GeneratedLayer[]} layers
- * @property {number[][]} compositeFrameMatrix - Final composited 24×24 matrix.
- * @property {number[][]} compositeColors      - Final color palette.
+ * @property {number[][]}     compositeFrameMatrix
+ * @property {number[][]}     compositeColors
  * @memberof SemanticLayerGenerator
  */
 
 /**
  * Generates all semantic layers for a single frame of an item.
  *
- * Shape topology stays fixed across adjacent frames (determined by layerSeed);
- * only smooth per-frame transforms vary (derived from frameSeed + low-frequency noise).
+ * If the descriptor provides `customMultiFrameGenerator`, a stub result is
+ * returned — use `generateMultiFrame` for those descriptors.
  *
  * @param {GenerateLayerOptions} options
  * @returns {GenerationResult}
@@ -758,13 +353,23 @@ export function generateFrame(options) {
     );
   }
 
+  // Descriptors with a custom multi-frame generator: return a transparent stub.
+  if (typeof descriptor.customMultiFrameGenerator === 'function') {
+    return {
+      itemId,
+      seed,
+      frameIndex,
+      layers: [],
+      compositeFrameMatrix: Array.from({ length: GRID_DIM }, () => Array(GRID_DIM).fill(0)),
+      compositeColors: [[0, 0, 0, 0]],
+    };
+  }
+
   const { paletteHints, preferredShapes, layers: layerSpecs } = descriptor;
   const layerKeys = Object.keys(layerSpecs);
 
-  // Composite frame matrix (start transparent — color index 0 will be transparent)
-  const compositeColors = [[0, 0, 0, 0]]; // index 0 = transparent
+  const compositeColors = [[0, 0, 0, 0]];
   const compositeMatrix = Array.from({ length: GRID_DIM }, () => Array(GRID_DIM).fill(0));
-
   const generatedLayers = [];
 
   for (const layerKey of layerKeys) {
@@ -773,7 +378,6 @@ export function generateFrame(options) {
     const layerId = `${itemId}-${layerKey}`;
 
     if (spec.generator === 'noise-field') {
-      // ── Noise-field base layer ──
       const { frameMatrix, colors: layerColors } = generateNoiseFieldLayer(
         paletteHints,
         layerSeedInt,
@@ -782,7 +386,6 @@ export function generateFrame(options) {
         density,
       );
 
-      // Merge colors into composite palette
       const colorMap = {};
       for (let ci = 0; ci < layerColors.length; ci++) {
         const c = layerColors[ci];
@@ -796,13 +399,10 @@ export function generateFrame(options) {
         colorMap[ci] = found;
       }
 
-      // Stamp onto composite
       for (let y = 0; y < GRID_DIM; y++) {
         for (let x = 0; x < GRID_DIM; x++) {
           const mapped = colorMap[frameMatrix[y][x]];
-          if (mapped !== undefined && mapped !== 0) {
-            compositeMatrix[y][x] = mapped;
-          }
+          if (mapped !== undefined && mapped !== 0) compositeMatrix[y][x] = mapped;
         }
       }
 
@@ -814,7 +414,6 @@ export function generateFrame(options) {
         colors: layerColors,
       });
     } else if (spec.generator === 'shape') {
-      // ── Shape element layer ──
       const layerRng = createRng(layerSeedInt);
       const frameSeedInt = deriveFrameSeed(layerSeedInt, frameIndex);
       const frameRng = createRng(frameSeedInt);
@@ -822,31 +421,24 @@ export function generateFrame(options) {
 
       const effectiveCount = Math.max(1, Math.round(spec.count * count * density));
       const layerEntries = [];
-
-      // Frame matrix for this layer alone (for metadata)
       const layerMatrix = Array.from({ length: GRID_DIM }, () => Array(GRID_DIM).fill(-1));
       const layerColors = [];
 
       for (let ei = 0; ei < effectiveCount; ei++) {
-        // Sparsity check — deterministic per element
         if (layerRng() < spec.sparsity) continue;
 
-        // ── Shape selection (stable across frames) ──
         const shapeKey = pickShape(spec.shapes, preferredShapes, createRng(layerSeedInt + ei * 97));
 
-        // ── Base transform (stable across frames — from layerSeed) ──
         const baseRng = createRng(layerSeedInt + ei * 31 + 17);
         const baseX = baseRng();
         const baseY = baseRng();
         const baseScale = 0.15 + baseRng() * 0.25 + (baseRng() * 2 - 1) * spec.scaleVariance * 0.15;
         const baseRotation = (baseRng() * 2 - 1) * spec.rotationVariance;
 
-        // ── Per-frame smooth perturbation (temporal coherence) ──
         const fj = spec.frameJitter || 0;
         const fr = spec.frameRotation || 0;
         const fs = spec.frameScale || 0;
 
-        // Low-frequency noise indexed by element position for smooth frame-to-frame change
         const noiseX = frameNoise(ei * 2.5, frameIndex * 0.1) * fj;
         const noiseY = frameNoise(ei * 2.5 + 100, frameIndex * 0.1) * fj;
         const noiseRot = frameNoise(ei * 2.5 + 200, frameIndex * 0.1) * fr;
@@ -859,48 +451,23 @@ export function generateFrame(options) {
           rotation: baseRotation + noiseRot,
         };
 
-        // ── Color (stable per element, small per-frame shift) ──
         const colorRng = createRng(layerSeedInt + ei * 53 + 7);
         const baseColor = pickColor(paletteHints, colorRng, spec.colorShift);
-
-        // Small per-frame color shift for shimmer
         const frameColorShift = Math.round(frameNoise(ei * 3.7 + 400, frameIndex * 0.08) * 3);
         const color = baseColor.map((ch, ci) => (ci < 3 ? clamp(ch + frameColorShift, 0, 255) : ch));
 
-        // ── Shape seed (stable topology) ──
         const shapeSeed = `${seed}:${itemId}:${layerKey}:${ei}`;
 
-        // Stamp onto composite matrix
         stampShape(
-          compositeMatrix,
-          compositeColors,
-          shapeKey,
-          transform,
-          color,
-          spec.noiseLevel * (spec.jitter + 0.5),
-          spec.detailLevel,
-          shapeSeed,
+          compositeMatrix, compositeColors, shapeKey, transform, color,
+          spec.noiseLevel * (spec.jitter + 0.5), spec.detailLevel, shapeSeed,
         );
-
-        // Also stamp onto layer-local matrix for metadata
         stampShape(
-          layerMatrix,
-          layerColors,
-          shapeKey,
-          transform,
-          color,
-          spec.noiseLevel * 0.5,
-          spec.detailLevel,
-          shapeSeed,
+          layerMatrix, layerColors, shapeKey, transform, color,
+          spec.noiseLevel * 0.5, spec.detailLevel, shapeSeed,
         );
 
-        layerEntries.push({
-          type: 'shape',
-          shapeKey,
-          transform,
-          color,
-          shapeSeed,
-        });
+        layerEntries.push({ type: 'shape', shapeKey, transform, color, shapeSeed });
       }
 
       generatedLayers.push({
@@ -911,6 +478,7 @@ export function generateFrame(options) {
         colors: layerColors,
       });
     }
+    // 'template-zone' handled by customMultiFrameGenerator — skip here
   }
 
   return {
@@ -925,32 +493,34 @@ export function generateFrame(options) {
 
 /* ═══════════════════════════════════════════════════════════════════════════
  *  MULTI-FRAME GENERATION
- *  Generates multiple consecutive frames with temporal coherence.
  * ═══════════════════════════════════════════════════════════════════════════ */
 
 /**
  * @typedef {Object} MultiFrameResult
- * @property {string} itemId
- * @property {string} seed
- * @property {number} frameCount
+ * @property {string}         itemId
+ * @property {string}         seed
+ * @property {number}         frameCount
  * @property {GenerationResult[]} frames
- * @property {Object} objectLayerRenderFramesData - Ready for ObjectLayerEngine.createObjectLayerDocuments.
- * @property {Object} objectLayerData             - Ready for ObjectLayerEngine.createObjectLayerDocuments.
+ * @property {Object}         objectLayerRenderFramesData
+ * @property {Object}         objectLayerData
  * @memberof SemanticLayerGenerator
  */
 
 /**
- * Generates N consecutive frames for an item-id, producing data structures
- * compatible with ObjectLayerEngine document creation.
+ * Generates N consecutive frames for an item-id.
+ *
+ * If the matched descriptor provides `customMultiFrameGenerator`, it is invoked
+ * directly and its result is returned unchanged — allowing category submodules
+ * (e.g. skin) to fully control frame layout and direction assignment.
  *
- * @param {Object} options
+ * @param {Object}  options
  * @param {string}  options.itemId
  * @param {string}  options.seed
- * @param {number}  [options.frameCount=1]     - Number of frames to generate.
- * @param {number}  [options.startFrame=0]     - Starting frame index.
- * @param {number}  [options.count=3]          - Shape element count multiplier.
- * @param {number}  [options.density=0.5]      - Density factor.
- * @param {number}  [options.frameDuration=250] - ms per frame.
+ * @param {number}  [options.frameCount=1]
+ * @param {number}  [options.startFrame=0]
+ * @param {number}  [options.count=3]
+ * @param {number}  [options.density=0.5]
+ * @param {number}  [options.frameDuration=250]
  * @returns {MultiFrameResult}
  * @memberof SemanticLayerGenerator
  */
@@ -965,22 +535,17 @@ export function generateMultiFrame(options) {
     );
   }
 
-  const frames = [];
-  let mergedColors = [[0, 0, 0, 0]]; // index 0 = transparent
+  // ── Dispatch to custom generator ─────────────────────────────────────────
+  if (typeof descriptor.customMultiFrameGenerator === 'function') {
+    return descriptor.customMultiFrameGenerator(options, descriptor);
+  }
 
-  // First pass: generate all frames
+  // ── Default shape / noise-field pipeline ─────────────────────────────────
+  const frames = [];
   for (let fi = 0; fi < frameCount; fi++) {
-    const result = generateFrame({
-      itemId,
-      seed,
-      frameIndex: startFrame + fi,
-      count,
-      density,
-    });
-    frames.push(result);
+    frames.push(generateFrame({ itemId, seed, frameIndex: startFrame + fi, count, density }));
   }
 
-  // Second pass: unify color palettes across all frames
   const globalColors = [[0, 0, 0, 0]];
   const frameMappings = [];
 
@@ -988,7 +553,9 @@ export function generateMultiFrame(options) {
     const mapping = {};
     for (let ci = 0; ci < frame.compositeColors.length; ci++) {
       const c = frame.compositeColors[ci];
-      let found = globalColors.findIndex((gc) => gc[0] === c[0] && gc[1] === c[1] && gc[2] === c[2] && gc[3] === c[3]);
+      let found = globalColors.findIndex(
+        (gc) => gc[0] === c[0] && gc[1] === c[1] && gc[2] === c[2] && gc[3] === c[3],
+      );
       if (found < 0) {
         globalColors.push([...c]);
         found = globalColors.length - 1;
@@ -998,14 +565,11 @@ export function generateMultiFrame(options) {
     frameMappings.push(mapping);
   }
 
-  // Third pass: remap frame matrices to global palette
   const remappedFrames = frames.map((frame, fi) => {
     const mapping = frameMappings[fi];
     return frame.compositeFrameMatrix.map((row) => row.map((ci) => (mapping[ci] !== undefined ? mapping[ci] : 0)));
   });
 
-  // Build objectLayerRenderFramesData structure
-  // For floor types: use direction '08' (down_idle / default_idle / none_idle)
   const objectLayerRenderFramesData = {
     frame_duration: frameDuration,
     is_stateless: descriptor.itemType === 'floor',
@@ -1013,7 +577,6 @@ export function generateMultiFrame(options) {
     colors: globalColors,
   };
 
-  // Assign frames to directions
   const directionMappings = {
     floor: [['down_idle', 'none_idle', 'default_idle']],
     skin: [
@@ -1028,14 +591,12 @@ export function generateMultiFrame(options) {
   };
 
   const dirGroups = directionMappings[descriptor.itemType] || directionMappings.floor;
-
   for (const dirGroup of dirGroups) {
     for (const dirName of dirGroup) {
       objectLayerRenderFramesData.frames[dirName] = [...remappedFrames];
     }
   }
 
-  // Build objectLayerData
   const objectLayerData = {
     data: {
       item: {