144 lines
8.7 KiB
Markdown
144 lines
8.7 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
|
|
|
|
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](PROGRESSION.md).
|
|
|
|
## 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
|
|
|
|
- [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/)
|