Changelog v3.2.5

2026-04-16

cli-run

Refactor cron command execution to improve flag handling and streamline deployment options (1773b8e12)
Add shellExec command for database operations in deployment process (9de52cb7d)

cli-cron

Enhance cron job commands with git option and streamline backup operations (170c77ff4)
Refactor cron job commands to use 'underpost' CLI and remove secret run step (e51cd0231)
Refactor streamline cron deployment handling and add deploy-id resolver (bb81fe80b)

github-actions

Fix sudo usage in package installation step (8545a8e88)

New release v:3.2.4 (2026-04-15)

cli-cron

Update underpost container environment path for volume mount (8fdfb5416)

github-actions

Add dispatch step for release CD in publish workflow (8dc0e3ccd)

New release v:3.2.3 (2026-04-15)

cli-cron

Remove is-inside-container dependency and implement isInsideContainer method in env module (79d39ece0)

github-actions

Ensure deploy-release job runs only on successful build-and-publish (08ba04632)

New release v:3.2.2 (2026-04-15)

docker-image

Remove unnecessary directory creation and volume declaration for working directory in Dockerfile (84f7f8950)

github-actions

Update CronJob schedules and commands to include kubeadm flag (2795d6a8a)
Add volume mounts for .env file in dd-cron backup and dns CronJobs (76cd8a31b)
Refactor deployment and cron job scripts for improved readability and maintainability (34d38d077)
Refactor deployment scripts to use environment variables for secret creation (40165237c)
Update cron jobs and deployment scripts to use secrets and streamline environment variable handling (3e3b0c3b0)

cli-cron

Add support for k3s, kind, and kubeadm flags in CronJob configuration (d7edd8dea)
Add environment variable volume and path for Kubernetes CronJob (abe731634)
Refactor deployment scripts to create secrets from container environment variables and streamline environment handling (e5589ec7f)
Enhance deployment and backup processes (f58323077)

cli-db

Add error handling and logging for database operations in UnderpostDB (c0d935a0c)
Implement private engine repository management (84719664a)

package

Implement feature X to enhance user experience and fix bug Y in module Z (8dea4a2f7)
Remove --force option from install:test script to prevent unintended package installations (2aeeff179)
Remove force in coveralls-next install script (5751a6d12)

runtime-wp

Implement automatic commit and push of generated files to repository during provisioning (d20f079ec)

runtime-lampp

Enhance .htaccess rules for WordPress and Lampp to protect sensitive files and directories (1a455ec7b)

cli-deploy

Refactor command construction in deployment and cron scripts for improved readability (ceaf5012b)

gitub-actions

Refactor CI workflows to streamline Docker build and release processes (ab0875839)
Refactor CI/CD workflows to streamline Docker build and release processes (5330af102)

client-core

Add SocketIoHandler and AppStore to DefaultConf component list (a55096889)
Refactor API path handling to introduce getApiBaseProxyPath function and streamline base path construction (afb1b3532)
Enhance DropDown component to reset checkbox values and improve state management on click events (b02a3fad4)
Refactor API path handling to introduce getApiBaseProxyPath function and simplify getApiBasePath logic (0a18bce99)

cli-fs

Enhance pull operation to log skipped files when they already exist (7330aa012)

cli-env

Refactor UnderpostSecret to streamline environment file handling and remove existing global .env file (c510f7cff)

server-start

Add cleanup command to production deployment process (5bf5530e3)

conf

Add SocketIoHandler and AppStore to default configuration (d155277a3)

New release v:3.2.0 (2026-04-13)

cli-repository

Refactor GitHub URL handling to centralize authentication logic and improve repository accessibility checks (4783e25bd)
Update GitHub token usage to use x-access-token format in repository URLs (8a9506d97)
Update GitHub token usage to use OAuth2 format for repository URLs (e71530fcc)
Add remote repository accessibility check and unzip to Dockerfile (be32ecebe)
Refactor UnderpostRepository and UnderpostRun: streamline unpushed commit detection and enhance commit message propagation logic (f96e3a674)
Refactor git repository initialization: streamline repo setup and user configuration using environment variables across multiple modules (146cb2181)
Fix getHistory and related methods to support repository path, enhancing command execution context (ee79f636f)
Add --unpush option to automatically detect unpushed commits for log display (9c7ca3ca5)
Add Git branch reflog and commit hash options to CLI (c69e8aeca)

runtime-wp

Enhance remote repository accessibility checks by preventing credential prompts and improving logging (abf48b28f)
Prepend XAMPP's bin directory to PATH for WP-CLI calls (a1449e380)
Add WP-CLI installation check and ensure safe.directory for git operations (414e8743e)
Enhance backup functionality: add GitHub organization support and streamline WordPress backup handling (717004bb0)
Enhance WpService: inject WP Mail SMTP plugin configuration into wp-config.php for improved email handling (10188d104)
Update .htaccess handling for WordPress subdirectories: append scoped rewrite rules to prevent conflicts between multiple installs. (409572dab)
Refactor database creation logic: drop and recreate MariaDB database for fresh installs to ensure a clean state. (e370b0b21)
Enhance WpService and runtime configuration: add WordPress install options to support custom titles, admin credentials, and integrate with server configuration. (deae03d84)
Ensure parent directory exists before moving WordPress files: add check and create directory if missing. (3661681f8)
Enhance deployment scripts and Dockerfiles: update image references to use PHP 8.3, add XAMPP binaries to PATH, and modify WpService to support redirect options in createApp method. (6c782a07d)
Add WordPress provisioning support with WP-CLI integration: enhance WpService to install WordPress and activate the Wordfence plugin non-interactively; update configuration for subdirectory support in Dockerfile. (e183f06fc)
Enhance WpService for subdirectory support: modify provisioning methods to handle WordPress installations in subdirectories, including .htaccess generation for URL rewriting. (38704bf37)
Update Dockerfile and Lampp.js to install XAMPP 8.2; add WpService for WordPress management (ee7cb66de)

server-start

Clear environment variables during production deployment cleanup (a6cc07699)
Add production environment cleanup in deployment process (69c07f7f6)

dependencie

Add is-inside-container package to dependencies (ba558dea5)

engine

Remove unused CERTBOT_LIVE_PATH variables from environment configuration (1b47da9ba)

engine-lampp

Update WordPress configuration for environment variables and add GitHub authentication for private repositories (aa0c605ea)

engine-test

Add SMTP configuration to DefaultConf and update deployment manifests with deploy-id labels (3bd19e174)

release

Refactor killDevServers function for improved process management during builds and deployments (a21689bdd)

package

Remove unnecessary peer dependencies for Babel packages (560bf8c6b)
fix: correct typo in install:test script for coveralls installation (a466daeb6)

api-cyberia-instance

Add border color support to status icons and update gRPC server handling (214ef8825)
Enhance portal functionality by introducing portal subtypes and occupancy grid for better entity placement (93b75c563)
Implement fallback world generation and API integration for CyberiaInstance (0657979de)
Implement central portal connector and procedural entity generation for CyberiaInstance (6146ada76)
Refactor schema to directed graph model (PortalEdgeSchema) (a4c0d62a7)
Implement CyberiaInstance API with CRUD operations and service integration (2fa7fde33)

engine-cyberia

Add Entity Status Indicator (ESI) registry and update gRPC server to handle status icons (4c5ec09d5)
Refactor Cyberia item definitions: update DefaultCyberiaItems structure and enhance import functionality (d59279a6d)
Add 'cyberia-dialogue' to DefaultConf: include dialogue module in configuration (bb7293875)
Add equipment rules and refactor object layer schemas for clarity (f852e2d9b)
Add semantic layer generator files and update configuration (7bde7856e)
Refactor enhance Semantic Layer Generator with modular structure and improved documentation (522ee230c)
Refactor entity schemas to include defaultObjectLayers for enhanced inventory management and streamline entity initialization (7ca2116eb)
Implement Fountain & Sink economy model with detailed configuration in defaults and schema (bd0725156)
Enhance bot generation by introducing weapon chance and adjusting entity count ranges for obstacles and foregrounds to improve gameplay variability. (b22aa71a8)
Refactor fallback world generation to use random counts for bots, obstacles, and foregrounds, enhancing procedural variability. (2829d9952)
Refactor Cyberia instance configuration to replace single item ID fields with arrays for live and dead item IDs, enhancing flexibility and consistency across schemas. (ed7697afb)
Refactor skill rules in Cyberia instance configuration to replace 'bullet' terminology with 'projectile', enhancing clarity and consistency across schemas (ec88c4bc4)
Refactor Cyberia instance configuration to utilize defaults for entity types and skill rules, enhancing maintainability and consistency across schemas (39b0c9c29)
Enhance Cyberia instance configuration with default values and auto-upsert logic for CyberiaInstanceConf (703603d57)
Refactor Cyberia instance configuration to use separate model and enhance skill configuration handling (6c8c5abe3)
Update skill configuration to use logicEventIds instead of logicEventId and remove spawnedItemIds (38d27602f)
Enhance skill configuration and fallback instance handling in gRPC server (987691fa0)
Enhance gRPC server with game server configuration and fallback instance handling (3f2bf5e43)
Refactor Cyberia dependencies management by removing overrides and patching logic (74ee9984e)
Update patchCyberiaDependencies to handle file-type import changes for ESM and CommonJS (4514e6d48)
Add CyberiaDependenciesOverrides for enhanced dependency management in Cyberia portal (d1783287c)
Add MapEngineCyberia grid rendering and interactive cell selection (b798ae61c)
fix: Enhance build process by missing copying jsdoc file with specific name and improve error handling in CLI (56d9300d3)

grpc-cyberia

Remove AtlasSpriteSheet handling from gRPC server: delete unused functions and RPC handlers (c8dd39728)

bin-deploy

Add 'add-api' command to deploy script: implement API addition to server and client configurations (17811367b)

api-cyberia-dialogue

Add Cyberia dialogue functionality: implement CRUD operations, enhance dialogue model, and create seed dialogues (4514545c3)
Implement Cyberia Dialogue API: add controller, service, model, and router for CRUD operations (dc463616c)

hardhat

Enhance coverage build process to support Hardhat 3 output structure (61b90edbe)
Upgrade to hardhat v3 and fix vulnerabilities (80ced86ef)

cli-release

Enhance UnderpostRelease: update local repo initialization to configure worktree and ensure changes are staged before commit (c552dbc42)
Add pwa method to update and push pwa-microservices-template repository (752adea13)
Add CI push options to release command and implement local CI workflow (4249540dc)
Add release orchestrator command and update GitHub workflows (615a6941f)

cli-run

Add random password generator run id (76f6be0a9)
Refactor release and run modules: update commit handling to return command strings for improved execution flow (0ff930428)
Enhance commit message handling: update logic to capture and sanitize last N commit messages from the engine repository for CI push and PWA build commands (114fda529)
Update gRPC service traffic handling to reflect current parent deploy traffic (754b8f770)
Add local deployment method for templates without GitHub Actions (62c3ff18a)
feat: add docker-image method to dispatch Docker image CI workflow (97737c3ab)
Add git clean option for deployment processes and enhance cluster context handling (a59df7402)
Refactor Docker image handling in CLI: Replace direct shell commands with Underpost.image.pullDockerHubImage for improved clarity and maintainability (6d656bec8)

wp-runtime

Refactor WpService and BackUp: initialize git repository for WordPress sites and link to remote repository during backup operations (220fa61af)
Update LamppService and WpService: adjust Apache user/group ownership to current user for improved plugin compatibility (2bea96a70)
Enhance Dockerfiles and WpService: update PATH for XAMPP binaries, add no-op sendmail, and adjust permissions for writable site configuration (5f6e34103)
Fix virtual host configuration: update ServerName directive and disable UseCanonicalName for improved routing. (bd9137cab)

cli-db

Enhance database management in UnderpostDB: ensure database creation for MariaDB and MongoDB; improve error handling for missing SQL and BSON files. Update WpService to verify remote repository accessibility before cloning, falling back to fresh install if necessary. (3f7beda29)

cli-kubectl

Refactor Kubernetes CLI operations: centralize pod management and file transfer in a new kubectl module; update db and deploy modules to utilize the new API (e31597512)

cli-deploy

Add host parameter to buildGrpcServiceManifest for targeted gRPC port scanning (f33d6a52a)
Add gRPC service deployment support in the deploy module (456a32076)
Enhance gRPC service manifest to support traffic color switching during deployment (daf79cce8)

bin-build

Copy .gitignore to the deployment directory during build process (fbd53450e)
Update build process to conditionally copy jsdoc and deployment manifests for development (a5b61e906)

api-atlas-sprite-sheet

Add metadata endpoints for AtlasSpriteSheet API to retrieve item metadata (18dfae3e1)
Add blob endpoint and service for retrieving atlas sprite sheet data (5c5f60d2b)

cli-cyberia-semantic

Update default values generate-semantic-examples examples (b97625211)

grpc

Fix gRPC server initialization condition to check for root path (1efd33b4b)

cyberia-semantic-engine

Refactor hair zone calculation for improved accuracy in skin generation (9eb644ed2)
Refactor hair zone calculation for improved accuracy in skin generation (4c2e666e3)
Refactor skin and hair generation logic for improved readability and maintainability (a2dd47768)
Add command to generate semantic examples with customizable options (45dbb38d7)
Enhance skin generation with subtype support for varied tones and hair styles (4549be1e7)
Add border extraction and hair depth control to skin template generation (03b6e45b8)

client-cyberia-ol-viewer

Refactor WebP display logic to prevent layout flicker and improve control state updates (4e9843554)

playwright

Update Playwright image version to v1.59.0 for improved features and stability (3aa4a281a)

cli-cyberia-instance

Refactor skillConfig seeding logic to ensure idempotency and improve error handling for missing CyberiaInstance (0afe4e899)
feat: enhance unpin logging for IPFS Cluster to handle 404 status (5ca839926)

api-ipfs

Refactor IPFS pinning logic to enhance CID registry management and remove userId dependency (986520b68)

client-cyberia-instance

Implement portal connection feature in Cyberia instance with error handling and UI integration (46a98148f)
Add portal management features to InstanceEngineCyberia component (ef7a1f1d0)
Add InstanceEngineCyberia and integrate with CyberiaInstance API (5c03603f7)

api-cyberia-global

Implement Cyberia Global Map Code Registry API with CRUD operations (2bb06f1c4)

cyberia-instance-conf

Implement Cyberia instance configuration API with CRUD operations (00312d6d0)

runtime-express

implement gRPC server integration and configuration in Express service (5029c962c)

gprc-cyberia

feat: add gRPC support with server implementation and update dependencies (07b552c1c)

github-actions

Update clean steps for client public directories in deployment process (b5e9b5edc)
Update workflow dependencies for Dockerhub and release processes (5f8aa62e0)
feat: streamline CI workflows by removing redundant GITHUB_TOKEN configuration steps (dc61ed92b)
fix: remove coveralls uninstallation from CI workflows and update install:test script (dee0cbc3e)
refactor: Simplify CI workflows by removing unnecessary conditions and enhancing dispatch logic (f7bcb4cc9)

client-stream

Enhance user tracking in stream channel by notifying existing users on join (01702e5d3)
Refactor: enhance Stream class for improved PeerJS management and simplify StreamNexodev integration (bc470740b)

api-cyberia-map

feat: enforce unique constraints on code fields in CyberiaInstance and CyberiaMap schemas (6ea0fe2ee)
feat: Implement Cyberia map CRUD operations with controller, service, and router (dd21f6b08)

cli-cyberia-instace

Add export/import functionality for Cyberia instances and related documents (9b64825cc)

client-cyberia-map

feat: add option to capture object layer thumbnail on save/update (824d15aee)
feat: add variation preserve input for entity dimension adjustments (d6bafbaba)
feat: ensure new thumbnail upload for cloned maps and handle auto-capture fallback (06468e028)
feat: add entity variation generation and flip functionality in MapEngineCyberia (815c9ecde)
feat: implement clone map functionality with thumbnail upload and auto-capture (ed28d7f9f)
Add grid dimensions to CyberiaMap schema and update MapEngineCyberia to handle grid parameters (bd3613ecc)
feat: add random dimension feature for entities and implement UI controls (d24f7e55f)
Add object layer image loading and toggle functionality in MapEngineCyberia (087377409)
Add toggle for adding entities on click and display cell coordinates in MapEngineCyberia (d77967d72)
Add entity filtering functionality to MapEngineCyberia component (d58f68ef9)
Enhance DropDown and MapEngineCyberia components with badge rendering and grid visibility toggle functionality (b60eb8fb0)
Refactor DropDown and MapEngineCyberia to integrate object layer item selection and thumbnail capture functionality (34988386a)
Add search-item-ids endpoint and implement autocomplete for object layer item IDs (ec066a757)
feat: Enhance Cyberia map management with admin role checks for update and delete operations (e62b121d4)
feat: Enhance Cyberia map management with additional fields, user authentication, and thumbnail support (0023ba3ec)
feat: Enhance Cyberia map management with load map functionality and notifications (71aab98e9)
feat: Implement Cyberia map management with CRUD operations and integrate into MapEngineCyberia (f6bb13ecc)
feat: Enhance Cyberia entity management with CRUD operations and integrate with MapEngineCyberia (bc3146f2f)

gitub-actions

Remove coveralls uninstallation from CI workflows (68eee857c)

coveralls

Update Coveralls upload step to use direct command instead of GitHub Action (b0c6712f3)

github-actios

fix: add bash to required packages and implement retry logic for database connections (d44c0d52e)

websocket

Refactor: update SocketIoHandler to SocketIoHandlerProvider and add AppStore references across multiple configuration files (0811b67cf)
Refactor: streamline WebSocket channel management by consolidating channel logic and removing deprecated management files (23e024554)

client

Refactor: remove BaseElement dependencies and simplify AppStore instantiation across multiple components (f0fa9011e)
Refactor components to utilize AppStore for state management (9436d91ca)
Refactor: replace uglify-js with esbuild for JavaScript minification and import rewriting (759d8269b)
Refactor parameter handling in multiple components: Remove unused EVENT_CALLBACK_TIME parameters and simplify Keyboard initialization (491303dcd)

client-ws

Refactor: streamline SocketIo handlers and enhance WebSocket management for improved clarity and maintainability (c2d135072)

cli-cyberia

Enhance README.md: Add new features for drop and cleanup, static asset management, IPFS and blockchain integration, and update import commands for clarity (cf433a4e6)
Enhance IPFS cleanup process in Cyberia CLI: collect and unpin CIDs, remove MFS paths for ObjectLayer items (0984e0fbb)
Enhance Object Layer and Atlas Sprite Sheet Management: Implement cut-over consistency for staging CIDs, streamline IPFS integration, and improve thumbnail handling in Cyberia services. (9b92cdec7)
Refactor CLI commands for object layer import: update flags from --import to --import-types for clarity (3ef65f6c7)
Add development environment option and enhance ObjectLayer upsert logic in Cyberia CLI (87ae2f471)
Add default Object Layer items and import command to Cyberia CLI (4905b91c8)
Enhance import functionality in Cyberia CLI: support specific item imports and batch imports by type (6c4c567a6)

object-layer-engine

Update ObjectLayerEngineModal to dynamically set cell dimensions based on loaded data (6b304e6e3)

conf

Update deployment configurations and proxy settings for dd-core and dd-cyberia environments (a97862864)

cli-client

Refactor syncEnvPort and singleReplica operations for improved clarity and error handling (751ef4ffd)

dependabot

feat: Enhance dependabot branch management with stashing, merging, and cleanup operations (06a42f4bd)

coverage

feat: Add coverageOutputDir to documentation configuration for custom coverage output path (ea630ecc4)

api-cyberia-entity

feat: Implement Cyberia entity CRUD operations and service integration (56629ee17)

cyberia

Network Object Layer Engine CLI

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, 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, 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.
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.
Drop and cleanup — removes ObjectLayer, RenderFrames, AtlasSpriteSheet, File documents and unpins IPFS CIDs. Supports targeted drop (specific items) or full drop.
Static asset cleanup — optionally removes client-side static asset folders and runs git-clean on the asset directory.
IPFS integration — pins CIDs to IPFS Cluster and Kubo, manages MFS paths, and unpins on drop.
Blockchain integration — deploys Besu IBFT2 networks, manages ERC-1155 tokens (register, mint, transfer, burn), and resolves canonical CIDs from MongoDB for on-chain registration.
Cut-over consistency — stages all IPFS operations, file creation, and atlas generation in-memory before atomically updating live MongoDB documents.

Getting Started

Prerequisites

You must have the following installed in your environment:

Node.js (v24.10.0 recommended)
npm or yarn
MongoDB (or access to the configured MongoDB instance)

Installation

npm install -g cyberia

Environment Setup

Ensure your required environment variables (e.g., DEFAULT_DEPLOY_ID, DEFAULT_DEPLOY_HOST, DEFAULT_DEPLOY_PATH) are correctly configured, typically in a .env file, to point the CLI to the correct database instance defined in conf.server.json.

Usage

The CLI is executed from the project root via the cyberia.js script.

Import specific items with `--import`

Import one or more object layers by item-id. The CLI searches all asset type directories for matching items.

# Import a single item
cyberia ol hatchet --import

# Import multiple items (comma-separated)
cyberia ol hatchet,sword,shield --import

Batch import by type with `--import-types`

Iterate asset folders for the given types and store processed objects in MongoDB.

# Process specific types (comma-separated)
cyberia ol --import-types skin,floor

# Process all recognized types (skips items that already exist in the database)
cyberia ol --import-types 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.

# 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

# Skin: random skin tone and hair
cyberia ol skin-random --generate --seed hero-1 --frame-count 4

# Skin: dark skin only
cyberia ol skin-dark --generate --seed hero-dark-7

# Skin: light/pale skin only
cyberia ol skin-light --generate --seed hero-light-3 --frame-count 4

# Skin: any skin tone with vivid (blue/red/green…) hair
cyberia ol skin-vivid --generate --seed hero-vivid-2

# Skin: any skin tone with natural hair only (brown, blond, grey…)
cyberia ol skin-natural --generate --seed hero-nat-5 --frame-count 4

# Skin: shaved / bald head (no hair at all)
cyberia ol skin-shaved --generate --seed hero-bald-1 --frame-count 4

--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-random`	skin	character, body	any skin tone, any hair
`skin-dark`	skin	character, body	dark/melanin-rich skin only
`skin-light`	skin	character, body	light/pale skin only
`skin-vivid`	skin	character, body	any skin + vivid hair (blue, red…)
`skin-natural`	skin	character, body	any skin + natural hair (brown…)
`skin-shaved`	skin	character, body	any skin, bald/shaved head

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:

Pick generator type (noise-field for base fills, shape for element placement).
Select palette colors deterministically from paletteHints with per-element colorShift.
For shape layers: pick shape via weighted preferredShapes, compute stable base transform (x, y, scale, rotation), apply frame-level smooth noise.
Stamp shapes onto a 24×24 grid via intCoords rasterization from the parametric shape generator.
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:

Static assets — PNGs written to ./src/client/public/cyberia/assets/{type}/{itemId}/{dirCode}/{frame}.png + metadata.json.
MongoDB — ObjectLayerRenderFrames + ObjectLayer documents created with SHA-256 hash.
Atlas sprite sheet — generated, saved to File + AtlasSpriteSheet collections, and linked via atlasSpriteSheetId.

Reproducibility example

Running the same command twice produces byte-identical output:

# 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:

cyberia ol floor-desert --generate --seed fx-42   # variant A
cyberia ol floor-desert --generate --seed fx-99   # variant B (same style, different arrangement)

Drop and cleanup with `--drop`

Removes object layer data from MongoDB and IPFS. Supports both targeted (specific items) and full drop.

# Drop specific items by item-id
cyberia ol anon,skin --drop

# Drop all object layers before re-importing
cyberia ol --drop --import-types all

What --drop removes per item:

ObjectLayer document
ObjectLayerRenderFrames document
AtlasSpriteSheet document
Associated File documents
IPFS CID pins (objectLayer.cid, render.cid, render.metadataCid, AtlasSpriteSheet.cid) from both IPFS Cluster and Kubo
MFS paths (/object-layer/{itemKey})

--drop companion flags:

Flag	Description
`--client-public`	Also remove static asset folders: `./src/client/public/cyberia/assets/{type}/{itemId}/` and `./public/{host}{path}/assets/{type}/{itemId}/`
`--git-clean`	Run `underpost run clean .` on the `src/client/public/cyberia` directory to remove untracked files

# Drop items and remove their static asset folders
cyberia ol anon --drop --client-public

# Full rebuild: drop everything, clean assets, re-import all
cyberia ol --drop --git-clean --import-types all

Environment and database flags

These flags apply to both ol and chain commands where database or environment access is needed.

Flag	Default	Description
`--env-path <path>`	`./.env`	Path to .env file (e.g., `./engine-private/conf/dd-cyberia/.env.development`)
`--mongo-host <host>`	—	MongoDB host override
`--storage-file-path <path>`	—	Storage file path override (JSON filter for selective import)
`--dev`	`false`	Force development environment (loads `.env.development` for IPFS localhost)

# Import using a specific environment
cyberia ol --import-types all --env-path ./engine-private/conf/dd-cyberia/.env.development

# Use development IPFS localhost
cyberia ol anon --import --dev

# Override MongoDB host
cyberia ol --import-types skin --mongo-host mongodb://localhost:27017

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].

# 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.

# 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.

# 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:

# 1. Import object layers from asset directories
cyberia ol --import-types 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

Procedural Generation Pipeline

Generate an object layer entirely from a semantic descriptor — no source PNGs needed:

# 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:

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

# 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

# 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

# Import multiple types at once
cyberia ol --import-types 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

Full Rebuild with Cleanup

Drop all data, clean static assets, and re-import everything:

# 1. Drop all object layers with IPFS cleanup and static asset removal
cyberia ol --drop --client-public --git-clean

# 2. Re-import all asset types
cyberia ol --import-types all

# 3. Verify
cyberia ol anon --show-frame 08_0

Targeted Drop and Re-import

Drop and re-import specific items without affecting others:

# 1. Drop specific items and their static folders
cyberia ol anon,skin --drop --client-public

# 2. Re-import only those items
cyberia ol anon,skin --import

# 3. Regenerate atlas for each
cyberia ol anon --to-atlas-sprite-sheet
cyberia ol skin --to-atlas-sprite-sheet

Blockchain Operations (`chain`)

The chain command group manages Hyperledger Besu IBFT2 network deployment and ERC-1155 token operations for on-chain object layer registration.

Deploy Besu IBFT2 Network

Deploys a private Besu IBFT2 network to Kubernetes.

# Deploy with defaults (4 validators, chain-id 777771)
cyberia chain deploy

# Custom configuration
cyberia chain deploy --validators 6 --chain-id 888881 --block-period 3

# Pull container images first
cyberia chain deploy --pull-image

deploy options:

Option	Default	Description
`--validators <count>`	`4`	Number of IBFT2 validators
`--chain-id <id>`	`777771`	Chain ID for the network
`--block-period <seconds>`	`5`	IBFT2 block period in seconds
`--epoch-length <length>`	`30000`	IBFT2 epoch length
`--coinbase-address <addr>`	auto-detect	Coinbase deployer address
`--besu-image <image>`	`hyperledger/besu:24.12.1`	Besu container image
`--curl-image <image>`	`curlimages/curl:8.11.1`	Curl init container image
`--node-port-rpc <port>`	`30545`	NodePort for external JSON-RPC access
`--node-port-ws <port>`	`30546`	NodePort for external WebSocket access
`--namespace <ns>`	`besu`	Kubernetes namespace for Besu resources
`--pull-image`	`false`	Pull Besu container images before deployment
`--skip-generate`	`false`	Skip manifest generation, use existing manifests
`--skip-wait`	`false`	Skip waiting for validators to reach Running state

Remove Besu Network

# Remove network (keep keys and manifests)
cyberia chain remove

# Full cleanup
cyberia chain remove --clean-keys --clean-manifests

Option	Default	Description
`--namespace <ns>`	`besu`	Kubernetes namespace for Besu resources
`--clean-keys`	`false`	Also remove generated validator keys
`--clean-manifests`	`false`	Also remove the generated manifests/besu/ directory

Generate Manifests Without Deploying

cyberia chain generate-manifests --validators 6 --output-dir ./manifests/besu

Accepts the same options as deploy plus --output-dir <dir> (default: ./manifests/besu).

Deploy ERC-1155 Contract

cyberia chain deploy-contract
cyberia chain deploy-contract --network besu-k8s

Compile and Test Contracts

cyberia chain compile
cyberia chain test

Register Object Layer Item On-Chain

Registers an object layer as an ERC-1155 token with its canonical CID.

# Register with CID resolved from MongoDB (recommended)
cyberia chain register --item-id hatchet --from-db

# Register with explicit CID
cyberia chain register --item-id hatchet --metadata-cid bafk...

# Semi-fungible with supply
cyberia chain register --item-id wood --from-db --supply 500000

Option	Default	Required	Description
`--item-id <itemId>`	—	yes	Human-readable item identifier
`--metadata-cid <cid>`	—	—	IPFS metadata CID (ignored when `--from-db` is set)
`--from-db`	`false`	—	Resolve canonical CID from MongoDB ObjectLayer document
`--supply <supply>`	`1`	—	Initial token supply (1 = NFT, >1 = semi-fungible)
`--network <network>`	`besu-k8s`	—	Hardhat network name
`--env-path <path>`	`./.env`	—	Path to .env file
`--mongo-host <host>`	—	—	MongoDB host override

Batch Register Multiple Items

# Batch register with CIDs from MongoDB
cyberia chain batch-register --from-db --items '[{"itemId":"wood","supply":500000},{"itemId":"hatchet","supply":1}]'

# Batch register with explicit CIDs
cyberia chain batch-register --items '[{"itemId":"wood","cid":"bafk...","supply":500000}]'

Mint, Transfer, and Burn Tokens

# Mint additional tokens
cyberia chain mint --token-id 1 --to 0xAddress --amount 100

# Transfer tokens
cyberia chain transfer --from 0xSender --to 0xRecipient --token-id 1 --amount 50

# Burn tokens
cyberia chain burn --address 0xHolder --token-id 1 --amount 10

Query Status and Balances

# Full network and contract status
cyberia chain status

# Query token balance
cyberia chain balance --address 0xAddress --token-id 0

Key Management

# Generate a new Ethereum key pair
cyberia chain key-gen

# Generate and persist keys
cyberia chain key-gen --save

# Set coinbase deployer key
cyberia chain set-coinbase --from-file ./engine-private/eth-networks/besu/0xAddr.key.json
cyberia chain set-coinbase --private-key 0xHexKey

Pause / Unpause Token Transfers (Emergency)

cyberia chain pause
cyberia chain unpause

Workflow Import (`run-workflow`)

Import Default Items

Imports default Object Layer items from a JSON configuration file into MongoDB.

cyberia run-workflow import-default-items

# Use development environment
cyberia run-workflow import-default-items --dev

Complete `ol` Command Reference

Flag	Type	Default	Description
`--import`	boolean	`false`	Import specific item(s) passed as comma-separated argument
`--import-types [type]`	string	—	Batch import by type: `skin`, `floors`, or `all`
`--show-frame [dir_frame]`	string	`08_0`	View object layer frame (direction_frameIndex)
`--to-atlas-sprite-sheet [dim]`	number	auto	Generate atlas sprite sheet, optionally specify dimension
`--show-atlas-sprite-sheet`	boolean	`false`	Display the atlas sprite sheet PNG for an item
`--generate`	boolean	`false`	Generate procedural object layers from semantic item-id
`--seed <str>`	string	random UUID	Deterministic seed for `--generate`
`--count <n>`	number	`3`	Shape element count multiplier for `--generate`
`--frame-index <n>`	number	`0`	Starting frame index for `--generate`
`--frame-count <n>`	number	`1`	Number of frames for `--generate`
`--density <f>`	number	`0.5`	Density factor (0–1) for `--generate`
`--drop`	boolean	`false`	Drop existing data (targeted or full)
`--client-public`	boolean	`false`	With `--drop`, remove static asset folders
`--git-clean`	boolean	`false`	With `--drop`, run underpost clean on cyberia assets
`--dev`	boolean	`false`	Force development environment
`--env-path <path>`	string	`./.env`	Path to .env file
`--mongo-host <host>`	string	—	MongoDB host override
`--storage-file-path <path>`	string	—	Storage file path override