114 lines
4.9 KiB
Markdown
114 lines
4.9 KiB
Markdown
# Aeternalis
|
|
|
|
A playable browser survival RPG foundation: an authoritative Go world server,
|
|
Three.js terrain and GLB models, persistent one-life characters, and weekly worlds.
|
|
|
|
**Status: local prototype, not a production MMO or a verified 2,000-player server.**
|
|
The review, architecture, deployment instructions, and remaining work are in
|
|
`docs/ARCHITECTURE.md`, `docs/DEPLOYMENT.md`, and `docs/ROADMAP.md`.
|
|
|
|
## Run locally
|
|
|
|
Requirements: Node.js 24 and Go 1.26+ (tested with Go 1.27.1).
|
|
On Windows without Go, `powershell -File tools/bootstrap-go.ps1` downloads a
|
|
checksum-verified, project-local toolchain.
|
|
|
|
```sh
|
|
npm ci
|
|
npm run build
|
|
node tools/dev-server.mjs
|
|
```
|
|
|
|
Open **http://127.0.0.1:18080**. Guest authentication is available only in
|
|
development, on an explicit loopback listen address. Production fails closed
|
|
without PostgreSQL and an HTTPS OIDC configuration.
|
|
|
|
The delivered Windows build can also be started without installing Go:
|
|
|
|
```powershell
|
|
powershell -File tools/start-local.ps1 -UseExisting
|
|
```
|
|
|
|
That command starts a hidden background process and prints its PID. Stop your
|
|
specific local process with `Stop-Process -Id <printed-pid>`. Local state lives in
|
|
`.local/aeternalis.db`; restarting preserves characters, world age, and death.
|
|
Deleting this development database is an explicit reset, not part of startup.
|
|
|
|
## Play
|
|
|
|
- Move with WASD/arrows, click the terrain, or use touch direction controls.
|
|
- Click resources/enemies to approach and gather/attack. The toolbar also chooses
|
|
the nearest suitable target. E gathers, Space attacks, I opens inventory.
|
|
- Gather wood, ore, and herbs. Craft a spear or bandages in inventory.
|
|
- The Harbinger appears after seven days. In loopback development, Display
|
|
settings includes **Awaken Harbinger** for testing the event immediately.
|
|
- During the boss event the safe world radius shrinks toward the center. The
|
|
boundary deals damage; complete collapse kills remaining characters, including
|
|
offline and daily-capped characters. Killing the boss freezes survivor eligibility.
|
|
- Survivors sign into a different configured world with the same identity, then
|
|
choose **Continue as ...**. An atomic passage redemption preserves identity,
|
|
inventory, skills, kills, and daily play-time usage.
|
|
|
|
PvP, damage-priority corpse looting, body-part damage, full skills/stats,
|
|
leaderboards, and an admin center are not implemented. Corpse looting currently
|
|
has no priority lock because PvP is not enabled.
|
|
|
|
## Multiple local worlds
|
|
|
|
Start independent worlds against the same SQLite database. Every process needs a
|
|
unique world ID and port. A completed world ID must never be recycled for a new
|
|
season. Seeds and balance are stored when a world is first created.
|
|
|
|
```powershell
|
|
$env:WORLD_DIRECTORY = '[{"id":"world-001","url":"http://127.0.0.1:18080"},{"id":"world-002","url":"http://127.0.0.1:18081"}]'
|
|
powershell -File tools/start-local.ps1 -WorldId world-001 -Port 18080
|
|
powershell -File tools/start-local.ps1 -WorldId world-002 -Port 18081 -Seed 829312
|
|
```
|
|
|
|
Loopback cookies are shared across these two ports, so the same local guest can
|
|
redeem a passage. Production worlds use OIDC issuer + subject for stable identity
|
|
and separate secure host cookies. Never use dev identity for public servers.
|
|
|
|
## Validate
|
|
|
|
```sh
|
|
npm run test:contracts
|
|
npm run check
|
|
npm run build
|
|
# In server/:
|
|
go test ./...
|
|
go vet ./...
|
|
# At the repository root:
|
|
npx playwright install chromium
|
|
npm run test:e2e
|
|
helm lint deploy/chart
|
|
helm template aeternalis deploy/chart
|
|
```
|
|
|
|
When Go is local, use `.tools/go/bin/go.exe` from the root or
|
|
`../.tools/go/bin/go.exe` from `server/`. Go tests use a temporary SQLite database.
|
|
Set `TEST_DATABASE_URL` to an expendable PostgreSQL test database to run the same
|
|
storage suite on PostgreSQL; CI provides one. Linux CI also runs `go test -race`.
|
|
The browser suite starts and stops its own server on port 18089 with a fresh DB.
|
|
On Windows, `PLAYWRIGHT_CHANNEL=msedge` can use installed Edge without downloading
|
|
Chromium. Screenshots and traces are written to `test-results/`.
|
|
|
|
For client hot reload, run the server with `PUBLIC_URL=http://127.0.0.1:5175`,
|
|
then run `npm run dev` and open port 5175. Origin checking intentionally rejects
|
|
requests from other origins.
|
|
|
|
## Layout
|
|
|
|
| Path | Responsibility |
|
|
|---|---|
|
|
| `planning/VISION.md` | Original user vision; new boss rule in `IMPLEMENTATION-NOTES.md` |
|
|
| `server/internal/game` | Terrain, authoritative simulation, lifecycle |
|
|
| `server/internal/store` | World ownership, snapshots, sessions, atomic passages |
|
|
| `server/internal/transport` | HTTP, OIDC, origin checks, WebSocket intent validation |
|
|
| `schemas/protocol.json` | Generated Go/TypeScript wire contracts |
|
|
| `server/content/balance.yaml` | Validated balance and recipe data |
|
|
| `client/` | Full-screen browser game and mobile controls |
|
|
| `tools/create-models.py` | Original temporary Blender models |
|
|
| `deploy/chart/` | Five independent world deployments, services, TLS ingress |
|
|
| `.gitea/workflows/build.yaml` | Tests, Harbor image publication, optional GitOps promotion |
|