Changelog v3.2.22

2026-06-07

repository

Add safe repo config in pullSourceRepo (4325c1ba7)

docs

Restore runtimeConfig docs logic (819792d1d)
Enhance favicon resolution logic in buildJsDocs function to handle missing files (4b4b6cca2)
Fix favicon path resolution in buildJsDocs function to handle missing files (a572ffaf8)
Update favicon path in buildJsDocs function to use publicClientId for dynamic resolution (d839d6a02)

monitor

Add support for custom image names in deployment scripts (2d4ddf731)
Enhance transport handling in UnderpostMonitor: Default to exec, add opt-in for http (eebe7ef03)
Refactor test-monitor script: Enhance deployment modes and flag parsing (07b65b004)
Enhance runtime status handling with exec transport and kubernetes gate (135773938)

deploy

Refactor deployment commands to use dynamic node names and update MongoDB flag in run command (b6a1dc9c7)

cli-start

Add error handling for deployment build/init process in UnderpostStartUp class (6c7d7e056)
Add support for private test repositories in build and monitor scripts (23837d02b)

ipfs

Refactor IPFS API URL functions to include container check for development environment (61e3fcd1e)

client-core

Fix bug Panel component; when the user writes markdown content but uploads missing reload md file (f91da9780)

New release v:3.2.21 (2026-06-06)

release

Add options for MongoDB and Valkey configuration in build process (7dba2a68a)

repository

Enhance deployment process: Include deploy ID in logging and update build commands (aedd99415)
Add --has-changes option to check for staged or unstaged git changes and update template repo logic (f479994a4)
Ensure repository directory is created before initialization (5cb66853f)

docs

Refactor CLI documentation generation: Update command argument and option sections for improved clarity (fd20febb1)

deploy

Add support for self-signed TLS certificates and related options in deployment scripts (d03ddf7b7)
Add localProxy option to enable TCP port forwarding and path-based routing (6b6c03a4c)
Add exposeLocalPort option for custom local port configuration in deployment (60fe88b95)
Refactor deployment scripts: Update commands in engine-test workflow and add link-local CLI script (8506dbca4)

cli-run

Add build-cluster-deployment-manifests method and update test-monitor script: Implement deployment manifest building for production and development environments. (be2c5a71e)
Add etc-hosts method: Modify /etc/hosts file for local service access (c4e7ba286)

monitor

Refactor monitoring and deployment port resolution: Introduce deployStatusPort for consistent internal status port handling and implement findFreePort for ephemeral TCP port allocation. (735c2c41e)
Add test-monitor script: Implement deployment and monitoring commands for development environment (a74316ae1)
Implement reliable two-phase deployment monitoring with internal HTTP status endpoint (a2b49dcd6)
Improve pod status handling: Exclude 'empty' status from container status checks (6d18e2872)
Improve pod status handling: Exclude 'empty' status from advanced pod tracking (a90400342)

build-template

Add option to update private template repository (77cbe276a)

runtime-cyberia

Refactor Dockerfiles: Standardize comments and clean up unnecessary lines (6ae4d0bef)

engine-cyberia

Enhance dialogue and quest systems: Add new dialogue entries for Lain, update action types, and revise implementation status in documentation (67702fa9c)

cyberia-cli

Add Mongo host override option to import command for Object Layer items (b181892b4)

env

Simplify environment variable check: Remove redundant logging for empty env path (b192cdff4)

New release v:3.2.14 (2026-06-02)

runtime-wp

Enhance Dockerfile: Add retry logic for XAMPP installation to handle flaky SourceForge transfers (d76f7ec69)

cli-run

Bundle runner: Enhance client build process by adding options for zip building and replica handling; improve bundle upload logic for deployment (ee79ccfea)
Add shared-dir command execution to UnderpostRun class (a5d6a3a09)

monitor

Enhance pod status monitoring by adding advanced error checks and tracking for container status regressions (de54ee20c)
Refactor deployment monitoring and image management; add tests for deployment failure detection (819d17f30)

github-actions

Add GITHUB_USERNAME environment variable to CI workflows for better repository management (2f47aaaa1)
Update CI workflows to use environment-specific configuration files for engine core, cyberia, lampp, prototype, and test (5c94eedf5)
Add conditional checks to skip commit and push if no changes are detected in CI workflows (033afed27)
Add npm install step to CI workflows for engine core, cyberia, lampp, prototype, and test (25457022f)
Add sparse checkout and configuration updates for engine prototype workflows (787cbac2b)
Add prototype ci cd workflows (147f9c90e)

docs

Refactor CLI documentation generation in buildCliDoc (fd2ef99ba)
Update architecture and server documentation (a3eefadd1)
Refactor documentation for Cyberia and Underpost Platform (36c8234df)

bin-build

Enhance build process by adding source repo validation and restoration; implement pullSourceRepo method for managing public source repositories (7cf35bcd8)
Enhance build process by adding template rebuild option and refactoring build template logic; streamline deployment template assembly (eb28b47f3)
Refactor build main entry logic related to CI workflows and build process for engine components (d1aba687a)

catalog

Refactor build process and introduce dynamic product catalogs for Cyberia and Prototype; enhance deployment template assembly and configuration syncing (65dc9cc6b)

engine-prototype

Add deployment and proxy configurations for dd-prototype-development (40549234c)

repository

Refactor CI workflow and enhance repository management with sparse checkout functionality (27485162d)

engine

Remove update defualt conf.js per deploy-id workflow (746285d10)

engine-core

Remove no core src (1a90ce0d7)

CYBERIA

Network Object Layers

Stackable Rendering Layers as a Unified Tokenized Reality

Cyberia is an MMORPG extension built on the Underpost Platform. The platform owns the toolchain, deployment surface, PWA delivery, and base infrastructure. Cyberia adds a three-service MMO runtime: `engine-cyberia`, `cyberia-server`, and `cyberia-client`.

engine-cyberia is the sidecar-backed data layer: a Node.js sidecar that owns content,
validation, persistence, the gRPC/REST data services, and asset metadata. It backs the authoritative
Go server and the WASM client with data — it does not run the simulation or the presentation.

Ecosystem at a glance

                         ┌───────────────────────────────────────────────┐
                         │              UNDERPOST PLATFORM                 │
                         │  toolchain · deploy · PWA build · static        │
                         │  delivery · cluster/image/db · monitoring       │
                         │                                                 │
                         │   underpost CLI  ──▶  builds & deploys all      │
                         └───────────────────────────────────────────────┘
                                            │  hosts / delivers
                                            ▼
   ╔═══════════════════════════════ CYBERIA MMO ══════════════════════════════════╗
   ║                                                                               ║
   ║   ┌──────────────────┐   gRPC    ┌──────────────────┐   WebSocket            ║
   ║   │  engine-cyberia  │ ────────▶ │  cyberia-server  │ ───────────┐           ║
   ║   │     (Node.js)    │           │       (Go)       │            │           ║
   ║   │                  │           │                  │            ▼           ║
   ║   │ content          │           │ authoritative    │   ┌──────────────────┐ ║
   ║   │ validation       │           │ simulation       │   │  cyberia-client  │ ║
   ║   │ persistence      │           │ world tick       │   │    (C / WASM)    │ ║
   ║   │ gRPC/REST data   │           │ AOI replication  │   │                  │ ║
   ║   │ asset metadata   │           │                  │   │ rendering        │ ║
   ║   └──────────────────┘           └──────────────────┘   │ input            │ ║
   ║            │                                             │ prediction       │ ║
   ║            └──────────────── REST (content/assets) ─────▶│ presentation     │ ║
   ║                                                          └──────────────────┘ ║
   ╚═══════════════════════════════════════════════════════════════════════════════╝

   One source of truth per concern:
     content & world config ── engine-cyberia
     real-time world state  ── cyberia-server
     presentation & input   ── cyberia-client

1. Toolchain and base infrastructure

Underpost Platform is the operational backbone and the source of truth for deploy IDs, runtime
selection, host/path layout, generated client assets, and environment resolution.

Area	What it owns
Toolchain	`underpost` CLI, build, deploy, release, metadata, secrets, environment selection
Infrastructure	bare metal, LXD, Kubernetes, K3s, kubeadm, images, SSH, runners
Data operations	MongoDB, MariaDB where needed, backups, cron, monitoring
Delivery	static build, SSR views, PWA packaging, service worker generation, host/path routing

underpost is the shared control surface for everything infrastructural. Cyberia-specific work belongs
in the cyberia CLI, never in parallel platform commands. When a concern already exists in underpost,
reuse it instead of forking a Cyberia variant.

2. PWA workflow

Every deployed client ships as a static application shell with PWA support. The pipeline has exactly two
inputs:

the deploy ssr configuration in conf.dd-*.js (or conf.ssr.json)
the service worker source in src/client/sw/core.sw.js

Everything else — index.html pages, sw.js, the precache list — is generated during the client
build. Treat them as outputs only; never hand-edit them.

Runtime service-worker behavior:

Request	Strategy
static assets	stale-while-revalidate
API `GET`	network-first + short cache
API mutations	network-only + background replay
navigation	network-first + fallback shells

Fallback selection: offline network → offline fallback view; origin/server failure → maintenance
fallback view. Only fallback-marked views are guaranteed precached.

3. Cyberia MMO extension

Responsibility split

Service	Owns	Must not own
`engine-cyberia`	content, validation, persistence, gRPC/REST data services, asset metadata	authoritative simulation, render policy
`cyberia-server`	authoritative simulation, world tick, gameplay mutation, AOI replication	content authority, presentation metadata
`cyberia-client`	rendering, input, prediction, interpolation, presentation	authoritative world state, gameplay authority

Two boundaries are non-negotiable:

Do not move authoritative logic into the client.
Do not move content-authority logic into the Go runtime.

Data flow

engine-cyberia ──gRPC──▶ cyberia-server ──WebSocket──▶ cyberia-client
engine-cyberia ──REST──────────────────────────────▶ cyberia-client

`engine-cyberia` as the sidecar-backed data layer

engine-cyberia is the only Cyberia service that owns content-backed data and asset metadata.

Boot-time world configuration flows from engine-cyberia to cyberia-server over gRPC GetFullInstance.
Client-facing assets, object layers, dialogues, and presentation hints flow from engine-cyberia to cyberia-client over REST.
Simulation never migrates into the sidecar, and presentation policy never migrates out of the client.

Runtime / health model

Three supervised processes run in parallel, each with its own monitor and reconnect loop. Gameplay is live only when all three are healthy at once.

        ┌──────────────────────────────────────────────────────────────┐
        │                    SUPERVISION (parallel)                      │
        │                                                                │
        │   engine-cyberia        cyberia-server        cyberia-client   │
        │   ┌────────────┐        ┌────────────┐        ┌────────────┐   │
        │   │  monitor   │        │  monitor   │        │  monitor   │   │
        │   │ +reconnect │        │ +reconnect │        │ +reconnect │   │
        │   └─────┬──────┘        └─────┬──────┘        └─────┬──────┘   │
        │         │                     │                     │          │
        │         └──────────┬──────────┴──────────┬──────────┘          │
        │                    ▼                     ▼                     │
        │            all three up & connected?                          │
        └────────────────────────────┬─────────────────────────────────┘
                                      │
                ┌─────────────────────┼─────────────────────┐
                ▼                     ▼                     ▼
          ┌───────────┐        ┌───────────┐         ┌───────────┐
          │  HEALTHY  │        │ DEGRADED  │         │  STANDBY  │
          │ all 3 up  │        │ ≥1 service│         │ gameplay  │
          │ gameplay  │        │ reconnect-│         │ paused    │
          │ live      │        │ ing / down│         │ until all │
          │           │        │           │         │ 3 healthy │
          └───────────┘        └───────────┘         └───────────┘

State	Meaning
`healthy`	all three Cyberia services are up and connected
`degraded`	at least one service is reconnecting or unavailable
`standby`	gameplay is paused because the full three-service set is not healthy

User commands

Use underpost for platform, infrastructure, build, and deploy. Use cyberia for MMO content and
extension workflows. Both share the same helpers — never duplicate config, env, or path logic.

Platform (underpost)

# Bootstrap a new app (local app serves on http://localhost:4001)
underpost new app-name

# Build the client bundle / static + PWA output
underpost client
npm run build            # node bin client

# Deploy and operate
underpost deploy <deploy-id>
underpost monitor

Cyberia (cyberia) — `bin/cyberia.js`

Group	Command	Purpose
`ol`	`cyberia ol [item-id]`	ObjectLayer import, procedural generation, atlas/sprite
`instance`	`cyberia instance [instance-code]`	export / import / drop a Cyberia instance and its data
`client-hints`	`cyberia client-hints [instance-code]`	per-instance presentation hints (palette, camera, icons)
`chain`	`cyberia chain <sub>`	Hyperledger Besu + ERC-1155 ObjectLayerToken lifecycle
`run-workflow`	`cyberia run-workflow <name>`	named maintenance/build scripts from `scripts/`

Common examples:

# Object layer content
cyberia ol hatchet,sword --import                 # import specific items
cyberia ol --import-types skin,floors             # batch import by type (or: all)
cyberia ol floor-desert --generate --seed fx-42   # procedural generation
cyberia ol hatchet --to-atlas-sprite-sheet        # build atlas sprite sheet
cyberia ol --drop --client-public                 # drop data + static asset folders

# Instance data
cyberia instance FOREST --export ./backup
cyberia instance FOREST --import ./backup
cyberia instance FOREST --drop

# Presentation hints
cyberia client-hints cyberia-main --seed-defaults

# Chain / token lifecycle
cyberia chain deploy --chain-id 777771
cyberia chain status
cyberia chain register / mint / transfer / burn / pause / unpause

# Named workflows
cyberia run-workflow import-default-items
cyberia run-workflow seed-skill-config --instance-code default
cyberia run-workflow seed-dialogues
cyberia run-workflow build-manifest
cyberia run-workflow build-server-dashboard

Run the MMO services

# engine-cyberia (Node.js data/content services)
npm start                                          # node src/server

# cyberia-server (Go authoritative simulation)
cd cyberia-server && go run main.go                # dev
cd cyberia-server && go build -o cyberia-server . && ./cyberia-server

# cyberia-client (C / WASM presentation)
cd cyberia-client && make -f Web.mk clean && make -f Web.mk web
cd cyberia-client && make -f Web.mk serve-development     # serves on :8082

v3.2.22

Changelog v3.2.22

2026-06-07

repository

docs

monitor

deploy

cli-start

ipfs

client-core

New release v:3.2.21 (2026-06-06)

release

repository

docs

deploy

cli-run

monitor

build-template

runtime-cyberia

engine-cyberia

cyberia-cli

env

New release v:3.2.14 (2026-06-02)

runtime-wp

cli-run

monitor

github-actions

docs

bin-build

catalog

engine-prototype

repository

engine

engine-core

CYBERIA

Ecosystem at a glance

1. Toolchain and base infrastructure

2. PWA workflow

3. Cyberia MMO extension

Responsibility split

Data flow

engine-cyberia as the sidecar-backed data layer

Runtime / health model

User commands

Platform (underpost)

Cyberia (cyberia) — bin/cyberia.js

Run the MMO services

Uh oh!

`engine-cyberia` as the sidecar-backed data layer

Cyberia (cyberia) — `bin/cyberia.js`