309 lines
20 KiB
Markdown
309 lines
20 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
|
|
|
|
The [initial character creator](CHARACTER-CREATION.md) saves a bounded version-2
|
|
humanoid recipe alongside the name in the durable join transaction. Existing
|
|
characters retain their saved version and cannot restyle through the old endpoint.
|
|
The browser's 17-bone humanoid and equipment sockets are presentation metadata;
|
|
authoritative hitboxes, stats, time, and lifecycle rules are unchanged.
|
|
|
|
The [creator detour](CREATOR-WORKSHOP.md) 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](WORLD-ENTRANCES.md) 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](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.
|
|
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](MILESTONE-8B.md) for the lifecycle and [8c](MILESTONE-8C.md) 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.
|
|
|
|
Gather/loot approach sends a zero-movement intent and waits for a snapshot that
|
|
acknowledges it before attempting the action. That stopped server position is
|
|
checked again for range; stale pre-stop snapshots cannot trigger the action or
|
|
reverse the approach. Out-of-range confirmation resumes movement. This leaves
|
|
server range, cooldown, depletion, and loot ownership checks unchanged. The desktop
|
|
E2E check covers this with delayed snapshots and sparse input ticks.
|
|
|
|
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
|
|
|
|
**September 11 review:** [the reliability and persistence plan](../planning/RELIABILITY-AND-PERSISTENCE.md)
|
|
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](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, 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](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/)
|