Files
aeternalis/docs/ARCHITECTURE.md
T

261 lines
17 KiB
Markdown

# 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.
Milestone 7 now implements corpse resurrection for new deaths. Key-owned housing
and portal dungeon instances remain design requirements. See
`planning/SYSTEMS-ROADMAP.md` for future lifecycle rules and unresolved details.
The milestone 1 [lifecycle and ownership contract](LIFECYCLE-OWNERSHIP.md) maps the
current code to proposed states, transaction boundaries, and migration steps.
Its later lifecycle systems remain specifications. [Milestone 5](MILESTONE-5.md)
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.
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](MILESTONE-3.md) 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
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](MILESTONE-7.md) 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 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](PROGRESSION.md).
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](MILESTONE-2.md) 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](MILESTONE-8A.md) 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](MILESTONE-4.md) 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](MILESTONE-6.md) 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
- [Three.js instanced rendering](https://threejs.org/docs/pages/InstancedMesh.html)
- [Three.js object-count optimization](https://threejs.org/manual/en/optimize-lots-of-objects.html)
- [Kubernetes security contexts](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/)
- [Gitea Actions runner setup](https://docs.gitea.com/usage/actions/quickstart/)