cyberia 2.96.1 → 2.98.3

package/.dockerignore

@@ -3,7 +3,6 @@
 /engine-private
 /conf
 /tmp
-/bkt
 /logs
 /build
 /.env
@@ -12,4 +11,4 @@
 /grafana_data
 /manifests
 .nyc_output
-.cache
+.cache

package/.env.development

@@ -35,12 +35,9 @@ MAAS_ADMIN_EMAIL=admin@default.net
 MAAS_ADMIN_PASS=changethis
 TFTP_ROOT=changethis
 NETMASK=255.255.255.0
-RPI4_INTERFACE_NAME=changethis
-RPI4_IP=192.168.1.192
 MAAS_DNS=8.8.8.8
 MAAS_NTP_SERVER=changethis
 NFS_EXPORT_PATH=changethis
-RPI4_MAC_ADDRESS=changethis
 NVIDIA_API_KEY=changethis
 DEFAULT_ADMIN_EMAIL=admin@default.net
 DEFAULT_ADMIN_PASSWORD=changethis

package/.env.production

@@ -36,12 +36,9 @@ MAAS_ADMIN_EMAIL=admin@default.net
 MAAS_ADMIN_PASS=changethis
 TFTP_ROOT=changethis
 NETMASK=255.255.255.0
-RPI4_INTERFACE_NAME=changethis
-RPI4_IP=192.168.1.192
 MAAS_DNS=8.8.8.8
 MAAS_NTP_SERVER=changethis
 NFS_EXPORT_PATH=changethis
-RPI4_MAC_ADDRESS=changethis
 NVIDIA_API_KEY=changethis
 DEFAULT_ADMIN_EMAIL=admin@default.net
 DEFAULT_ADMIN_PASSWORD=changethis

package/.env.test

@@ -35,12 +35,9 @@ MAAS_ADMIN_EMAIL=admin@default.net
 MAAS_ADMIN_PASS=changethis
 TFTP_ROOT=changethis
 NETMASK=255.255.255.0
-RPI4_INTERFACE_NAME=changethis
-RPI4_IP=192.168.1.192
 MAAS_DNS=8.8.8.8
 MAAS_NTP_SERVER=changethis
 NFS_EXPORT_PATH=changethis
-RPI4_MAC_ADDRESS=changethis
 NVIDIA_API_KEY=changethis
 DEFAULT_ADMIN_EMAIL=admin@default.net
 DEFAULT_ADMIN_PASSWORD=changethis

package/.github/workflows/engine-cyberia.ci.yml

@@ -13,7 +13,7 @@ jobs:
     # if: github.repository == 'underpostnet/engine' && startsWith(github.event.head_commit.message, 'ci(engine-cyberia-repo-build)')
     name: Update github repo package Jobs
     env:
-      SYNC: ${{ startsWith(github.event.workflow_run.head_commit.message, 'ci(package-pwa-microservices-template-sync-dd-cyberia)') }}
+      SYNC: ${{ startsWith(github.event.workflow_run.head_commit.message, 'ci(package-pwa-microservices-template-sync-engine-cyberia)') }}
     runs-on: ubuntu-latest
     container:
       image: quay.io/rockylinux/rockylinux:9

package/.prettierignore

@@ -2,7 +2,6 @@
 /public
 /conf
 /tmp
-/bkt
 /logs
 /build
 /.env
@@ -10,4 +9,4 @@
 /prometheus_data
 /grafana_data
 .nyc_output
-.cache
+.cache

package/.vscode/settings.json

@@ -4,10 +4,10 @@
   "explorer.compactFolders": false,
   "javascript.preferences.importModuleSpecifierEnding": "js",
   "[javascript]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
   },
   "[python]": {
-    "editor.defaultFormatter": "ms-python.python"
+    "editor.defaultFormatter": "ms-python.python",
   },
   "cSpell.words": [
     "adminer",
@@ -40,7 +40,6 @@
     "htmls",
     "inet",
     "inlt",
-    "ipfs",
     "Itemledger",
     "jsonld",
     "lampp",
@@ -72,16 +71,16 @@
     "webroot",
     "xampp",
     "xfwd",
-    "youtu"
+    "youtu",
   ],
   "[php]": {
-    "editor.defaultFormatter": "bmewburn.vscode-intelephense-client"
+    "editor.defaultFormatter": "bmewburn.vscode-intelephense-client",
   },
   "[xml]": {
-    "editor.defaultFormatter": "redhat.vscode-xml"
+    "editor.defaultFormatter": "redhat.vscode-xml",
   },
 
   "files.watcherExclude": {
-    "**/target": true
-  }
+    "**/target": true,
+  },
 }

package/README.md

@@ -14,17 +14,21 @@
 
 This Command Line Interface (CLI) is a core tool for the **Cyberia Network Object Layer Engine**, specifically designed for processing, generating, and managing game assets, primarily **Object Layer** elements like skins, floors, and weapons.
 
-It handles image asset quantization, generates data matrices and color palettes, and persists the resulting structured data into the game's database.
+It handles image asset quantization, generates data matrices and color palettes, creates separate render frame documents, and persists the resulting structured data into the game's database with top-level references to render frames and atlas sprite sheets.
 
 ## What this tool does
 
-The CLI scans the local asset folders (`./src/client/public/cyberia/assets/{type}/{id}/{direction}/{frame}`), quantizes images to a tile matrix and color palette, and persists the resulting object-layer documents to your configured MongoDB. It also supports reconstructing a visual PNG from the stored matrix for inspection.
+The CLI scans the local asset folders (`./src/client/public/cyberia/assets/{type}/{id}/{direction}/{frame}`), quantizes images to a tile matrix and color palette, creates separate ObjectLayerRenderFrames documents, and persists the resulting object-layer documents with references to your configured MongoDB. It also supports reconstructing a visual PNG from the stored matrix for inspection.
 
 Key features:
 
 - Walks the asset directory structure and processes PNG/GIF files.
 - Produces `frame_matrix` and `map_color` arrays from images.
-- Saves processed objects to the `ObjectLayer` model in MongoDB.
+- 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.
 
 ## Getting Started
@@ -66,8 +70,139 @@ cyberia ol --import all
 
 ## Visualize a processed frame
 
-Reconstructs and opens a PNG from the processed frame data. The input format is `objectLayerId_direction_frameIndex`.
+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]`.
 
 ```bash
-cyberia ol --import skin --show-frame anon_08_0
+# Show frame with default direction and frame (08_0)
+cyberia ol anon --show-frame
+
+# Show specific direction and frame
+cyberia ol anon --show-frame 08_0
+
+# Show different directions
+cyberia ol anon --show-frame 02_0  # up_idle
+cyberia ol anon --show-frame 04_1  # left_idle (second frame)
+```
+
+**Valid direction codes:**
+- `08`: down_idle, none_idle, default_idle
+- `18`: down_walking
+- `02`: up_idle
+- `12`: up_walking
+- `04`: left_idle, up_left_idle, down_left_idle
+- `14`: left_walking, up_left_walking, down_left_walking
+- `06`: right_idle, up_right_idle, down_right_idle
+- `16`: right_walking, up_right_walking, down_right_walking
+
+This command:
+- Finds the ObjectLayer by item-id
+- Loads the associated ObjectLayerRenderFrames document
+- Reconstructs the PNG from the stored `frame_matrix` and `map_color`
+- Saves it temporarily to disk as `{item-id}_{direction}_{frame}.png`
+- Opens it with Firefox for visual inspection
+
+### Generate Atlas Sprite Sheet
+
+Consolidates all frames (8 directions, multiple modes) from an object layer's render frames into a single optimized PNG atlas with metadata.
+
+```bash
+# Generate atlas sprite sheet with auto-calculated dimensions (recommended)
+cyberia ol anon --to-atlas-sprite-sheet
+
+# Generate atlas with custom dimensions (manual override)
+cyberia ol anon --to-atlas-sprite-sheet 4096
+
+
+```
+
+This command:
+- Finds the ObjectLayer by item-id or MongoDB `_id`
+- Loads the associated ObjectLayerRenderFrames document
+- **Auto-calculates optimal atlas dimensions** based on total frame count (8 directions × all animation modes)
+- Generates a consolidated PNG with all animation frames properly arranged
+- Stores the PNG in the File collection
+- Creates/updates an AtlasSpriteSheet document with frame positions
+- Updates the ObjectLayer with top-level `atlasSpriteSheetId` reference
+- Uses power-of-2 dimensions for GPU efficiency
+
+**Atlas Dimension Calculation:**
+- **Auto (default)**: Dynamically calculates optimal size based on:
+  - Total number of frames across all directions and modes
+  - Individual frame dimensions
+  - Grid layout to minimize wasted space
+  - Power-of-2 optimization (1024, 2048, 4096, etc.)
+- **Manual override**: Specify exact dimension (e.g., `--to-atlas-sprite-sheet 4096`)
+
+**Common Atlas Sizes:**
+- **1024x1024**: ~6-10 frames
+- **2048x2048**: ~20-40 frames (typical for character sprites)
+- **4096x4096**: ~80-160 frames (complex animations)
+- **8192x8192**: Maximum, for extreme cases
+
+The tool automatically warns if frames exceed the specified dimension and suggests a larger size.
+
+### View Atlas Sprite Sheet
+
+Opens the consolidated atlas sprite sheet PNG for inspection.
+
+```bash
+# Show atlas sprite sheet by item-id
+cyberia ol anon --show-atlas-sprite-sheet
+
+```
+
+This command:
+- Finds the ObjectLayer by item-id
+- Retrieves the associated AtlasSpriteSheet via top-level `atlasSpriteSheetId` or by matching `metadata.itemKey`
+- Saves it temporarily to disk
+- Opens it with Firefox for visual inspection
+- Displays atlas dimensions in the console
+
+## Common Workflows
+
+### Complete Asset Processing Pipeline
+
+Process assets from source files through to atlas generation:
+
+```bash
+# 1. Import object layers from asset directories
+cyberia ol --import skin
+
+# 2. Verify a specific frame was imported correctly
+cyberia ol anon --show-frame 08_0
+
+# 3. Generate optimized atlas sprite sheet
+cyberia ol anon --to-atlas-sprite-sheet
+
+# 4. View the generated atlas
+cyberia ol anon --show-atlas-sprite-sheet
+```
+
+### Debugging Asset Issues
+
+```bash
+# Check if frame data is correct for all directions
+cyberia ol anon --show-frame 08_0  # down_idle
+cyberia ol anon --show-frame 02_0  # up_idle
+cyberia ol anon --show-frame 04_0  # left_idle
+cyberia ol anon --show-frame 06_0  # right_idle
+
+# Verify walking animations
+cyberia ol anon --show-frame 18_0  # down_walking
+cyberia ol anon --show-frame 12_0  # up_walking
+cyberia ol anon --show-frame 14_0  # left_walking
+cyberia ol anon --show-frame 16_0  # right_walking
+```
+
+### Working with Multiple Items
+
+```bash
+# Import multiple types at once
+cyberia ol --import skin,floor,weapon
+
+# Process individual items
+cyberia ol sword --show-frame 08_0
+cyberia ol sword --to-atlas-sprite-sheet
+cyberia ol shield --show-frame 08_0
+cyberia ol shield --to-atlas-sprite-sheet
 ```

package/baremetal/commission-workflows.json

@@ -1,10 +1,40 @@
 {
-  "rpi4mb": {
-    "menuentryStr": "UNDERPOST.NET UEFI/GRUB/MAAS RPi4 commissioning (ARM64)",
-    "systemProvisioning": "ubuntu",
-    "kernelLibVersion": "6.8.0-41-generic",
+  "rpi4mbarm64-iso-ram": {
+    "type": "iso-ram",
+    "osIdLike": "debian ubuntu",
+    "isoUrl": "https://cdimage.ubuntu.com/releases/24.04/release/ubuntu-24.04.3-live-server-arm64.iso",
+    "tftpPrefix": "rpi4mb",
+    "bootstrapHttpServerPort": 8888,
+    "menuentryStr": "UNDERPOST.NET UEFI/GRUB/MAAS RPi4 ISO-RAM commissioning (ARM64)",
+    "networkInterfaceName": "enabcm6e4ei0",
+    "chronyc": {
+      "timezone": "America/Santiago",
+      "chronyConfPath": "/etc/chrony/chrony.conf"
+    },
+    "firmwares": [
+      {
+        "url": "https://github.com/pftf/RPi4/releases/download/v1.41/RPi4_UEFI_Firmware_v1.41.zip",
+        "gateway": "192.168.1.1",
+        "subnet": "255.255.255.0"
+      }
+    ],
+    "maas": {
+      "commissioning": {
+        "architecture": "arm64/hwe-24.04-edge",
+        "name": "ubuntu/noble"
+      }
+    },
+    "keyboard": {
+      "layout": "es"
+    }
+  },
+  "rpi4mbarm64-chroot": {
+    "type": "chroot-debootstrap",
+    "osIdLike": "debian ubuntu",
+    "tftpPrefix": "rpi4mb",
+    "bootstrapHttpServerPort": 8888,
+    "menuentryStr": "UNDERPOST.NET UEFI/GRUB/MAAS RPi4 CHROOT commissioning (ARM64)",
     "networkInterfaceName": "enabcm6e4ei0",
-    "netmask": "255.255.255.0",
     "firmwares": [
       {
         "url": "https://github.com/pftf/RPi4/releases/download/v1.41/RPi4_UEFI_Firmware_v1.41.zip",
@@ -13,7 +43,7 @@
       }
     ],
     "chronyc": {
-      "timezone": "America/New_York",
+      "timezone": "America/Santiago",
       "chronyConfPath": "/etc/chrony/chrony.conf"
     },
     "debootstrap": {
@@ -23,22 +53,69 @@
       }
     },
     "maas": {
-      "image": {
+      "commissioning": {
         "architecture": "arm64/ga-24.04",
         "name": "ubuntu/noble"
       }
     },
-    "nfs": {
-      "mounts": {
-        "bind": [
-          "/proc",
-          "/sys",
-          "/run"
-        ],
-        "rbind": [
-          "/dev"
-        ]
+    "keyboard": {
+      "layout": "es"
+    }
+  },
+  "rpi4mbarm64-iso-nfs": {
+    "type": "iso-nfs",
+    "osIdLike": "debian ubuntu",
+    "isoUrl": "https://cdimage.ubuntu.com/releases/24.04/release/ubuntu-24.04.3-live-server-arm64.iso",
+    "tftpPrefix": "rpi4mb",
+    "bootstrapHttpServerPort": 8888,
+    "menuentryStr": "UNDERPOST.NET UEFI/GRUB/MAAS RPi4 ISO-NFS commissioning (ARM64)",
+    "networkInterfaceName": "enabcm6e4ei0",
+    "chronyc": {
+      "timezone": "America/Santiago",
+      "chronyConfPath": "/etc/chrony/chrony.conf"
+    },
+    "firmwares": [
+      {
+        "url": "https://github.com/pftf/RPi4/releases/download/v1.41/RPi4_UEFI_Firmware_v1.41.zip",
+        "gateway": "192.168.1.1",
+        "subnet": "255.255.255.0"
+      }
+    ],
+    "maas": {
+      "commissioning": {
+        "architecture": "arm64/hwe-24.04-edge",
+        "name": "ubuntu/noble"
+      }
+    },
+    "keyboard": {
+      "layout": "es"
+    }
+  },
+  "rpi4mbarm64-chroot-rocky9": {
+    "type": "chroot-container",
+    "osIdLike": "rhel centos fedora",
+    "tftpPrefix": "rpi4mb",
+    "bootstrapHttpServerPort": 8888,
+    "menuentryStr": "UNDERPOST.NET Rocky9 Container CHROOT NFS (ARM64)",
+    "networkInterfaceName": "eth0",
+    "firmwares": [
+      {
+        "url": "https://github.com/pftf/RPi4/releases/download/v1.41/RPi4_UEFI_Firmware_v1.41.zip",
+        "gateway": "192.168.1.1",
+        "subnet": "255.255.255.0"
       }
+    ],
+    "chronyc": {
+      "timezone": "America/Santiago",
+      "chronyConfPath": "/etc/chrony/chrony.conf"
+    },
+    "container": {
+      "image": "quay.io/rockylinux/rockylinux:9",
+      "architecture": "arm64",
+      "packages": ["kernel", "chrony", "kbd", "glibc-langpack-en", "glibc-langpack-es", "tzdata"]
+    },
+    "keyboard": {
+      "layout": "es"
     }
   }
 }

package/bin/build.js

@@ -159,6 +159,7 @@ const { DefaultConf } = await import(`../conf.${confName}.js`);
       recursive: true,
     });
 
+  const originPackageJson = JSON.parse(fs.readFileSync(`./package.json`, 'utf8'));
   const packageJson = JSON.parse(fs.readFileSync(`${basePath}/package.json`, 'utf8'));
   packageJson.name = repoName.replace('engine-', '');
 
@@ -171,16 +172,31 @@ const { DefaultConf } = await import(`../conf.${confName}.js`);
       );
       delete packageJson.bin.underpost;
       packageJson.bin.cyberia = 'bin/index.js';
-      packageJson.keywords = ['cyberia', 'object-layer', 'game-engine', 'assets-management', 'web3'];
+      packageJson.keywords = [
+        'cyberia',
+        'object-layer',
+        'game-engine',
+        'assets-management',
+        'web3',
+        'atlas-sprite-sheet',
+      ];
       packageJson.description = 'Cyberia Engine - Object Layer and Assets Management Microservice';
+      const { CyberiaDependencies } = await import(`../src/client/components/cyberia-portal/CommonCyberiaPortal.js`);
+      packageJson.dependencies = {
+        ...packageJson.dependencies,
+        ...CyberiaDependencies,
+      };
       fs.writeFileSync(`${basePath}/bin/index.js`, fs.readFileSync(`./bin/cyberia.js`, 'utf8'), 'utf8');
       fs.copyFileSync(`./src/api/object-layer/README.md`, `${basePath}/README.md`);
       fs.copySync(`./hardhat`, `${basePath}/hardhat`);
       fs.copySync(`./hardhat/white-paper.md`, `${basePath}/white-paper.md`);
-      fs.copySync(
-        `./src/client/ssr/pages/CyberiaServerMetrics.js`,
-        `${basePath}/src/client/ssr/pages/CyberiaServerMetrics.js`,
-      );
+      for (const path of [
+        '/src/client/ssr/pages/CyberiaServerMetrics.js',
+        '/src/server/object-layer.js',
+        '/src/server/atlas-sprite-sheet-generator.js',
+      ])
+        fs.copySync(`.${path}`, `${basePath}${path}`);
+
     default:
       break;
   }