Changelog v3.3.76

2026-09-13

test-unit

Skip cyberia product suites where the tree does not ship them (93c4f0906)

client-core

Add top-left hamburger menu button while the top bar is collapsed (43b00dcd1)

Cyberia

Fix minified atlas sprite sheet workload and validations (b64cbf23a)
Reuse authored cells when importing an object layer (117e0e620)
Stage direction frames at one uniform size for webp (82b4acac6)
Preview items and entity maps by the atlas idle still (c5fb8ae62)
Cut an idle-preview still from each atlas render (0402a1243)
Wire signed stats and entity levels through boot payloads (56000de95)
Add entity levels and progression rules to the game defaults (208530c45)
Sign stat modifiers in the shared contract (29df5fc49)
Preview both atlas renders in the object-layer viewer (8e8441f6e)
Read the audio File fields from the reference registry (0e3ca2903)
Take the atlas renders when collapsing duplicate layers (8dcc9ed1a)
Purge an atlas and its renders through the store (943e9e4c5)
Add the File reference registry module (6b7610101)
Navigate editors by instance code and item id (d87a56818)
Store two atlas renders and refresh the minified one (73ffe183e)
Bind item-pickup and craft audio events (3b0f1069d)
Add dropChance to entity-type-default overrides (5014c7e33)
Generate pixel-faithful sprite sheet atlases (dfba47760)
Resolve object-layer item identity and map previews (2bd4f88d1)
Reference entity-type defaults by id and derive skills from content (f669fa94f)
Add audio assets and per-map audio configuration (3ec20cb33)
Fix mentions of wasm-driver.py (d748d11dc)
Cleared coments (602f984a0)

cyberia-client

Surface featured worlds on the portal landing (90c528be5)

object-layer-engine

Add axis rulers and cursor readout to the pixel canvas (cd4955c6b)
Add cut, copy, paste, and scale tools with toolbar UI fixes (e215b3583)

cyberia-docs

Document the idle-preview still (4344d73b9)
Document the signed stat contract and progression (b7a4c3301)
Reflow the audio option table and emphasis (8358fe5e8)
Document the ol atlas renders and rebuild options (888c7bcbf)
Reflow tables and emphasis across the architecture docs (64c7e3a2d)
Document the Data Server URL as a required command-line flag (28c4a51e4)
Document Data Server flags and manifest CLI (74a09d397)

cyberia-cli

Carry the idle still through ol minify and backups (f41f66f52)
Require an explicit source for the ol import commands (b7c759a2e)
Implement restore OL backup workflow for a single itemId version instance and related document (293a62db2)
Add copy manifests in cyberia-instance repository build workflow (0f40c2b82)
Rework sync-src as a bidirectional dry-run mirror (6f05a7dc6)
Integrated the cyberia public assets folders module into the cyberia repo's publish workflows (7e5c0e0a7)
Integrated the cyberia-audio project module into the cyberia repo publish workflows (07993ee93)

engine

Publish per-suite coverage reports as deploy artifacts (f37be7ba6)
Resolve instances and maps by their codes (2daca38b8)
Lower the default request timeouts to ten seconds (9fbb5c844)
Publish products with the engine runtime dependency set (8bd9a12a3)
Redact adjacent credentials in service error messages (e8ad83ae6)
Fail downloads that stop short of their declared length (2cb52c254)
Replace adm-zip with jszip and shared archive helpers (14e4857c4)
Allow cross-origin reads on CRUD controllers (7100c5ee4)

test

Fix cyberia stat-contract coverall (faf4f4378)
Move sprite atlas and object-layer minify tests to the cyberia tier (931d98277)

cli-cyberia

Add the stat balancing policies and contract generation to the CLI (d6f477f59)
Route drops and imports through the atlas store purge (0a103f6e8)
Rework the ol command on the stored atlas renders (73b5c2fa2)
Sync the cyberia-instances checkout on publish with cmt --switch-repo (66ffde978)
Keep CLI-name arguments through the underpost reroute (e898bf498)
Add ol --minify reprocessing scoped to instances (9b19bfc1e)

docs

Regenerate the CLI references for the storage and bundle options (4ce71e989)

cli

Warn when a container resolves no OCI env overlay (20dcb3897)
Rework push-bundle and pull-bundle as one client bundle transport (ead02902b)
Rework fs selection around storage manifests (26471a64b)
Resolve instance root path from conf in instance-build-manifest (fd08a771b)
Deploy Mongo Express through the cluster command (4a9d03fbb)

cli-wireguard

Install the landed source before any step runs it (96db68293)

deploy

Consolidate deploy scripts on shared constants and bundle sync (dd9d1d368)
Stream the deploy log verbatim in a new debug mode (1d41af6c0)
Fix git track storage in dd-cyberia sync-deploy (3ed3c297d)

runtime-cyberia-server

Upgrade go version v1.25 (2a14dd26a)
Pass Data Server endpoints to cyberia-server as flags (c8b4a1b54)

runtime-cyberia-client

Add CYBERIA_DATA_SERVER_URL on cyberia-client dockerfiles runtime (99738cc80)

package

Update qs version >= 6.16.0 via overrides (b7697d52b)

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-skills
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

Operational guardrails

Prefer one source of truth for config, deploy IDs, runtime selection, startup behavior, and generated assets.
Reuse existing helpers and conventions instead of creating parallel implementations.
Do not duplicate parsing, env resolution, or path normalization logic across modules.
Treat generated artifacts (sw.js, static pages, atlases, README, manifests) as outputs only.
Host-level changes must be idempotent, reversible, and explicit; validate before mutating; keep
orchestration scripts safe to rerun.
engine-private/ is a private external dependency. Reference it only as private input; never assume
its contents exist locally.

v3.3.76