Firebird Quake

Quake, simulated and rendered inside the Firebird SQL database, running entirely in your browser on Firebird 6 compiled to WebAssembly. A port of the idea behind Firebird DOOM to a true 3D engine.

Play it: https://mariuz.github.io/firebird-quake/

The series went on: Firebird Quake 2 (play) and Firebird Quake III Arena (play), with Bézier patches, MD3 player models and deathmatch bots that think in SQL.

More pictures, of every level of the first two episodes, the start of the third and the registered monsters, with the commands that made them, are in docs/screenshots.md. The long account of how it is built is docs/ARCHITECTURE.md; what is still missing is docs/ROADMAP.md.

Every game tic is a PSQL procedure call. Every frame is a SELECT. JavaScript handles the keyboard, the mouse and the canvas; everything else — collision against the BSP hulls, the player's physics, doors, platforms, triggers, items, weapons, damage, the monster AI, and the visibility and projection of every polygon on screen — happens in SQL.

keyboard/mouse → SELECT * FROM quake_tic(...)      game logic: 20 Hz, PSQL
               → SELECT * FROM frame_faces_fast    the faces on screen this frame (SQL picks, JS projects)
               → SELECT * FROM frame_ents          alias models and sprites in the PVS, with their pose
               → SELECT * FROM frame_lightstyles   this frame's light animation
               → SELECT ... FROM sound_events      what to play, and where
               → JS rasterises polygons and models through the colormap → canvas

Running it

npm install
npm run fetch-pak      # downloads the Quake shareware episode (quake106.zip) and extracts id1/pak0.pak
npm run serve          # http://localhost:8080/ — add --coi if your browser blocks service workers

fetch-pak needs a tool that can read the LHA archive inside the shareware zip: 7-Zip, lha or lhasa (sudo apt-get install lhasa on Debian/Ubuntu). If you own Quake, copy your pak0.pak with PAK=/path/to/pak0.pak npm run fetch-pak and put pak1.pak beside it in public/pak/, or pick the two files together in the page's file picker. With pak1.pak loaded the page offers the other three episodes and the registered monsters (enforcer, hell knight, vore, spawn, rotfish, Shub-Niggurath), and the screenshot tool can draw them.

LibreQuake

LibreQuake is free game data for the Quake engine (BSD-3-licensed models, textures, sounds and maps that keep Quake's file layout). The page and the tools take it as an alternative to the shareware episode, and its pak1.pak as a free stand-in for the registered one:

npm run fetch-librequake   # downloads LibreQuake lite (v0.09-beta, 56 MB) into public/pak/lq1/pak0.pak and pak1.pak

The page's Data selector then offers LibreQuake (its own levels, lq_e0m1 onwards, with its monsters and weapons) and Quake shareware + LibreQuake monsters: the shareware episode with LibreQuake's pak1.pak beside it, which gives the enforcer, hell knight, vore, spawn, rotfish and Shub-Niggurath models and sounds without the registered data. The deployed site serves both.

LibreQuake's models carry no frame names, only numbers, while the game picks animations by name (run, pain, death…). They keep Quake's frame order, since progs.dat addresses frames by number, so the loader applies the id models' frame layouts (src/framelayouts.js, generated by npm run gen-frame-layouts from a pak with named frames) to any model whose frames are unnamed. LibreQuake's own progs.dat runs too, in QuakeC mode (the Logic setting): FTEQCC overlaps the locals of its functions, which the VM saves and restores around their calls as Quake's does.

Mods

The QuakeC VM runs a mod's own progs.dat. The page's Mod control lays one over the game data as Quake lays a game directory over id1: a mod's zip as released (with its loose files, its pak files, or both) or its pak files, picked from your disk, or FrikBot X, which the site serves. A mod with its own progs.dat runs in QuakeC mode, and the Impulse box beside the control sends any impulse, as a key bound to it would. With FrikBot X, start a deathmatch or coop game and send impulse 100 to add one of its bots beside ours (101 adds one on the other team, 102 removes one).

npm run fetch-mods   # FrikBot X into public/pak/mods/ (the site serves it); two more mods into mods/ for the test
npm run test:mod     # the three mods' progs.dat files in QuakeC mode, FrikBot X's bots in a deathmatch

The page runs Firebird WASM's build without threads, which needs no SharedArrayBuffer, so no cross-origin isolation and no reload on the first visit. FB_THREADS=1 npm run build ships the threaded build instead, which does: the dev server sends the COOP/COEP headers with --coi, and on a static host like GitHub Pages coi-serviceworker.js re-issues responses with them after a one-time reload. The build runs the schema once and ships the database as an image (schema-<hash>.fdb.gz, 0.7 MB) that the page opens instead of compiling the PSQL, and the page keeps the paks in the browser's cache after the first visit, so a revisit is playing in about three seconds. Node 20 or later is required for the scripts.

Playing

Click the view to capture the mouse.

keys
W A S D or the arrows	move (always running; Shift walks)
mouse, PgUp/PgDn	look
Ctrl, F or click	fire
Space or E	jump, or swim up
1–8, / or the wheel	choose a weapon, cycle weapons
9	all weapons and ammo (impulse 9)
P	pause
F6, F9	quick save, quick load
`	Quake's console: map e1m3, god, noclip, give s 100, kill, color 4 13, bind k +jump, alias, exec default.cfg, sql SELECT …, help for the rest; what it prints shows over the view for three seconds
Game setting	single player, or deathmatch or coop (QuakeC mode, progs.dat's rules) against 1 to 7 bots played by PSQL, which learn the level from where you and they go (FrikBot's waypoints) and run its ways to the pickups; the menu's Multiplayer starts a deathmatch
Demo buttons	record from this moment (as Quake's record: a demo begun mid-level carries a save of where it starts), play it back, save or open a .dem.json file
Save buttons	download the last game saved or loaded as a .sav.json file, or load one (saves otherwise live in the browser)
Esc	Quake's menu: new game, load and save (twelve slots), options (customize controls, mouse speed, always run, volumes, screen size…), help

Every key is a binding, as in Quake: the menu's Customize controls or the console's bind changes them, and the page keeps them.

On a phone or a tablet the controls appear with the first touch: a stick where the left thumb lands (as far as it is pushed, as fast), the right side of the view to look by dragging (a quick tap fires), buttons to fire, jump, change weapon, bring up the menu and go full screen, and arrows, OK and back to drive the menu.

The page's settings: the map (every .bsp in the pak), the skill, the detail (640×400, 320×200 or 160×100), the liquids (opaque as in Quake, or translucent where the map was vised for it, as LibreQuake's are, at the alphas the map asks for, or the console's r_wateralpha, r_lavaalpha…), the renderer mode (below), the sound volume and the music. Quake's music was CD audio and is not in the pak: put track02.ogg…track11.ogg (or .mp3) in public/music/, or pick that folder in the page, and each map plays its worldspawn track; without them a synthesised drone fills in, or turn it off.

The SQL console

The page has a console onto the live game database. Everything is a table, so everything can be read or changed while playing:

SELECT * FROM player;
SELECT id, mtype, st, health, enemy_id FROM ents WHERE mtype IS NOT NULL ORDER BY st;
SELECT classname, COUNT(*) FROM ents GROUP BY classname ORDER BY 2 DESC;
SELECT FIRST 40 * FROM frame_faces_fast;          -- what the painter is about to draw
EXECUTE PROCEDURE player_impulse(9);              -- all weapons
SELECT * FROM spawn_monster('shambler', 300);     -- one, 300 units ahead
UPDATE ents SET health = 1 WHERE mtype IS NOT NULL AND health > 0;
UPDATE ents SET flags = BIN_OR(flags, 64) WHERE classname = 'player';   -- god mode

Ctrl+Enter runs; ↑ and ↓ walk the statements run before (kept across reloads); Tab completes a table, column, procedure or function name, or a keyword, and cycles the matches. window.quake exposes the database, the renderer, the audio and the settings to the browser's own console as well.

What it does not try to be

So that the list of ideas stays about this project:

• Multiplayer between people. Deathmatch and coop are against bots that PSQL plays, in one tab; there is no network code and no server to join. A second person would need a second Firebird.
• GLQuake. The picture is WinQuake's software renderer, drawn from query results: 8-bit palette, lightmaps and the colormap, no OpenGL, no coloured light, no filtering, no high-resolution textures. See-through water is there only because the maps vised for it allow it.
• A drop-in Quake engine. Demos and saves are this project's own JSON (.dem.json, .sav.json), not Quake's .dem and .sav; there is no QuakeWorld physics or client prediction.
• Fast. A tic is several milliseconds of SQL where Quake spends microseconds; the point is that it runs at 20 tics a second at all, and the numbers are kept (npm run perf).

How it works

The BSP becomes tables (sql/schema.sql, src/loader.js)

A BSP file is a relational database in disguise. loader.js parses it (src/bsp.js) and copies it in, denormalised so the hot loops never need a second lookup:

table	from
faces	FACES + PLANES (flipped for side) + TEXINFO, plus a bounding sphere
face_verts	EDGES and SURFEDGES resolved to an ordered vertex list per face
leaves	LEAVES with the PVS decompressed to a hex string (leaf j visible ⇔ bit j−1)
marksurfaces, hulls	MARKSURFACES; NODES (hull 0) and CLIPNODES (hulls 1 and 2), planes copied in
models, anims	the world, its submodels (*N), the b_*.bsp boxes, every .mdl with its frame runs
map_ents	the entity lump, which SPAWN_MAP_ENTS turns into rows of ents

ents is the edict table: one wide row per entity with its origin, velocity, angles, bounding box, model, frame, health, flags, think time, movement state and targets — the fields of entvars_t.

The WASM build binds parameters as text, so each table has a generated LOAD_<table> procedure that parses 30 KB chunks of fixed-width fields in PSQL (no separators to search for). E1M1 (70 k rows) loads in about 1.2 seconds.

Collision is a recursive procedure (sql/physics.sql)

RHC is SV_RecursiveHullCheck: it splits the segment at every plane it crosses and recurses into both sides, threading the trace state (allsolid, startsolid, inopen, inwater, the fraction and the hit plane) through its parameters, because PSQL procedures can call themselves. TRACE_MOVE picks the hull by the moving box's size, runs it against the world and against every brush-model entity at its own origin, and clips against monsters and the player with a Minkowski slab test. FLY_MOVE, WALK_MOVE (with the 18-unit step), MOVE_STEP (monsters), TOSS_MOVE and PUSH_MOVE (doors crushing and carrying) are sv_phys.c; the clip planes and the pushed entities live in global temporary tables because PSQL has no arrays. A primary-key lookup costs about 4 µs in the WASM engine, so a trace is well under a millisecond.

The game is PSQL (sql/game.sql and the files after it, sql/weapons.sql, sql/monsters.sql)

QUAKE_TIC runs the player (client.qc: water, jumping, the water jump, friction, acceleration, the trigger and item touches, powerups, drowning), the pushers (with SUB_CalcMove semantics), the thinks that are due, and the physics of everything that flies, bounces or falls. Doors link by touching boxes and need keys; platforms, buttons, trains with path corners and secret doors move as in doors.qc and plats.qc. Items and weapons from the axe to the thunderbolt, armour, damage momentum, gibs and backpacks are items.qc, weapons.qc and combat.qc. The monsters run ai.qc's state machine — FIND_TARGET, MOVE_TO_GOAL, NEW_CHASE_DIR, CHECK_ATTACK — with each monster's attacks and sounds defined in monster_types (its branches on a monster's name are the zombie's pain, the spawn's explosion and the two bosses): the grunt, dog, knight, ogre, scrag, fiend, zombie, shambler and Chthon of the shareware episode, and the enforcer, hell knight, vore, spawn, rotfish and Shub-Niggurath of the registered one. Per-map gravity (Ziggurat Vertigo), the level's worldspawn message and type, the intermission and the finale live in game. Everything the simulation wants heard is a row in sound_events; visual effects are rows in fx_events.

A QuakeC VM (sql/qcvm.sql)

The game above is a rewrite of progs.dat in PSQL, so mods do not run. The start of the faithful route is a QuakeC virtual machine in PSQL: src/progs.js loads progs.dat (statements, functions, global and field definitions, strings, the global image) into tables, and QC_CALL is PR_ExecuteProgram with one branch per opcode, the locals saved on a stack table, parameters copied into the callee's locals, recursion for calls, entity fields as rows addressed by OP_ADDRESS, and forty of the builtins (makevectors, setorigin, spawn, find, traceline against the loaded world, ftos, lightstyle, the prints into qc_log...). It runs the shareware progs.dat: qc_spawn_map spawns E1M1 through its 336 spawn functions in a second, and qc_frame runs StartFrame and the due thinks, so items place themselves, monsters stand and doors link; qc_client_connect and qc_player_frame run the player's own code, so the shotgun fires through FireBullets and a box of shells is picked up through ammo_touch.

QuakeC mode (qc_enter) puts the original game on the engine: every edict's engine fields (origin, velocity, angles, box, solid, movetype, flags, frame, model…) live in its ents row, the VM's field access is routed there, and qc_server_frame is Host_ServerFrame: the client's friction and acceleration, StartFrame, then each edict's physics by movetype (pushers on their own clock, toss and missiles, falling monsters, the player's walk with its step), the touches delivered to QuakeC through the same traces and pushers the PSQL game uses. A frame of E1M1 takes about 40 ms.

node scripts/screenshot.mjs e1m1 out --qc --at=1150,1030,-250,330 --tics=4 --single --fast renders a QuakeC-mode frame. In the page, the Logic setting switches between the PSQL game and QuakeC VM (progs.dat): the level is spawned by progs.dat, every tic is qc_tic, which takes quake_tic's input and returns its row from the QuakeC player's fields (centre prints, messages, the pickup flash, damage, the intermission's stats screen, the episode's finale text and changelevel included), and a level change carries the player's parms (SetChangeParms, DecodeLevelParms) as Quake does. The monsters see the player through checkclient (the PVS from eye to eye), walk and chase through walkmove and movetogoal (the engine's SV_movestep family), and the gunshots, blood, explosions and lightning they and the player make arrive as effects from the progs' temp-entity messages. The interpreter runs a statement in about 13.5 µs (one joined query and one UPDATE); on top of it, QuakeC is compiled to PSQL (src/qcjit.js): the functions a level calls most become stored procedures of their own, with the temporaries, locals and parameters in PSQL variables, constants as literals and jumps as nested labelled loops, a few between frames while the game runs. The compiled code runs about six times faster than the interpreter, and a server frame of E1M1 takes 15 to 22 ms with the monsters asleep and 21 to 26 ms with grunts awake (25 to 44 interpreted: npm run bench:qc, QCJIT=all to compile everything first), against 5 to 10 ms for the PSQL game's tic; what is left is mostly the engine's own work (the traces of the monsters' steps, the client's physics).

The renderer is a query (sql/render.sql)

FRAME_FACES finds the leaf the eye is in and, once per leaf, marks every face of every leaf in its PVS into vis_faces (Quake's visframe). Visible brush models are marked too, at their origin. One cursor then joins the marked faces to their vertices, dropping back faces and faces whose bounding sphere is outside the frustum in the WHERE clause and computing the view transform, the projection and the texel coordinates in the select list — evaluated by the engine rather than as PSQL statements, which cost several times more. Edges that cross the near plane are clipped by the painter in view space; the (face, seq) primary key yields each polygon's vertices in order, so no sort is needed. FRAME_ENTS lists the alias models and sprites whose leaves are in the PVS.

Two renderer modes are selectable in the page. SQL picks faces, JS projects (the default, FRAME_FACES_FAST): SQL does the visibility work — PVS marking, back faces, frustum — and emits one row per visible face; the painter transforms the vertices it already holds from the BSP. SQL projects every vertex (FRAME_FACES): the view transform and projection happen in the select list too, one row per polygon vertex. Both paint the same pixels (the headless screenshot tool checks with --compare); the first costs about a quarter of the second, since a frame is ~400 face rows instead of ~2000 vertex rows.

JavaScript only paints (src/renderer.js)

An 8-bit framebuffer of palette indices and a z-buffer, like Quake's. Polygons are scan-converted with perspective-correct spans (1/z, s/z, t/z) over a surface cache: the miptex tiled under the face's lightmap, run through the colormap — r_surf.c. Alias models are drawn with the lightmap value under the entity and Gouraud light from the vertex normals, clipped against the near plane triangle by triangle; sprites are billboards; the sky is Quake's two scrolling layers mapped by the pixel's direction; explosions and blood are particles. The status bar comes from gfx.wad.

Sound (src/audio.js)

sound_events rows are played with the Web Audio API, attenuated and panned from where they happened. Entity ambients (drips, hums, torches) loop at their entities; the water and wind ambients come from the BSP leaf the player is in, which QUAKE_TIC reports each frame. The music is the CD track named by the map's worldspawn, from the files described above.

Tests

Each test boots the real Firebird WASM engine under Node, loads a level from the pak, and plays a scene through QUAKE_TIC, asserting on the tables afterwards. They are the regression suite for the physics, the movers and the AI, and they run in CI before every deploy.

command	what it plays
npm test	SQL smoke test: every procedure compiles, E1M1 loads, tics and frames run, every sound the game queued exists in the pak; the PSQL player's movement as Quake's (wall friction, SV_CheckStuck, the swim's step, the jump after the input, SV_AirMove's input), T_Damage in god mode, a thrown thing's 2000 cap (PAK=… PAK1=… node scripts/sql-smoke.mjs start runs it over LibreQuake, as CI does)
npm run test:boss	E1M7: the rune wakes Chthon, he rises and throws lava, the lightning does nothing until both terminals are up, three bolts kill him, the exit opens
npm run test:skill	the skills: each of the start map's halls sets its skill, nightmare's monsters attack without waiting and flinch at most every five seconds (two hits make a knight flinch twice on normal, once on nightmare), and QuakeC's localcmd("skill 3") sets it in QuakeC mode
npm run test:save	save games: E1M1 saved mid-play and loaded back exactly (every entity, the client, the totals, the light styles); exported as the page keeps it and as a downloaded file (another data set's file refused), loaded onto E1M1 loaded again with other brush model ids; the same in QuakeC mode with progs.dat's globals, fields and run-time strings; no saving dead or in the intermission
npm run test:water	see-through liquids (the Liquids setting): over lq_e0m2's water the floor shows through at alpha 0.5; over E1M1's slime, which id's vis tools did not see through, nothing changes; lq_e0m4's lava stays opaque as its own lavaalpha 1 asks; the alphas per kind (the map's keys, then r_lavaalpha, r_slimealpha, r_telealpha, else the water's); from under E1M1's water the surface's underside is in the frame
npm run test:bsp2	the BSP2 and 2PSB formats of larger modern maps: E1M1 rewritten in both loads to the same rows, plays the same 150 tics and draws the same faces as the original
npm run test:fire	the shambler's lightning on sham_magic6, 9 and 10 (and 11 on nightmare) with magic7 and 8 skipped, and the lava fireballs' throw, with misc.qc's speed bug for spawners without a speed key
npm run test:hazard	slime and lava as Quake's WaterMove hurts: slime 4 × waterlevel a second and nothing in the biosuit, lava 10 × waterlevel every 0.2 s and once a second in the suit, the PSQL game and QuakeC mode alike

Tools for the same purpose:

npm run check          # compile every sql/*.sql against the engine, nothing else
npm run bench          # where a tic and a frame spend their time
npm run perf           # every benchmark against the deployed history (perf-history.json), as CI runs it
npm run screenshots    # headless frames to docs/ (node scripts/screenshot.mjs e1m1 --at=x,y,z,yaw [--fast] [--compare])

Posed and staged shots of every level, with their commands, are in docs/screenshots.md.

Layout

sql/schema.sql     tables: the BSP, the models, the edicts, the player, the game, the events
sql/physics.sql    traces against the hulls, linking, water, the movement procedures
sql/game.sql       progs.dat's utilities and entity helpers, and the stubs the next five call
sql/movers.sql     doors, plats, buttons, trains, secret doors
sql/triggers.sql   SUB_UseTargets and the triggers, changelevel, teleporters
sql/items.sql      the pickups
sql/combat.sql     damage, the projectiles, impacts
sql/spawn.sql      the entity lump: every classname's spawn function
sql/weapons.sql    the player's tic: movement, firing, impulses
sql/monsters.sql   the AI, the pushers, the think and physics loops, QUAKE_TIC, INIT_MAP
sql/render.sql     visibility and projection
sql/qcvm.sql       the QuakeC VM: progs.dat as tables, globals, fields, strings, edicts
sql/qcbuiltins.sql the builtins, in five procedures by kind
sql/qcexec.sql     the interpreter
sql/qcserver.sql   spawning a map, the client
sql/qcphysics.sql  the server frame and its physics
sql/qcpage.sql     the page's QuakeC mode: qc_begin_map, qc_tic
src/qcjit.js       QuakeC compiled to PSQL: a stored procedure per hot function, the dispatchers
src/loader.js      BSP and MDL to tables, the generated bulk loaders
src/main.js        the page: input, the game loop, settings, the console
src/renderer.js    the painter
src/audio.js       sound events, ambients, music
scripts/           the tests, the benchmark, the screenshot tool, the pak fetcher, the build

Firebird lessons

• Derived tables are inlined and IN (subquery) can scan the whole table: JOIN the marked set instead, and the join to the vertices becomes an index walk.
• Expressions in the select list are cheap; PSQL statements are not. Moving the per-vertex arithmetic out of the loop body and into the cursor's select list cut the frame query by half.
• A join per candidate row costs more than copying its columns. leaf_faces carries each face's plane and sphere, so the frame query culls without probing faces by key for every candidate, and it halved.
• Rows are the cost. Emitting ~2000 vertex rows costs ~35 ms; emitting the ~400 face rows they belong to costs ~8 ms. Filter before you join: a predicate on the joined row still walks every vertex.
• Keep what does not change. The PVS marking is kept until the eye enters another leaf; items at rest are not relinked.
• Bind as text. The WASM build cannot bind binary parameters, so bulk data goes in as text and is parsed by generated PSQL loaders, which beat EXECUTE BLOCKs of INSERTs.
• Recursion works, and deep enough for a BSP hull: RHC calls itself for each side of each plane.
• CASE and IIF over string literals pad the result to the longest branch, so a sound name picked that way wants a TRIM before it reaches the pak.
• Floating-point time drifts. Thinks scheduled at time + 0.1 are compared with a small tolerance, or a monster thinks at 8 Hz instead of 10.
• Smaller things: a VARCHAR longer than 8191 needs CHARACTER SET ASCII; INSERT ... VALUES takes one row; a procedure that calls one declared later needs a stub with the same signature first; at is a reserved word.

Licence

MIT for the code here. Firebird and Electric Firebird are Apache-2.0. The Quake shareware episode is freely redistributable; Quake is a trademark of id Software. LibreQuake's data is BSD-3-Clause (its progs.dat and pop.lmp are GPL-2 and are not used here).