BlueGit

timfa questward

Files

questward / README.md

README.md

README.md 2.7 KiB Download Raw

Questward

Authoritative Node.js tile MMO with a FrameworkV3 web client. Architecture lives in questward_server_technical_design_v0.6.md. Implementation status lives in docs/FEATURES.md.

Layout

  • shared/ — protocol constants and tile definitions used by server and client
  • server/src/ — Node.js simulation, persistence, editor API, gateway
  • client/src/ — game client on top of FrameworkV3
  • client/assets/ — world sprites. Grounds and blocks live in a folder per type; each PNG is a visual state (first alphabetical is the default). Pivot is 8px from the bottom.
  • client/frameworkv3/ — FrameworkV3 git submodule

Run locally

git submodule update --init --recursive
npm install
npm run build:client
npm test
npm start

Open http://localhost:8080 to play and http://localhost:8080/editor for the world editor.

The world editor keeps an in-memory (and sessionStorage) draft across brief WebSocket drops: the gateway sends protocol pings ~every 25s, and the editor client auto-reconnects with backoff without wiping unsaved paint.

Sign in via auth.timfalken.com (OAuth). Without QUESTWARD_AUTH_CLIENT_SECRET, local dev uses stub admins (admin-1, …). A fresh world is infinite closed grass: open chunk 0,0 in the world editor, save, then Apply now before a character can walk.

Auth env (production)

VariablePurpose
QUESTWARD_AUTH_CLIENT_SECRETOAuth client secret from auth.timfalken.com /admin
QUESTWARD_AUTH_CLIENT_IDRegistered domain (default timfalken.com)
QUESTWARD_AUTH_REDIRECT_URICallback URL (default: {public-origin}/auth/callback)
QUESTWARD_AUTH_URLAuth base URL (default https://auth.timfalken.com)
QUESTWARD_AUTH_STUB=1Force stub auth

Register timfalken.com in auth admin with callback path /auth/callback and allowed port 1234 if using :1234.

Production env file (systemd)

On the game host, put secrets outside git:

sudo mkdir -p /etc/questward
sudo nano /etc/questward/env   # QUESTWARD_AUTH_CLIENT_SECRET=...
sudo chmod 600 /etc/questward/env

The systemd unit loads /etc/questward/env automatically (EnvironmentFile=-/... — missing file is OK). Reinstall or daemon-reload after edits.

cd ~/questward
sudo QUESTWARD_USER=timfa QUESTWARD_REPO="$HOME/questward" ./deploy/install-service.sh

The player-driven Central Exchange marketplace is live (hidden order book, escrow, midpoint matching, pigeon settlement). Place a Central Exchange counter in the editor next to a bank.

Source
1# Questward
2
3Authoritative Node.js tile MMO with a FrameworkV3 web client. Architecture lives in `questward_server_technical_design_v0.6.md`. Implementation status lives in `docs/FEATURES.md`.
4
5## Layout
6
7- `shared/` — protocol constants and tile definitions used by server and client
8- `server/src/` — Node.js simulation, persistence, editor API, gateway
9- `client/src/` — game client on top of FrameworkV3
10- `client/assets/` — world sprites. Grounds and blocks live in a folder per type; each PNG is a visual state (first alphabetical is the default). Pivot is 8px from the bottom.
11- `client/frameworkv3/` — FrameworkV3 git submodule
12
13## Run locally
14
15```text
16git submodule update --init --recursive
17npm install
18npm run build:client
19npm test
20npm start
21```
22
23Open [http://localhost:8080](http://localhost:8080) to play and [http://localhost:8080/editor](http://localhost:8080/editor) for the world editor.
24
25The world editor keeps an in-memory (and `sessionStorage`) draft across brief WebSocket drops: the gateway sends protocol pings ~every 25s, and the editor client auto-reconnects with backoff without wiping unsaved paint.
26
27Sign in via [auth.timfalken.com](https://auth.timfalken.com) (OAuth). Without `QUESTWARD_AUTH_CLIENT_SECRET`, local dev uses stub admins (`admin-1`, …). A fresh world is infinite closed grass: open chunk `0,0` in the [world editor](http://localhost:8080/editor), save, then **Apply now** before a character can walk.
28
29### Auth env (production)
30
31| Variable | Purpose |
32|----------|---------|
33| `QUESTWARD_AUTH_CLIENT_SECRET` | OAuth client secret from auth.timfalken.com `/admin` |
34| `QUESTWARD_AUTH_CLIENT_ID` | Registered domain (default `timfalken.com`) |
35| `QUESTWARD_AUTH_REDIRECT_URI` | Callback URL (default: `{public-origin}/auth/callback`) |
36| `QUESTWARD_AUTH_URL` | Auth base URL (default `https://auth.timfalken.com`) |
37| `QUESTWARD_AUTH_STUB=1` | Force stub auth |
38
39Register `timfalken.com` in auth admin with callback path `/auth/callback` and allowed port `1234` if using `:1234`.
40
41### Production env file (systemd)
42
43On the game host, put secrets outside git:
44
45```bash
46sudo mkdir -p /etc/questward
47sudo nano /etc/questward/env # QUESTWARD_AUTH_CLIENT_SECRET=...
48sudo chmod 600 /etc/questward/env
49```
50
51The systemd unit loads `/etc/questward/env` automatically (`EnvironmentFile=-/...` — missing file is OK). Reinstall or `daemon-reload` after edits.
52
53```bash
54cd ~/questward
55sudo QUESTWARD_USER=timfa QUESTWARD_REPO="$HOME/questward" ./deploy/install-service.sh
56```
57
58The player-driven **Central Exchange** marketplace is live (hidden order book, escrow, midpoint matching, pigeon settlement). Place a Central Exchange counter in the editor next to a bank.