8.7 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:
- Death and transfers must remain correct after retries, crashes, and redeploys. A duplicated survivor or resurrected character undermines the one-life premise.
- 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.
- 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.
- 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.
- 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
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.
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; editing YAML affects newly created world IDs only.
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 stat points; there is no allocation intent until the stat design is defined. Levels, XP, points, and the character's original level curve survive restart and survivor passage. Replacement characters start at level 1. Existing snapshots receive level 1 and the initial progression defaults once, without retroactive XP or points, while preserving deaths 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 account inheritance is the initial interpretation of player-bound titles. Awarded names, descriptions, effects, and provenance are copied at grant time; later content changes do not remove or alter an earned title.
All earned title effects are active and additive, once per title ID. The initial effect hooks are damage and movement speed; both accept positive and negative values, with effective damage/speed floored at zero. They cannot alter death, the daily play budget, or passage eligibility. The broader stat and effect catalog remains open. See progression configuration.
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.