Trap_* prefix on functions?


Why some functions have this prefix? What’s the purpose of it? Also, is there any text file or link that explains the prefixes in the engine?


trap_ prefix is used for system calls into the engine. For DLLs, it calls a function in g_syscalls.c that calls syscall() which is a pointer to a engine function SV_GameSystemCalls(). However, for QVMs trap functions are listed with a negative value in g_syscalls.asm that match (negated and 1 subtracted) game syscall values and are handled directly by the VM interpreter. Not necessarily important to the terminology but “trap functions” do not run a function that exists in the QVM. Also see Trap (computing) on Wikipedia.

In Quake 2 which used DLLs for the game logic used a structure with function pointers named gi (game import) that were set to engine function addresses. For example, Q2 used gi.trace() instead of trap_Trace() to call SV_Trace() in the engine. The change to using trap functions was likely because QVMs cannot call engine functions directly using the memory address in the engine. This is due to QVMs having a separate address space for portability and security(?) reasons.

Strictly speaking DLLs in Quake 3 have extra overhead of a few unnecessary function calls compared to Quake 2. The trap function calls the syscall handler function that calls the actual engine function. (There is some other functions too if I remember correctly.) It would be more optimal to call the engine function directly like in Quake 2. DLLs still perform better than QVMs which have a slight performance decrease (reportedly 5% decrease in John Carmack’s .plan from 1999). Though I doubt that unnecessary DLL functions calls or QVM performance loss matter on modern computers or maybe even raspberry pi 3. That may be why RTCW and ET used DLLs instead of QVMs though.

Mods as C code compiled to platform independent byte code is such a beautiful thing though.

I don’t know of documentation of the prefixes. They are all simpler than trap_ though.

Ref – Refresh (Renderer)
RE_ – Refresh Export
RB_ – Refresh Backend
CL_ – Client
Snd_ – Sound
SV_ – Server
Com_ – Common. Either shared by server/client or server/client/VMs.
Q_ – Quake replacements for standard library functions and low-level string and number handling
Z_ – Zone memory allocator
G_ – (Server) Game VM
CG_ – Client Game aka CGame VM
BG_ – Shared by both game and cgame VM (actually all three VMs, hello UI)
UI_ – UI VM (used by both BASEQ3 and MISSIONPACK UI VM)

I don’t know what “tr_” prefix used by the renderer is though. I thought it was a reference to the trinity code name for the Q3 renderer (named after Trinity River) but it’s used in Quake 2 as well. So either it’s something else or “trinity” started before switching from Q2 to a separate code base or something.


You are a living Quake Encyclopedia. Thank you! :grinning:


Wow, this proves a bunch of my assumptions about the code. Thanks!