An architecture you can build on

Game rules can stand on their own.

kosuno_state has no engine, scene, GPU or physics dependency. It owns tracked resources, commands, change records, snapshots and model time. A game can exercise its rules in ordinary tests and run the same model on a client or an authority service.

Tracked records describe old and new values, map-key presence and resource lifecycle. They support rejected-command rollback, persistence, subscriptions and authority synchronization. Published changes can identify the command that caused them.

Rollback covers the supported tracked projection. Arbitrary native side effects, external I/O and skipped fields are outside that guarantee. Snapshot and field rollback policies have different supported mutation surfaces.

Packages define capabilities across hosts.

A project selects packages in Packages/packages.toml. Runtime, editor and cooker facets describe their capabilities and requirements. One resolver serves the editor, player and build tools; generated compositions link project-local Rust code without making the engine depend on a game.

Preflight checks content requirements before installation. Build probes inspect registrations in the compiled host. Source locks, plan fingerprints and artifact receipts govern reuse, so a cached executable must match its inputs and verified bytes.

The shared engine owns simulation ordering. Editor and player hosts wrap that work with input, presentation and authoring responsibilities. Shared code reduces divergence; each platform still needs acceptance testing.

Keep authored data and live state distinct.

Components store authoring data. Runtime state lives in entity-keyed stores and subsystems. Editor property changes therefore do not replace a component's live physics or rendering handles.

Entity references use session handles or persistent identities; tracked assets use GUIDs. Prefab instances store authored overrides and compose inherited data from the template. These boundaries make renames, template changes, reload and persistence easier to reason about.

Open registries let packages add component and asset types without extending a central list. The editor can preserve authored payloads for unavailable components until their package returns.

Trace content from authoring to a release.

The content graph tracks references, Used By relationships, diagnostics and inclusion chains. Plugins contribute semantic dependency readers. Build planning uses the same graph, and cooking captures inputs before producing release artifacts.

Scenes, animation clips, controllers, materials and environments have cooked binary forms. The cooker decodes its output and compares it with parsed authoring data. Machina can bake graph outputs into ordinary assets, separating procedural authoring from the player's runtime dependencies.

Local native releases use SHA-256-addressed objects and deterministic catalogs. A build record identifies the executable and its capabilities. Supported content-only updates reuse that record; local activation verifies the release before replacing the active-catalog pointer.

Content-only changes are restricted: script/shader sources, voxel baselines and assets with incomplete discovery are frozen against the original build record. Remote acquisition, publication and universal platform support remain work in progress.

Separate simulation reach from rendering.

A StreamingSource component sets a simulation radius around a player, vehicle or server observer. Scene-owned entity streaming runs at the command boundary in persistent-identity order, with a sparse spatial index for returning entities and a margin against boundary thrashing. It works in headless hosts and without voxel content. Its checkpoint section holds streamed-out entity state.

Voxel chunk reads and decoding use the content executor: worker threads on native hosts and a budgeted frame executor on single-threaded Web. Finished work is adopted at defined boundaries. Deterministic runs wait for the chunks they require so terrain collision does not depend on read timing.

The generic storage crate separates read-only content, writable project data and player-owned user data, with capabilities reported by each store. Native hosts supply a disposable cache; modified chunks and body snapshots can spill beyond the chunk-cache memory limit and return through asynchronous reads.

Entity streaming and voxel residency are separate systems. The voxel window still has one view center, and voxel residency is not checkpointed. Frame execution budgets cannot split an indivisible decode. Cache spill is session scratch, not a durable save, and memory-only hosts cannot use it to free memory. The Web player still preloads project files; fetch/Range, OPFS, IndexedDB backends and remote verified delivery remain planned.

Keep presentation connected to state.

State bindings drive vector document inputs as ordinary UI properties, including numbers, booleans, colors and text. Shared atlas pages render widgets into regions that the UI draws as batched quads. Static pages stay untouched until their content changes; continuously changing nodes move to dynamic pages. Direct vector rendering remains available for large panels. Both routes respect ancestor clipping.

Scroll views support drag, flick, elastic edges, snapping and wheel input. Vector runtimes keep scene-owned state, and checkpoint capture holds their animation layers, transitions, inputs and nested instances.

Text values carry literal content or a localization key and arguments. The independent kosuno_l10n crate formats ICU messages with locale-aware plural rules; labels and bound vector text resolve them for the player's locale. Locale is a player preference, separate from game state. Pseudo-localization and the loc check command help find expansion and table errors.

Localization is not complete: RTL layout, translator exchange, per-locale font/content loading and Story dialogue integration remain work to do. A checkpointed vector text input currently keeps its displayed string but loses its key until set again. Native UI captures on this site do not establish browser or mobile acceptance.

Declare rendering work and inspect its execution.

Render features declare passes, resource accesses and attachments. A GPU-independent compiler validates the graph, orders producers and consumers, culls work outside observable outputs, analyzes live resource lifetimes and identifies compatible raster-pass merges.

A structural cache reuses compiled analysis for matching declarations while preserving current callbacks and bindings. Feature-owned transient textures with identical descriptors can share storage when their compiled lifetimes do not overlap. Imported resources and pinned targets retain their own ownership rules.

The graph inspector exposes execution and allocation information. Mesh and voxel rendering share lighting contracts; optional backends negotiate their device requirements before creation. GPU timestamps and profiler export provide workload-specific measurements.

Texture pooling is exact-descriptor object reuse, not arbitrary GPU memory aliasing. Cache hits still declare and validate the graph. Allocation-count reductions and compile-cache results do not establish an end-to-end frame-rate improvement.

Follow a device problem below the renderer.

A many-pass vector UI workload exposed GPU-side process memory that wgpu's allocation report did not explain. The investigation traced Vulkan growth to retained command-pool memory and measured Metal's per-pass command-buffer cost. Shared vector atlas pages reduce pass counts at the engine level; a separate experimental wgpu branch records a single backend command buffer per encoder and trims idle Vulkan pools.

These are documented experimental-branch measurements, not a promise for every current Kosuno build or GPU. The work is not upstream. Metal's 10k-draw encoding benchmark showed a 3–9% CPU cost; other GPUs and iOS still need checks. The engine-side atlas and the experimental backend patch are separate changes.

Share rules between prediction and authority.

The client predicts commands locally, persists numbered batches before sending, and reconciles against authority replies. The authority processes batches once and in order, persists commits before acknowledgement, and uses ownership epochs to fence stale writers.

The authority core accepts messages and time and returns replies and commits; I/O sits in adapters. PostgreSQL storage and WebSocket transport exist, alongside a headless demonstration service and fault-injection tests.

This is an authority foundation. Production account integration, the scene-level backend package, multi-server routing, push and realtime replication are not complete. The current deployment is a single-server demonstration.