@underpostnet/cyberia 3.3.73 → 3.3.77

package/src/projects/cyberia/atlas-sprite-sheet-generator.js

@@ -5,14 +5,28 @@
  * @namespace CyberiaAtlasSpriteSheetGenerator
  */
 
-import fs from 'fs-extra';
-import path from 'path';
-import sharp from 'sharp';
 import { Jimp, rgbaToInt } from 'jimp';
 import { loggerFactory } from '../../server/ops/logger.js';
+import { getKeyframeDirectionsByCode } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
 
 const logger = loggerFactory(import.meta);
 
+/** Direction code of the still an item is previewed by: down idle. */
+export const IDLE_PREVIEW_DIRECTION_CODE = '08';
+
+/**
+ * Pixels per cell of the human-resolution atlas, when no factor is given.
+ * @memberof CyberiaAtlasSpriteSheetGenerator
+ */
+export const DEFAULT_ATLAS_UPSCALE_FACTOR = 20;
+
+/**
+ * Pixels per cell of the minified atlas. The client runtime downloads this one,
+ * so it stays at one pixel per cell.
+ * @memberof CyberiaAtlasSpriteSheetGenerator
+ */
+const MINIFY_CELL_PIXEL_DIM = 1;
+
 /**
  * @typedef {Object} AtlasFrame
  * @property {number} x - X position in atlas
@@ -38,7 +52,7 @@ export class AtlasSpriteSheetGenerator {
    * @returns {Promise<Jimp>} The generated image
    * @memberof CyberiaAtlasSpriteSheetGenerator
    */
-  static async frameMatrixToImage(frameMatrix, colors, cellPixelDim = 20) {
+  static async frameMatrixToImage(frameMatrix, colors, cellPixelDim = 1) {
     if (!frameMatrix || frameMatrix.length === 0 || frameMatrix[0].length === 0) {
       throw new Error('Invalid frame matrix');
     }
@@ -79,59 +93,47 @@ export class AtlasSpriteSheetGenerator {
    * @memberof CyberiaAtlasSpriteSheetGenerator
    */
   static calculateOptimalDimension(frameImages) {
-    if (!frameImages || frameImages.length === 0) {
-      logger.warn('No frames provided for dimension calculation, using default 2048');
-      return 2048;
-    }
-
-    // Get max frame dimensions with defensive checks
-    const widths = frameImages.map((f) => f.width).filter((w) => !isNaN(w) && w > 0);
-    const heights = frameImages.map((f) => f.height).filter((h) => !isNaN(h) && h > 0);
-
-    if (widths.length === 0 || heights.length === 0) {
-      logger.warn('Invalid frame dimensions found, using default 2048');
-      return 2048;
+    if (
+      !frameImages?.length ||
+      frameImages.some(
+        ({ width, height }) => !Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0,
+      )
+    ) {
+      throw new Error('Invalid frame dimensions');
     }
-
-    const maxFrameWidth = Math.max(...widths);
-    const maxFrameHeight = Math.max(...heights);
-
-    logger.info(`Frame dimensions: max ${maxFrameWidth}x${maxFrameHeight}, count: ${frameImages.length}`);
-
-    // Calculate grid layout (try to make it roughly square)
-    const frameCount = frameImages.length;
-    const cols = Math.ceil(Math.sqrt(frameCount));
-    const rows = Math.ceil(frameCount / cols);
-
-    // Calculate required dimensions
-    const requiredWidth = cols * maxFrameWidth;
-    const requiredHeight = rows * maxFrameHeight;
-    const requiredDim = Math.max(requiredWidth, requiredHeight);
-
-    logger.info(`Grid layout: ${cols}x${rows}, required: ${requiredWidth}x${requiredHeight}`);
-
-    // Round up to next power of 2
-    const optimalDim = AtlasSpriteSheetGenerator.nextPowerOf2(requiredDim);
-
-    // Ensure minimum 1024, maximum 8192
-    const finalDim = Math.max(1024, Math.min(8192, optimalDim));
-
-    logger.info(`Calculated optimal dimension: ${finalDim}x${finalDim}`);
-
-    return finalDim;
+    const cols = Math.ceil(Math.sqrt(frameImages.length));
+    const rows = Math.ceil(frameImages.length / cols);
+    return AtlasSpriteSheetGenerator.nextPowerOf2(
+      Math.max(
+        cols * Math.max(...frameImages.map((frame) => frame.width)),
+        rows * Math.max(...frameImages.map((frame) => frame.height)),
+      ),
+    );
   }
 
   /**
-   * Consolidates all frames from an ObjectLayerRenderFrames into a single atlas sprite sheet
+   * Consolidates all frames of an ObjectLayerRenderFrames into one atlas sprite sheet.
+   *
+   * One packing produces two renders of the same layout: `minifyBuffer` at one
+   * pixel per cell, which the client runtime downloads, and `buffer` at
+   * `upscaleFactor` pixels per cell for human viewing. `metadata` describes the
+   * minified render, so atlas metadata and the served blob always agree.
+   *
    * @static
    * @param {Object} objectLayerRenderFrames - The ObjectLayerRenderFrames document
    * @param {string} itemKey - The item key for the atlas
-   * @param {number} [cellPixelDim=20] - Pixel dimension per cell
+   * @param {number} [upscaleFactor=DEFAULT_ATLAS_UPSCALE_FACTOR] - Pixels per cell of the human-resolution render
    * @param {number} [maxAtlasDim=null] - Maximum atlas dimension (auto-calculated if null)
-   * @returns {Promise<{buffer: Buffer, metadata: Object}>} Atlas buffer and metadata
+   * @returns {Promise<{buffer: Buffer, minifyBuffer: Buffer, metadata: Object}>} Both renders and the shared metadata
    * @memberof CyberiaAtlasSpriteSheetGenerator
    */
-  static async generateAtlas(objectLayerRenderFrames, itemKey, cellPixelDim = 20, maxAtlasDim = null) {
+  static async generateAtlas(
+    objectLayerRenderFrames,
+    itemKey,
+    upscaleFactor = DEFAULT_ATLAS_UPSCALE_FACTOR,
+    maxAtlasDim = null,
+  ) {
+    if (!Number.isInteger(upscaleFactor) || upscaleFactor < 1) throw new Error('Invalid pixel scale');
     const { frames, colors } = objectLayerRenderFrames;
     const frameDuration = Number(objectLayerRenderFrames?.frame_duration);
 
@@ -157,7 +159,7 @@ export class AtlasSpriteSheetGenerator {
       'none_idle',
     ];
 
-    // Generate all frame images
+    // The packing works on the minified render; the upscaled render reuses its layout.
     const frameImages = [];
 
     for (const direction of directionOrder) {
@@ -167,10 +169,15 @@ export class AtlasSpriteSheetGenerator {
       for (let frameIndex = 0; frameIndex < directionFrames.length; frameIndex++) {
         const frameMatrix = directionFrames[frameIndex];
         try {
-          const frameImage = await AtlasSpriteSheetGenerator.frameMatrixToImage(frameMatrix, colors, cellPixelDim);
+          const frameImage = await AtlasSpriteSheetGenerator.frameMatrixToImage(
+            frameMatrix,
+            colors,
+            MINIFY_CELL_PIXEL_DIM,
+          );
 
           frameImages.push({
             image: frameImage,
+            frameMatrix,
             direction,
             frameIndex,
             width: frameImage.bitmap.width,
@@ -194,10 +201,8 @@ export class AtlasSpriteSheetGenerator {
       );
     }
 
-    // Validate maxAtlasDim
-    if (isNaN(maxAtlasDim) || maxAtlasDim <= 0) {
-      logger.error(`Invalid maxAtlasDim: ${maxAtlasDim}, using default 2048`);
-      maxAtlasDim = 2048;
+    if (!Number.isInteger(maxAtlasDim) || maxAtlasDim <= 0 || maxAtlasDim > 4096) {
+      throw new Error('Atlas dimension must be between 1 and 4096');
     }
 
     // Simple grid packing algorithm
@@ -215,43 +220,29 @@ export class AtlasSpriteSheetGenerator {
       );
     }
 
-    // Create atlas canvas
-    const atlasImage = new Jimp({ width: atlasWidth, height: atlasHeight, color: 0x00000000 });
+    const minifyImage = new Jimp({ width: atlasWidth, height: atlasHeight, color: 0x00000000 });
+    const upscaledImage = new Jimp({
+      width: atlasWidth * upscaleFactor,
+      height: atlasHeight * upscaleFactor,
+      color: 0x00000000,
+    });
 
-    // Build metadata structure first
     const frameMetadata = {};
 
-    // Composite frames onto atlas
-    let loggedCount = 0;
     for (const packedFrame of packedFrames) {
-      const { image, x, y, direction, frameIndex } = packedFrame;
-
-      // Log first few frames for debugging
-      if (loggedCount < 3) {
-        logger.info(
-          `Frame ${loggedCount + 1}: ${direction}[${frameIndex}] → (${x},${y}) ${image.bitmap.width}x${image.bitmap.height}`,
-        );
-        loggedCount++;
-      }
-
-      // Manually copy pixels to ensure correct positioning
-      for (let srcY = 0; srcY < image.bitmap.height; srcY++) {
-        for (let srcX = 0; srcX < image.bitmap.width; srcX++) {
-          const destX = x + srcX;
-          const destY = y + srcY;
+      const { image, frameMatrix, x, y, direction, frameIndex } = packedFrame;
 
-          // Skip if out of bounds
-          if (destX >= atlasWidth || destY >= atlasHeight) continue;
+      AtlasSpriteSheetGenerator.blitFrame(minifyImage, image, x, y);
 
-          // Get pixel color from source image
-          const color = image.getPixelColor(srcX, srcY);
-
-          // Set pixel in atlas at destination position
-          atlasImage.setPixelColor(color, destX, destY);
-        }
+      // The same cell grid at a larger scale, so the upscaled atlas is an exact
+      // multiple of the layout the metadata describes.
+      if (upscaleFactor > MINIFY_CELL_PIXEL_DIM) {
+        const upscaledFrame = await AtlasSpriteSheetGenerator.frameMatrixToImage(frameMatrix, colors, upscaleFactor);
+        AtlasSpriteSheetGenerator.blitFrame(upscaledImage, upscaledFrame, x * upscaleFactor, y * upscaleFactor);
+      } else {
+        AtlasSpriteSheetGenerator.blitFrame(upscaledImage, image, x, y);
       }
 
-      // Store metadata in correct order
       if (!frameMetadata[direction]) {
         frameMetadata[direction] = [];
       }
@@ -265,19 +256,80 @@ export class AtlasSpriteSheetGenerator {
       };
     }
 
-    // Convert to PNG buffer
-    const buffer = await atlasImage.getBuffer('image/png');
-
     const metadata = {
       itemKey,
       atlasWidth,
       atlasHeight,
-      cellPixelDim,
+      cellPixelDim: MINIFY_CELL_PIXEL_DIM,
+      upscaleFactor,
       frame_duration: Number.isFinite(frameDuration) ? frameDuration : 100,
       frames: frameMetadata,
     };
 
-    return { buffer, metadata };
+    return {
+      buffer: await upscaledImage.getBuffer('image/png'),
+      minifyBuffer: await minifyImage.getBuffer('image/png'),
+      metadata,
+    };
+  }
+
+  /**
+   * The frame an item is previewed by: the first frame of the first down-idle keyframe the
+   * atlas carries, or the first frame of any direction when it has none.
+   *
+   * @static
+   * @param {Object} metadata - Atlas metadata as {@link generateAtlas} returns it.
+   * @returns {{x:number,y:number,width:number,height:number}|null} Frame box in minified cells.
+   * @memberof CyberiaAtlasSpriteSheetGenerator
+   */
+  static idlePreviewFrame(metadata) {
+    const frames = metadata?.frames ?? {};
+    const preferred = getKeyframeDirectionsByCode(IDLE_PREVIEW_DIRECTION_CODE);
+    for (const direction of [...preferred, ...Object.keys(frames)]) {
+      const frame = frames[direction]?.[0];
+      if (frame) return frame;
+    }
+    return null;
+  }
+
+  /**
+   * Cuts the idle-preview still out of the human-resolution render, using the same layout
+   * `metadata.frames` describes for the minified one scaled by `metadata.upscaleFactor`.
+   *
+   * @static
+   * @param {Buffer} buffer - PNG bytes of the human-resolution atlas render.
+   * @param {Object} metadata - Atlas metadata as {@link generateAtlas} returns it.
+   * @returns {Promise<Buffer|null>} PNG bytes of the still, or null when the atlas has no frame.
+   * @memberof CyberiaAtlasSpriteSheetGenerator
+   */
+  static async idlePreviewFromAtlas(buffer, metadata) {
+    const frame = AtlasSpriteSheetGenerator.idlePreviewFrame(metadata);
+    if (!frame) return null;
+    const scale = Number(metadata.upscaleFactor) || 1;
+    const image = await Jimp.read(buffer);
+    image.crop({ x: frame.x * scale, y: frame.y * scale, w: frame.width * scale, h: frame.height * scale });
+    return await image.getBuffer('image/png');
+  }
+
+  /**
+   * Copies a frame image onto an atlas canvas at the given origin.
+   * @static
+   * @param {Jimp} atlasImage - Destination atlas canvas.
+   * @param {Jimp} frameImage - Source frame image.
+   * @param {number} originX - Destination X origin.
+   * @param {number} originY - Destination Y origin.
+   * @returns {void}
+   * @memberof CyberiaAtlasSpriteSheetGenerator
+   */
+  static blitFrame(atlasImage, frameImage, originX, originY) {
+    for (let srcY = 0; srcY < frameImage.bitmap.height; srcY++) {
+      for (let srcX = 0; srcX < frameImage.bitmap.width; srcX++) {
+        const destX = originX + srcX;
+        const destY = originY + srcY;
+        if (destX >= atlasImage.bitmap.width || destY >= atlasImage.bitmap.height) continue;
+        atlasImage.setPixelColor(frameImage.getPixelColor(srcX, srcY), destX, destY);
+      }
+    }
   }
 
   /**
@@ -302,7 +354,6 @@ export class AtlasSpriteSheetGenerator {
     let rowHeight = 0;
     let maxWidth = 0;
     let totalHeight = 0;
-    let exceedsCount = 0;
 
     for (const frame of sortedFrames) {
       // Check if frame fits in current row
@@ -313,9 +364,8 @@ export class AtlasSpriteSheetGenerator {
         rowHeight = 0;
       }
 
-      // Check if we exceed max height
-      if (currentY + frame.height > maxDim) {
-        exceedsCount++;
+      if (frame.width > maxDim || currentY + frame.height > maxDim) {
+        throw new Error(`Frames exceed atlas dimension ${maxDim}`);
       }
 
       packedFrames.push({
@@ -330,20 +380,8 @@ export class AtlasSpriteSheetGenerator {
       totalHeight = Math.max(totalHeight, currentY + frame.height);
     }
 
-    // Log once if frames exceeded dimensions
-    if (exceedsCount > 0) {
-      const recommendedSize = AtlasSpriteSheetGenerator.nextPowerOf2(Math.max(maxWidth, totalHeight));
-      logger.warn(
-        `${exceedsCount} frames exceed atlas dimension (${maxDim}x${maxDim}). ` +
-          `Actual required: ${maxWidth}x${totalHeight}. ` +
-          `Recommended: --to-atlas-sprite-sheet ${recommendedSize}`,
-      );
-    }
-
-    // Use maxDim as the atlas dimensions (already power-of-2 and optimal from auto-calculation)
-    // If all frames fit within a smaller power-of-2, use that instead
-    const atlasWidth = maxDim;
-    const atlasHeight = maxDim;
+    const atlasWidth = maxWidth;
+    const atlasHeight = totalHeight;
 
     return {
       packedFrames,
@@ -369,45 +407,4 @@ export class AtlasSpriteSheetGenerator {
     n |= n >> 16;
     return n + 1;
   }
-
-  /**
-   * Generates atlas and saves to file system
-   * @static
-   * @param {Object} objectLayerRenderFrames - The ObjectLayerRenderFrames document
-   * @param {string} itemKey - The item key for the atlas
-   * @param {string} outputPath - Output file path
-   * @param {number} [cellPixelDim=20] - Pixel dimension per cell
-   * @param {number} [maxAtlasDim=null] - Maximum atlas dimension (auto-calculated if null)
-   * @returns {Promise<{buffer: Buffer, metadata: Object, outputPath: string}>}
-   * @memberof CyberiaAtlasSpriteSheetGenerator
-   */
-  static async generateAtlasToFile(
-    objectLayerRenderFrames,
-    itemKey,
-    outputPath,
-    cellPixelDim = 20,
-    maxAtlasDim = null,
-  ) {
-    const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
-      objectLayerRenderFrames,
-      itemKey,
-      cellPixelDim,
-      maxAtlasDim,
-    );
-
-    await fs.ensureDir(path.dirname(outputPath));
-    await fs.writeFile(outputPath, buffer);
-
-    logger.info(`Atlas sprite sheet generated: ${outputPath}`);
-
-    return { buffer, metadata, outputPath };
-  }
 }
-
-// Export convenience functions
-export const generateAtlas = AtlasSpriteSheetGenerator.generateAtlas;
-export const generateAtlasToFile = AtlasSpriteSheetGenerator.generateAtlasToFile;
-export const frameMatrixToImage = AtlasSpriteSheetGenerator.frameMatrixToImage;
-export const packFramesGrid = AtlasSpriteSheetGenerator.packFramesGrid;
-export const nextPowerOf2 = AtlasSpriteSheetGenerator.nextPowerOf2;
-export const calculateOptimalDimension = AtlasSpriteSheetGenerator.calculateOptimalDimension;