Ioquake3: Where do I get started? (dev)

Suggestions based on my experience with creating a standalone game.

Code

First figure out how to compile ioquake3. In the code directory game, cgame, and q3_ui contain the (C 1989 standard) game logic which are compiled to cross-platform QVM (Quake Virtual Machine) bytecode and DLLs for debugging. This is likely what you would be interested in changing for creating a new game. There are some tutorials (Code 3 Arena) that give you an idea of how the game logic works. Looking at what other standalone games have done can be helpful too.

I would suggest forking the ioq3 repo and editing the Makefile to change BASEGAME=baseq3 to BASEGAME=yourmod and set BUILD_STANDALONE=1 (and additional settings like the client/server executable name). Compile ioquake3 (make) and run with your data files using (bat script containing) build\release-mingw32-x86_64\ioquake3.x86_64.exe +set sv_pure 0 +set fs_steampath "C:\Users\Sarge\dev" (sv_pure 0 allows unzipped files and where C:\Users\Sarge\dev\ contains yourmod directory with the data files). (fs_steampath -originally fs_cdpath- is used so that fs_basepath is still the engine directory and QVMs/DLLs will be loaded.) With this setup you can repeatedly run make and a bat script to run the game.

If you crash the game or want to check for issues hidden by QVMs (e.g., not crashing when NULL pointer is dereferenced), make a debug build (make debug) and run ioquake3 using a debugger such as gdb and use DLLs +set sv_pure 0 +set vm_game 0 +set vm_cgame 0 +set vm_ui 0. +set vm_game 2 etc will change back to using QVMs.

Data

For bootstraping your own data I would suggest downloading the Quake 3 demo data so you can tell the layout and what files you need to create for a standalone game (important ones being default.cfg (errors without it), gfx/2d/bigchars.tga which is the console / in-game font, and models/players/sarge/* the default player model). You can unzipped demoq3 pak0.pk3 into youmod\aa-q3demo.pk3dir\ to keep the files separate from other own and still easy to access and remove unneeded or replaced files. You could also get (GPLv2 licensed) fonts and botfiles (for bot AI) from OpenArena if you want to have a complete data set to release sooner rather than later.

You can reload models, textures, and shaders by running vid_restart command in the console. This also allows reloading the cgame and q3_ui code. game code is reloaded by map command.

Release

For making a release you would zip the data files and build\release-mingw32-x86_64\yourmod\vm\*.qvm (with vm\*.qvm in the zip) and change the .zip extension to .pk3. (Quake 3 uses uncompressed ‘store’ zip file so it’s just a file index but standard ‘deflate’ compression is also supported.)

Tools / resources

Map editor: https://gitlab.com/xonotic/netradiant
Shader manual: http://q3map2.everyonelookbusy.net/shader_manual/
Obj to md3 / md3 viewer: https://clover.moe/mm3d/

3 Likes