How GLOAMFALL works
The service architecture, fair results, catalogue versions, and honest alpha status.
Four services, one recorded result
| Part | Responsibility |
|---|---|
| Web · Next.js / React / Phaser | The Moonkeep, account screens, codex, input, arena rendering and audio. |
| API | Identity validation, progression, catalogue publication, social features and accounting. |
| Game server · Colyseus | Authoritative solo, co-op and Daily simulation; validates movement and choices. |
| Worker | Independent payment-event checks and reconciliation when configured. |
| PostgreSQL | Persistent account and game records. Local development can use embedded PGlite. |
Why the server decides
The game advances at a fixed 20 simulation steps per second and replicates updates at 10 per second. The browser smooths movement and renders the result; it does not decide damage, XP, health, currency or victory.
A run pins its seed, content version, balance version, mode, heroes, biome and server build. Separate random streams prevent visual effects from changing combat randomness.
Completed results are delivered to the API with idempotent settlement: receiving the same completion again must not award currency again. Balance changes have append-only accounting records.
A living catalogue, stable hunts
The current reference catalogue contains 100 base weapons, 50 evolutions, 18 passives, eight heroes, five biomes, 60 enemy variants and 25 major guardians. Reference tables in this codex read the same loaded catalogue as the collections.
An operator can publish validated content and balance changes for future runs. Existing rooms and stored Daily challenges keep their pinned configuration. Older history can therefore differ from a current collection entry.
This guide describes version 0.2.0 default rules. The selected run’s configuration and the Daily page take precedence where an operator has changed values.
What is implemented, what is still pending
| Area | Current status |
|---|---|
| Playable systems | Gameplay, builds, evolutions, five worlds, timed bosses, co-op, Daily, progression and social screens are implemented. |
| Presentation | Original pixel-art catalogue, animation, environments, music and effects are integrated, alongside the owner’s transparent logo and blue brand palette. |
| Verification | Recorded core, browser, contract, encounter, reconnection and stress checks exist. Enhanced-build fixtures test mechanics, not human balance. |
| Still needs acceptance | Human full-session balance/readability testing, production identity and wallet flow, deployment load tests, and operational staging sign-off. |
| Payments | No accepted live purchase or deployed contract is claimed. Mainnet remains disabled. |
| Hosting | The public alpha is hosted on Vercel with the API, multiplayer server, worker, PostgreSQL and Redis on Railway. Health checks and public connection checks pass; full signed-in gameplay and sustained online load testing still need acceptance. |
For maintainers
The source distribution includes architecture, content, networking, security, testing, deployment and operations runbooks under docs/. The standard local launcher starts the web, API, game and worker services together and refuses occupied ports.
Only the API process owns the embedded local database. Do not start competing API processes against the same database directory. Production uses PostgreSQL; scaling game processes additionally requires deployment routing and Redis validation.
Drain active rooms before routine game-server deployments. Preserve the completed-run outbox on durable storage, and verify backups, restore procedures, monitoring, identity origins and operator access before launch.
Rules describe the 0.2.0 defaults. Catalogue entries follow the loaded collection; active hunts and stored Daily challenges keep their own pinned rules.
Implementation references: docs/ARCHITECTURE.md · docs/NETWORKING.md · docs/STATUS.md · docs/CONTENT_SYSTEM.md