Files
aeternalis/docs/ARCHITECTURE.md
T

12 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

Planning update: the vision now includes corpse-based item/spell resurrection, key-owned hub housing, crafting rolls/provenance, and portal dungeon instances. These are design requirements, not implemented behavior. This document's terminal death and current-world boundaries describe the running implementation; see planning/SYSTEMS-ROADMAP.md for the 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. It is a specification for later milestones, not an applied schema change.

One Go process owns one world, with a serial simulation protected by one lock. 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. 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

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 and are deliberately a simple first implementation. Before public permadeath or large worlds, replace this with a durable event log, asynchronous checkpoints, versioned migrations, and crash/latency fault injection.

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.

Security scope

  • 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