Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:QVM (Quake III)

From ReverseEngineering.wiki
Format
Developer id Software
Versions no version field
Magic 44 14 72 12 (int32 0x12721444, little-endian) at offset 0
Extensions .qvm (symbols in .map)
Endianness little
On this wiki Facts · Code · Notes · Topics

Bytecode image of Quake III Arena's virtual machine (vm/cgame.qvm, vm/qagame.qvm, vm/ui.qvm): a 32-byte header starting with the little-endian magic 0x12721444, then a stack-machine code segment, an initialised data segment and a literal segment.

Compiled game-module image of Software:Quake III Arena: the game logic (qagame), client game (cgame) and user interface (ui) can run as native DLLs or as QVM bytecode from a Format:PK3 (Quake III). Each QVM is produced by the LCC-based q3asm tool chain from C.

Identification

The file starts with the int32 VM_MAGIC 0x12721444 (bytes 44 14 72 12). The engine loads vm/<name>.qvm and, when developer symbols are wanted, the text file vm/<name>.map.

Header

vmHeader_t is eight int32 in this order: vmMagic, instructionCount, codeOffset, codeLength, dataOffset, dataLength, litLength, bssLength (32 bytes). Offsets are from the start of the file. The loader byte-swaps the header, then rejects the file with bad header if the magic differs, if bss, data or lit length is negative or if codeLength is zero or less. At load the data image is dataLength + litLength bytes copied from dataOffset; only the first dataLength bytes are byte-swapped as 32-bit words (the literal part, strings, is not). The memory size is dataLength + litLength + bssLength rounded up to a power of two so that every access can be masked, and the program stack starts at the end of that image.

Instructions

A stack machine. Each instruction is one opcode byte; the opcodes ENTER, LEAVE, CONST, LOCAL, BLOCK_COPY and the comparison branches EQ..GEF (ids 11-26) are followed by a 4-byte little-endian operand, ARG by a 1-byte operand, all others have none. instructionCount counts instructions, codeLength bytes, and the loader needs a first pass over the code to build the jump-target table (instruction number to byte offset), because branch and JUMP targets are instruction numbers.

Opcode ids (enum order of opcode_t): 0 UNDEF, 1 IGNORE, 2 BREAK, 3 ENTER, 4 LEAVE, 5 CALL, 6 PUSH, 7 POP, 8 CONST, 9 LOCAL, 10 JUMP, 11 EQ, 12 NE, 13 LTI, 14 LEI, 15 GTI, 16 GEI, 17 LTU, 18 LEU, 19 GTU, 20 GEU, 21 EQF, 22 NEF, 23 LTF, 24 LEF, 25 GTF, 26 GEF, 27 LOAD1, 28 LOAD2, 29 LOAD4, 30 STORE1, 31 STORE2, 32 STORE4, 33 ARG, 34 BLOCK_COPY, 35 SEX8, 36 SEX16, 37 NEGI, 38 ADD, 39 SUB, 40 DIVI, 41 DIVU, 42 MODI, 43 MODU, 44 MULI, 45 MULU, 46 BAND, 47 BOR, 48 BXOR, 49 BCOM, 50 LSH, 51 RSHI, 52 RSHU, 53 NEGF, 54 ADDF, 55 SUBF, 56 DIVF, 57 MULF, 58 CVIF, 59 CVFI.

Calls into the engine

OP_CALL pops a target; a non-negative target is an instruction number inside the module, a negative target t is a system call with number -1 - t that the interpreter hands to the engine's syscall handler with the arguments on the VM stack. This is how a decompiled QVM reaches the engine API (trap_* functions).

Code & repositories

  • https://github.com/id-Software/Quake-III-Arena @ dbe4ddb10315479fc00086f08e25d968b4b43c49 · license: GPL-2.0-or-later (declared by the contributor for the files used; GitHub reports GPL-2.0 for the repository)
    GPL release of the Quake III Arena source; qcommon/qfiles.h, vm_local.h, vm.c, vm_interpreted.c and files.c document the QVM and PK3 handling.
    Tested on: source read, not run: source read · checked 2026-10-18; last activity 2024-08-02

Pitfalls

  • The format has no section for names; function names exist only in the separate .map file (shipped for none of the retail modules; Unverified: retail QVMs in baseq3/pak0.pk3 have no .map).
  • Community engines add instruction-count and header extensions (Unverified: ioquake3 uses a second magic for a 0x12721445 header with a jump-table length; not read from source here).

Evidence & references

  • id-Software/Quake-III-Arena code/qcommon/qfiles.h (VM_MAGIC, vmHeader_t), code/qcommon/vm_local.h (opcode_t), code/qcommon/vm.c (VM_Create), code/qcommon/vm_interpreted.c (VM_PrepareInterpreter, OP_CALL) at commit dbe4ddb (GPL-2.0).