Files
aeternalis/docs/ARCHITECTURE.md
T

19 KiB

Architecture and vision review

Reviewed 2026-09-05 against C:/Dev/aeternalis/planning/VISION.md and the earlier RPGTheory design notes. The new weekly boss rule is authoritative over the older uncertain session-ending description.

Assessment

The vision has a coherent distinguishing loop: players invest in a single life, cooperate against a closing deadline, and earn passage to a new world. The browser is a reasonable first client. Chunk subscriptions and GPU instancing address some client costs, but do not prove that thousands of players can gather around one boss. Changing to a native client would not remove simulation, bandwidth, or persistence bottlenecks. Measure before changing platforms.

The highest-risk requirements are:

  1. Death and transfers must remain correct after retries, crashes, and redeploys. A duplicated survivor or resurrected character undermines the one-life premise.
  2. One world is explicitly one server instance. Kubernetes adds world capacity by adding independent owners; replicating the same world deployment does not share its simulation. A crowded final boss bypasses the benefit of small AOIs.
  3. Nine 128-unit chunks are a subscription rule, not a complete scaling plan. Entity density, bytes/update, allocation rate, AI work, and client draw cost need separate budgets and load measurements.
  4. Two hours per day and a destructive weekly event interact. The prototype protects a capped character from enemies in a central safe zone, but does not exempt it from final world collapse or grant passage before the boss dies. Offline-world survival is an explicit provisional rule requiring playtesting.
  5. Five worlds opened together also reach their deadlines together. Operators need to open fresh destinations before survivors transfer. There is no automatic Kubernetes world allocator in this slice.

Implemented boundaries

The creator detour adds bounded, versioned procedural appearance recipes. Go validates and persists character looks and admin-authored visual presets; resource/mob definitions copy their selected recipes. Three.js builds matching preview, world, housing, and export geometry, merging by material and instancing repeated appearances. Appearance does not affect gameplay geometry or stats. Full rigs, visible equipment, animation/audio, and CDN uploads remain.

Revised milestone 3 places a world portal and one shared housing entrance in each hub. Source-owner travel and housing transactions validate physical proximity and obstruction; key-targeted entry also validates the exact active carried key. Existing transfer escrow and housing permission/recovery ledgers remain authoritative. See physical entrances for the manual handoff.

Planning update: the vision now includes corpse-based item/spell resurrection, key-owned hub housing, crafting rolls/provenance, and portal dungeon instances. Milestone 7 now implements corpse resurrection for new deaths. Milestone 8b adds key-owned housing documents and floor-plan controls; 8c adds walkable interiors and leased cross-hub visitor presence. Portal dungeon instances remain. See planning/SYSTEMS-ROADMAP.md for future lifecycle rules and unresolved details. The milestone 1 lifecycle and ownership contract maps the current code to proposed states, transaction boundaries, and migration steps. Its later lifecycle systems remain specifications. Milestone 5 implements hub/survival kinds and durable travel escrow: source departure and destination acceptance each commit under their own owner lease, with the account reserved throughout transit. Hub crafting suppresses XP and retains daily usage.

One Go process owns one world, with a serial simulation protected by one lock. Housing membership stays with the current hub's character owner. Separate shared house documents and key ledgers serialize storage/permission/key changes with the fenced character snapshot, so all hubs access the same retained contents. The three-second action destroys a key; only completion removing the last valid key archives a house. Recovery and purge follow the recorded creator death world. See milestone 8b for the lifecycle and 8c for indoor movement, rendering, visitor consistency, bounds, and manual tests. Clients submit bounded intents. The server determines speed, terrain height, range, cooldown, inventory changes, damage, death, play-time, and passage eligibility. Movement is interpolated on the client; full prediction/reconciliation is deferred. Client movement and action intents run on a bounded 50ms timer, independent of render frames. Elapsed time controls retries without replaying missed timer ticks; hidden tabs and open menus clear movement/actions. Rendering alone clamps its interpolation step. An open WebSocket shows "Synchronizing world" until a valid world snapshot has been processed; reconnect clears the previous input snapshot. No rigid-body physics is claimed: this is heightfield movement in open terrain.

Milestone 3 adds authoritative vertical jump velocity and gravity over that heightfield. Generator 2 increases terrain depth and chooses weighted biomes; generator 1 remains supported with unchanged heights/resource identities. Explored resource layouts are persisted separately from evictable terrain meshes. New catalog resources affect unexplored chunks in generator-2 worlds. Skill IDs are content references, not gameplay enums: one progression/modifier/risk path handles all gathering professions. Character snapshots retain skill XP, cooldowns, and copied timed gathering effects with absolute expiry. Server snapshots publish personalized risk per resource definition, avoiding a repeated payload per node. See milestone 3 for tuning, bounds, compatibility, and manual tests.

The simulation ticks at 20 Hz; snapshots are sent at 5 Hz. Coordinates use X/Z chunk indices and Y height. Terrain has a vertical coordinate but is a 2.5D heightfield, not a volumetric 128x128x128 voxel world. Overhangs, caves, stacked chunks, and fully destructible voxel terrain require another generator/version. Destruction currently means a shrinking hazardous boundary, not terrain deformation.

OpenSimplex supplies seeded noise. A versioned generator produces chunk meshes and resources only as needed. Mesh height and server collision height share a triangle split. A connection subscribes to current chunk + eight neighbors. Unchanged terrain and static resource transforms are not resent; resource availability IDs and dynamic entities are filtered by this area. GPU terrain is disposed on eviction. Repeated GLB meshes use instancing; camera frustum culling is separate from network interest. The server retains mutation deltas across chunk eviction.

The finite circular world, 48-unit spawn separation, 100-character capacity, combat numbers, terrain details, mob scaling, and respawn periods are provisional defaults. They are not newly confirmed design decisions. Balance is validated and persisted with the world. YAML initializes new worlds; Control publishes a shared, versioned title/equipment/stat catalog that world owners apply and checkpoint.

Durability and ownership

September 11 review: the reliability and persistence plan verifies duplicate whole-world payload writes and projection synchronization under the simulation lock. Revised milestone 4 now makes their bounded repair, followed by partitioned durable storage and recovery qualification, prerequisites for the expanding-world generator. Preserve the current ownership/fencing and atomic lifecycle claims. The storage design below describes current behavior; the plan's journal and asynchronous checkpoints are not implemented yet.

Milestone 7 adds copied character-owned spells/ranks/cooldowns and weapon XP, preserved by travel and revival and absent from replacement characters. Go owns learning, unlocks, cast release, useful-hit XP, and moving aura effects. Pending casts cancel across restart/travel. See milestone 7 for scope.

Resurrection stages consent-checked corpse revival and resource costs before an owner/revision-fenced transaction. account_lives records the latest character ever created, including after death; replacement permanently invalidates older revival eligibility. character_deaths archives distinct death occurrences and atomically claims revival once. A new-life insert trigger maintains the pointer for older writers during deployment. Corpse loot, restored character, costs, and death claim commit together. Old deaths without a revival identity remain final; world destruction still prevents revival. Daily limits and transfer ownership continue to apply.

Development uses SQLite WAL. Production requires PostgreSQL with TLS certificate verification. Both use the same storage tests and transaction behavior.

The worlds row has an expiring owner token and a monotonically increasing revision. Every save atomically checks owner, lease expiry using database time, and expected revision. A competing process cannot acquire an unexpired lease, and a previous owner cannot write after replacement. Lease renewal accompanies regular saves; a stopped/crashed process releases or expires after 30 seconds.

World snapshots are saved every second and on material gameplay changes before the next client snapshot. Victory creates survivor passage records in that same transaction. A destination saves its imported character and marks the passage redeemed in one transaction. Later victories can issue a new passage for the same character ID; old source servers cannot overwrite it. Account identity is checked at redemption, and the destination rejects duplicate accounts/characters.

On storage failure the process freezes and fails readiness/liveness, closes its sockets, and must restart/reload durable state. This avoids continuing after an ambiguous commit. Default shutdown allows 10 seconds to save and release ownership. Treat backup/restore as an explicit administrative operation: restoring an old database can reverse deaths and transfers, so production needs a restoration policy.

Prototype durability limit: an abrupt crash can roll back up to one second of position and daily play usage. Gameplay mutations are acknowledged after a save; unacknowledged inputs can disappear. Whole-world JSON checkpoints occur under the simulation lock, currently with two serializations/payload updates in the general save path. The dirty-or-periodic trigger also saves unchanged worlds. Explored resource layouts remain resident/persisted after mesh eviction, so every save grows with exploration. This is an architectural limit, not only a tuning issue. Separate fenced lease heartbeats before suppressing idle payload writes; offline lifecycle deadlines must still run. Replace full-world saves with partitioned state, a durable event log, asynchronous checkpoints, versioned migrations, and crash/latency fault injection before expanding worlds. Do not remove retained corpses or weaken permanent-death, daily-time, or transfer rules to reduce cost.

Progression and permanent titles

The Go simulation awards character XP for successful gathering, crafting, mob kills, and the boss killing blow. Each crossed level threshold banks 10 stat points, adds 5 stamina, and banks a choice of 5 maximum health or mana. Seven primary attributes accept allocation intents; all derived values are calculated in Go. Levels, choices, allocations, XP, and the character's level curve survive restart and survivor passage. Replacement characters start at level 1. Legacy characters receive the extra points and pending vital choices for already-earned levels once, while retaining deaths, XP, and daily usage.

Title requirements are evaluated in Go and produce ordered award candidates. The shared database resolves first-world and first-ever claims in the same transaction as the owner/revision-checked world snapshot, character registry, and survivor passages. A conflicting first claim is an ordinary lost race. Only committed awards appear in the character view or affect combat/movement. The immutable account ledger preserves title ownership after death and across worlds; death records retain their titles and new lives inherit account awards. This is current implementation behavior, superseded by the confirmed design: only cosmetic access carries to replacement characters. Titles and all character progression will be character-owned; revival/travel preserve them and replacement resets them. The title ledger requires a migration that preserves historical first claims and explicitly handles awards already inherited. No migration is applied by this documentation update; see the lifecycle contract. Awarded names, descriptions, effects, and provenance are copied at grant time; later content changes do not remove or alter an earned title.

Audited administrator player commands are an exception to gameplay title permanence. Revocation records suppress active ownership/effects and future automatic awards; the original immutable award and first claim remain intact. Explicit admin restoration reactivates that original award. Dead-life history is not rewritten. Item and title commands stage their changes inside the owner-checked save transaction, after locking character registry rows, and update survivor passages and audit results atomically.

All earned title effects are active once per title ID. Flat bonuses are summed, then combined percentage bonuses apply. Modified primaries feed the derived-stat formulas. Existing damage/movement effects remain compatible. None can alter death, the daily play budget, or passage eligibility. See progression configuration.

Control publications serialize on a singleton catalog row, check the editor's expected version, and record an immutable audit entry in the same transaction. Title/item IDs are append-only; stat formulas can be updated. Owners poll under the simulation lock and checkpoint updates before snapshots. New title requirements are evaluated on the next gameplay event. Published content cannot rewrite earned title awards or acquired equipment snapshots.

Milestone 2 adds immutable reusable requirement/effect sets to that same catalog. Publication resolves them into concrete title/item requirements and stat modifiers; no live references can rewrite awards or equipment. The admin preview endpoint uses the same semantic validation without writing catalog/audit state. Existing catalogs without set collections remain compatible. Input actions and a shared focused-menu handler separate keyboard/pointer input from intents; Esc closes one focused menu. See milestone 2 handoff for manual checks and scope.

Equipment instances retain identity across equip, drop, corpse loot, and passage. All equipment effects are excluded when checking prerequisites, preventing items from enabling themselves or each other. Invalidated equipment returns to the bag. Legacy knife/spear stacks migrate once, including corpses; duplicate instance IDs within a world fail restoration. Materials and consumables remain quantity stacks.

Combat and mobs

Milestone 8a adds copied structure definitions and world-owned structure snapshots. The server checks kit consumption, profession level, placement bounds/obstacles, and protected locations. Swept box intersections support movement/projectile collision and combat sight checks. Structures can be attacked and destroyed by players and nearby aggressive/guard mobs. Housing is still pending; see the building checkpoint for scope and manual verification.

Biomes now retain a stable ID with server-assigned revisions and archived resource assignments. Explicit resource ID lists replace reverse resource-to-biome lookup for revised/new biomes; legacy lists are resolved on first edit. New resource publication revisions its selected biomes in the same catalog transaction. Explored layouts remain snapshots and do not regenerate when a biome changes.

Projectile speed samples weapon settings and final Dexterity/Strength at firing. A bounded two-second launch/impact journal accompanies snapshots so short flights are visible even if they complete between publications. Client presentation deduplicates these events; only the Go collision path determines outcomes. The journal is presentation history, not an input command or reward queue.

Combat attack definitions are copied into weapon and mob instances. Go resolves straight projectiles with swept target collision and terrain obstruction, and bounded stationary damage/healing areas. Living-source checks preserve death and shelter boundaries. Projectiles, areas, mob identity/home/health, and loot rolls are persisted in world snapshots; impacts and spawn-command outcomes commit before publication. Mob motion crosses chunks with local slope checks and home leashes; inactive mobs retain state. Region spawn rules use persisted explored biome IDs (legacy layouts fall back to their stored biome names). See milestone 4 handoff for behavior, limits, and manual checks.

Security scope

Crafting accepts authenticated ingredient offers through POST /api/craft under the world mutex. The server stages the character, resolves the secret recipe and random result, then saves consumption, discovery, XP, item provenance, and an account-scoped replay receipt in one lease/revision-fenced transaction. Live state and success feedback are published only after commit. Recipe definitions are admin-only; players receive only their own recorded discoveries. Crafted stack batches accompany aggregate inventory totals through consumption, corpse loot, and travel. See milestone 6 for bounds and manual checks.

  • Production login: OIDC verification (issuer, audience, signature, expiry), PKCE, state and nonce binding, and opaque server-side sessions.
  • Secure, HttpOnly, SameSite cookies. No client-controlled identity or progression.
  • Explicit same-origin checks on mutations and WebSockets; no permissive CORS.
  • Strict JSON parsing, small input limits, sequence checks, HTTP/WS rate limits, action validation, movement timeout, and bounded slow-consumer queues.
  • CSP, no framing, MIME sniff protection, HSTS in production, and no token logging.
  • A non-root, read-only runtime container with all capabilities dropped, no service account token, health probes, TLS ingress, and limited network egress.

The application limiter uses the real TCP peer address, not untrusted forwarded headers. Behind ingress this may group many users into one bucket. Configure trusted-proxy-aware rate limiting before public load; the chart's ingress rate limit is an additional layer. OIDC provider callbacks and JWKS refresh, TLS, network policies, actual ingress behavior, backups, secret rotation, and dependency scanning must be tested on the real cluster. This code is not a completed security audit.

Source references