Frequently asked questions

What is SHAG Engine?

SHAG is a Babylon.js engine and arena-FPS stack for Quake 3 and Warsow media. It includes BSP/PK3 loading, Quake shader compatibility, deterministic movement, an authoritative multiplayer server, console tooling, and the active FPS game module.

What license is it under?

The repository uses the MIT License. See the LICENSE file.

Where do maps and PK3s go?

Put external game data under public/data/. The directory and *.pk3 files are ignored by Git. Generate the manifest/index using the repository scripts, then confirm discovery with:

developer 1
pk3 stats
pk3 list
pk3 find maps/wdm2.bsp

Why does a map not load?

Check these in order:

1. the expected PK3 is under public/data/;
2. the generated index is current;
3. pk3 find maps/<name>.bsp resolves;
4. bsp load <name> succeeds in the headless runner;
5. the browser network panel has no missing PK3, texture, WASM, or manifest requests.

Use bsp load for inspection and map <name> [gametype] for normal gameplay.

Why did bsp load not start a match?

bsp load is the loader/inspection path. A browser match uses the gameplay launcher and server:

map wdm2 duel

See Map launching.

How do I open the console?

Press backquote/tilde. Enable developer commands with developer 1.

What is the player key, and what happens if I lose it?

Every player has an account, and the key is what opens it. A browser that reaches the lobby without one is given a new account and a key, kept in that browser's local storage; pasting the key into another browser opens the same account there. The lobby stores only the key's SHA-256, so nobody — including the server operator — can recover a lost key or tell you what it was. The Profile key at the foot of the menu opens it: copy it, save it as a file, or hand it to the browser's password manager. Lose it and the account is gone; make a new one.

See the Lobby server guide.

How do I change rendering settings?

Individual variables apply immediately:

r_wireframe 1
r_wireframe 0
r_bloom 1.2
render list
render reset

render list shows every renderer variable with its range and description. A few, such as material-path switches, apply on the next map load; their descriptions say so.

Does SHAG support raw .map files?

The parser and renderer exist, but MapLoader loads indexed BSP maps only, so a raw .map is not playable. Build playable maps in the SHAGGED editor, which compiles them, or with an external idTech3 toolchain. See Raw .map system.

How should I test a change?

npm run typecheck
npm run test:run
npm run cli:game -- --exec 'bsp load wdm2; bsp info; quit'
npm run test:simulation
npm run test:physics

Renderer or networking edits need the extended regression set in AGENTS.md.

Where do I report a problem?

Search or open an issue in the SHAG GitHub repository. Include the exact command, map, browser/runtime, console output, and a minimal reproduction.