Getting Started¶

Status: Current Last reviewed: 2026-09-08

This page takes you from a clean checkout to a running game, a second client, the level editor, and your first content change.

Install¶

Node 20.19 or a supported newer LTS is expected. From the repo root:

npm install

This installs all three workspaces (shared, server, client).

Run¶

npm run dev

This starts both processes together:

The authoritative game server on ws://localhost:8090 (health check at http://localhost:8090/health).
The Vite client dev server, default http://localhost:5173.

Open the printed Vite URL, create a character with a password, or sign in to an existing account.

To run them separately:

npm run dev:server
npm run dev:client

Type-check everything without running:

npm run typecheck

Run Two Clients¶

Use separate browser profiles, a normal/private window pair, or two browsers. Create two accounts: cookies are shared by ordinary tabs, and a character may have only one active connection. You will see the other player move, fight, and take damage. Movement is predicted locally and reconciled against the server; remote players are interpolated about 140 ms in the past.

For isolated campaign testing (the network check starts and stops its own temporary server):

npm run test:campaign
npm run test:campaign-network
npm run test:starter
npm run test:smoothness

Open the Editor¶

The level editor is at http://localhost:5173/admin. Sign in through the game first, then close that game connection before entering the editor with the same account.

In local development, leave the token field empty and click Open Editor. Connections from localhost are accepted automatically.
In production, the server must be started with an ADMIN_TOKEN environment variable, and you must enter the matching token. Without a token set, admin is refused in production.

Do not expose the editor publicly

The dev auth is deliberately thin. It is a stopgap until real accounts and roles exist. See the Level Editor security notes.

Edit a Map¶

Once the editor is open:

Action	Control
Fly the camera	`W` `A` `S` `D`, `Q` down, `E` up, hold `Shift` for fast
Look around	Hold right mouse button and drag
Place an object	Pick a prefab in the palette, then left-click the ground (hold `Shift` to place several)
Select an object	Left-click it
Move	Drag a selected object across the ground
Rotate	`[` and `]`
Scale	`+` and `-`
Duplicate	`Cmd`/`Ctrl` + `D`
Delete	`Delete` or `Backspace`
Undo	`Cmd`/`Ctrl` + `Z`
Cancel placement or deselect	`Esc`

Grid snapping (0.5 m) and rotation snapping (15°) are on by default and can be toggled in the toolbar. Use the view toggles to show colliders, spawn/aggro radii, safe-zone bounds, and quest-trigger volumes. Every edit is applied live for connected players.

Save a Map¶

Click Save Zone in the toolbar. The server validates the zone, writes it to server/data/zones/starter_valley_001.json, and keeps a timestamped .bak.json copy of the previous version alongside it. Reload From Disk discards unsaved edits and re-reads the file. Export JSON downloads the current zone; Import JSON loads one back in (not saved until you press Save).

Add a Quest¶

Two options:

In the editor, click Quests to open the JSON editor, edit the array, and click Save Quests. This writes server/data/quests/starter_quests.json. Players pick up the new definitions on their next join.
Or edit server/data/quests/starter_quests.json directly and restart the server.

See Adding Quests for the schema and a worked example.

Spawn Mobs¶

For a permanent spawn point, place a Mob Spawn marker from the palette, set its variant and respawnSeconds in the inspector, and save the zone.
For a throwaway test, use the Spawn Wave playtest tool, or the admin spawn_mob command. Dynamic spawns do not respawn.

See Adding Mobs for the full pipeline.

The wiki¶

The wiki follows Todroth's MkDocs Material structure with player guidance, design proposals, implementation and generated game tables.

python3 -m venv .venv-docs
.venv-docs/bin/python -m pip install -r requirements-docs.txt
npm run docs:build
npm run docs:serve

docs:build regenerates current data, checks links and builds site/. The development game serves this built site at /wiki/; docs:serve provides a live documentation preview at http://127.0.0.1:8000. Run docs:build again to refresh the copy shown through the game. The root npm run build also builds the wiki and includes it in client/dist/wiki/. Public hosting remains separate release work.

M1–M3 have standing content approval and are implemented. The roadmap separates them from M4–M8.

Campaign saves¶

The local server stores accounts, session hashes, characters, banks, companies, action receipts and the war in SQLite at ~/Library/Application Support/Vyrgarde/campaign.sqlite. The first launch imports the existing local player JSON once. Register the original character name on this loopback development server to retain that character's progress.

Use VYRGARDE_DATA_DIR for an isolated test database; doing so skips legacy import. VYRGARDE_CONTENT_DIR selects zone/quest sources. VITE_GAME_SERVER selects a development backend; the default client uses port 8090. The war runs with zero players and pauses when the server process stops. Shut down gracefully to checkpoint before copying a backup. Public hosting, account recovery and capacity certification remain later release work.