Skip to content

v3.1.3

Choose a tag to compare

View all tags
@underpostnet underpostnet released this 18 Mar 01:42
· 109 commits to main since this release
v3.1.3
4024fac

Changelog v3.1.3

2026-03-17

cli-run

  • feat: Add 'pid-info' and 'background' methods to enhance process management in CLI (30afedf4d)

server-start

  • feat: Add option to skip pulling base code in build process and update configuration for error handling (3f8d7b09b)

github-actions

  • feat: Update CI workflows to improve commit message handling and deployment conditions (2a4884a1e)
  • feat: Add deploy_type option to CI workflows and enhance changelog message propagation (d222753ec)

docs

  • feat: Update changelog, CLI help, and documentation with new commands and options (124c8b2af)
  • feat: Update CLI documentation and enhance README with versioning and command index (e6eb668d4)
  • feat: Enhance documentation configuration and remove obsolete options in build processes (3437e1488)

client-underpost

  • feat: Refactor styles in RichText and CssUnderpost components for improved typography (ee1d12335)

client-core

  • feat: Update links to open in the top frame and enhance iframe sandboxing (8ec50df8d)

cli-client

  • feat: Add sync-conf command and enhance build options for client assets (ad8b96242)

swagger

  • fix: update security middleware to ensure correct CSP headers for Swagger UI (ef7dd5243)

scripts

  • Add missing package installation command in ports-ls.sh (e13253366)

New release v:3.1.2 (2026-03-15)

cli-run

  • Fix streamline deployment logic prevent override env files and redundant build workflows (048fb8ff1)

engine-cyberia

  • fix: update error handling for underpost passthrough to include 'env' command (402a96176)

New release v:3.1.1 (2026-03-14)

cli-index

  • fix: add quiet option to dotenv config for improved error handling (975448eb4)

cli-secrets

  • fix: add missing dotenv import in secrets module (7f83e26c4)

cli-repository

  • fix: enhance environment variable checks for GITHUB_TOKEN retrieval (d097c6c1f)

New release v:3.1.0 (2026-03-14)

docs

  • Add documentation for Baremetal and LXD management, including command references and quick start guides (3569b5150)
  • feat: update documentation with new command options for database and deployment management (707ef0e4d)

github-actions

  • feat: add optional commit message input for workflow_dispatch in CI configurations (2314de8c6)
  • Fix cloud explorer underpost session and underpost install in deployments workflows (746547206)
  • Add npm install for update packages in deployments engine workflows (5549a3f5d)
  • Remove temporal --underpost-quickly-install in deployments workflows (777b39a2e)

cli-repository

  • feat: enhance CI/CD workflows with workflow_dispatch support and input options (b311866fa)

package

  • fix: add production image script to package.json (fe0ca63df)
  • Add deploy js dependabot branch merge deploy script (cdc7e90c3)
  • Fix packages vulnerabilities (492a3963a)

run-deploy

  • feat dd security check for secrets before template deployment (50b6b9ba6)

bin-deploy

  • feat(deploy): add 'conf' case to load configuration based on arguments (28d3e8bf5)
  • Add temporal fallback underpost legacy version handling (ad74d2ef6)
  • separate cyberia-hardhat case deploy script (3cd032785)

server-logger

  • fix(logger): update json-colorizer import and color definitions (2b89456df)
  • Fix colorize import logger (d7c01ccc2)

gitleaks

  • fix: update gitleaks configuration title and add new ignore entries for sensitive tokens (408cad0a4)

server-conf

  • feat: add loadCronDeployEnv function to manage deployment-specific environment variables across modules (19de5ea13)
  • feat: enhance environment variable file generation with template support (467f3a348)
  • refactor: update configuration loading logic and enhance environment variable handling (bbda63807)

cli-client

  • feat: refactor deployment process to use new client command and streamline build operations (c854da41a)

env

  • feat: integrate loadEnv function to manage deploy-specific environment variables in CLI and server modules (47a1560be)

template

  • fix: update deployment script to build template and adjust logging configuration (30c3a830b)

server-client

  • fix: improve error logging for nodemon crashes in client development server (a0ece9770)

package-script

  • feat: add clean script to package.json for environment cleanup (1516217a8)

cli-repo

  • feat: add sync-start option to synchronize start scripts in package.json for deploy IDs (59ebb8c1c)
  • feat: add option to display current Git branch name (8492f7a2b)

cli-run

server-env

  • refactor: centralize environment variable loading (3c2709aec)

bin-vs

  • Improve vs code ide runner handling (2b1a8b326)

engine

  • Refactor security deploy conf logic and handle (7d6592c43)
  • Silencing dotenv injection logs (56b8e8e80)

engine-cyberia

  • Add development pv pvc dd-cyberia manifests (ca4d3d342)
  • Fix object layer model Mongoose pre save next error (506fb719c)
  • Add missing ethers packahge in CyberiaDependencies scope (5f11cafe6)
  • Add Customize Docs release URL and MenuCyberiaPortal GitHub (e879c2240)
  • Fix Hardhat CI npm audit failure (3ea9ed486)
  • Update hardhat config evm version (816e1d7d0)
  • Cyberia Portal Docs Modal Fixes (9bd9eb1e4)
  • Add Cyberia portal docs build integration (9d8abe001)
  • Kubeadm Underpost Cluster Besu Integration (1df6cfbfb)
  • Fix Hardhat Web Integration Canonical CID (bb2a81fab)
  • Cryptokoyn and Itemledger metadata client and seo injects (db8c9b337)
  • Cyberia NPM Dependency Installer hardhat on main module override (a43cc25ea)
  • Apply mermaid on diagrams in WHITE-PAPER.md (0bb230e14)
  • Hardhat Cyberia CKY Token Lifecycle (514bdafae)
  • Hardhat Ethers v6 Upgrade Audit (114e42f7d)
  • Hardhat ES6 refactor for Cyberia (9b9f85693)
  • Object Layer Token Ethereum Refactor (82076eb9e)
  • Rename cyberkoyn reference to cryptokoyn (ae5949337)
  • Refactor Object Layer White Paper and ERC1155 Besu Integration (8cb6f59c2)

cli-deploy

  • Fix Kubernetes PVC Manifest Inconsistencies (6839bccca)
  • Fix Kubernetes PVC Manifest Inconsistencies builder (d6f311c60)

client-core

  • Fix AgGrid Theme Events Rendering (4b37681f1)
  • Add logic to custom ui-icon in content component (b380703c8)
  • Fix sitemap generation logic (7cfb23d01)
  • Fix sitemap builder defaul url sitemap (c39f1e070)

client-underpost

  • Add File Explorer Cloud Menu Auth (f3cc57e28)

api-core

  • Fix deprecated Mongoose pre save next error (bee1a5829)

conf

  • Add SwaggerDarkMode in dd-cyberia conf (69d4c54f1)

bin-build

cli-core

CYBERIA Network Object Layer Engine CLI

cyberia

Network Object Layer Engine CLI

Downloads Version

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.

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.

Process and import object-layer assets

This will iterate asset folders for the given types and store processed objects in MongoDB.

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

# Process all recognized types
cyberia ol --import all

Procedural generation with --generate

Produces semantically consistent object layers with controlled, reproducible variation and short-term temporal coherence (consecutive frames stay visually consistent). Uses the parametric shape generator and object layer engine under the hood.

# Generate a desert floor tile (single frame, auto seed)
cyberia ol floor-desert --generate

# Full control: 3 frames, explicit seed, density
cyberia ol floor-desert --generate --count 3 --seed fx-42 --frame-index 0 --frame-count 3 --density 0.5

# Grass terrain, sparse, 5 frames
cyberia ol floor-grass --generate --seed meadow-7 --frame-count 5 --density 0.3

# Water surface, dense, high element count
cyberia ol floor-water --generate --seed ocean-1 --count 5 --density 0.8 --frame-count 4

# Stone cobblestone
cyberia ol floor-stone --generate --seed cobble-99 --count 4 --density 0.6

# Lava flow, 3-frame animation
cyberia ol floor-lava --generate --seed magma-3 --frame-count 3 --density 0.7

--generate options:

Option Default Description
--seed <str> auto UUID Deterministic seed string. Same seed → same output.
--count <n> 3 Shape element count multiplier per layer.
--frame-index <n> 0 Starting frame index.
--frame-count <n> 1 Number of consecutive frames to generate.
--density <f> 0.5 Overall density factor (0–1). Lower = sparser.

Available semantic item-id prefixes:

Prefix Type Tags Palette
floor-desert floor sand, dune, arid warm ochres, sand tones
floor-grass floor grass, meadow, earth greens, earth browns
floor-water floor water, ocean, wave blues, foam whites
floor-stone floor stone, rock, cobble greys, warm/cool stone
floor-lava floor lava, magma, fire reds, oranges, dark crust
skin-* skin character, body skin tones, clothing darks

How generation works

Each item-id maps to a semantic descriptor that provides semanticTags, paletteHints, preferredShapes, and named layer specs (e.g. base, dunes, rocks, tufts for floor-desert).

Seed derivation — deterministic at every level:

layerSeed  = hash(seed + ':' + itemId + ':' + layerKey)
frameSeed  = hash(layerSeed + ':' + frameIndex)

Temporal coherence — shape topology (which shapes, how many, where) is locked to layerSeed and never changes between frames. Only smooth, low-frequency noise perturbations (position jitter, slight rotation/scale wobble) are derived from frameSeed, so frame N and N+1 differ by ~2% of cells.

Layer naming — every generated layer gets an id: <itemId>-<layerKey> (e.g. floor-desert-dunes).

Generation pipeline per layer:

  1. Pick generator type (noise-field for base fills, shape for element placement).
  2. Select palette colors deterministically from paletteHints with per-element colorShift.
  3. For shape layers: pick shape via weighted preferredShapes, compute stable base transform (x, y, scale, rotation), apply frame-level smooth noise.
  4. Stamp shapes onto a 24×24 grid via intCoords rasterization from the parametric shape generator.
  5. Composite all layers into a final frame_matrix + unified colors palette.

Variability factors per layer:
scaleVariance, rotationVariance, colorShift, jitter, noiseLevel, detailLevel, sparsity — small, deterministic variations that keep each generation unique but semantically coherent.

What --generate persists

The full pipeline runs automatically:

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

Reproducibility example

Running the same command twice produces byte-identical output:

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

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 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 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
Assets 2
Loading