jnz/q3vm

Free

Q3VM - Single file (vm.c) bytecode virtual machine/interpreter for C-language input

FreeFree tier

Type

Open Source

Visit Website GitHub (38 stars)

About jnz/q3vm

Q3VM is a lightweight, embeddable bytecode virtual machine and interpreter implemented in a single C file (vm.c) with no external dependencies. Based on the Quake III Arena virtual machine, it executes compiled bytecode files (.qvm) generated from C source code using the included LCC C compiler. The interpreter features static typing, static memory allocation (no garbage collector), and computed gotos for improved performance when compiled with GCC. It is battle-tested through 20 years of use in Quake III Arena and has undergone static code analysis, test coverage, and Valgrind testing. Q3VM is ideal for sandboxing untrusted code, embedding in game engines, IoT applications, and educational projects.

Key Features

Single file implementation (vm.c) with no external dependencies

Includes LCC C compiler to generate .qvm bytecode files

Static type checking and static memory allocation, no garbage collector

Computed gotos for faster interpretation under GCC

Battle-tested through 20 years of use in Quake III Arena

Tool-tested with static analysis, test coverage, and Valgrind

Supports bounded CPU time and memory for embedded and IoT use cases

Provides four callback functions (Com_malloc, Com_free, Com_Error, systemCalls) for easy embedding

Pros & Cons

Pros

Extremely small and lightweight – one .c file to include
No need to learn a new scripting language; uses C as input
Static memory allocation avoids unpredictable garbage collection pauses
Ability to revert to native C code if VM performance is insufficient (Plan B)
Leverages the full C toolchain (debuggers, profilers, static analyzers)
Faster than the similar Triseism Q3VM interpreter
Battle-tested reliability from decades of Quake III Arena usage

Cons

Only supports C as input language; not intended for dynamic or interpreted languages
Requires implementing four callback functions for embedding, which may involve a learning curve
Computed gotos are GCC-specific; performance may be lower on other compilers
No built-in support for modern language features (e.g., exceptions, reflection)

Best For

Sandbox for untrusted or externally downloaded bytecode (e.g., from a web server)Modding and scripting for hobby and indie game enginesEmbedded systems and IoT plugins requiring bounded resources and peripheral restrictionEducational tool for learning about virtual machines with a practical C compilerGames and applications needing a lightweight, C-compatible scripting alternative to Lua

FAQ

What is Q3VM?

Q3VM is a lightweight, embeddable bytecode virtual machine/interpreter that runs compiled C bytecode files (.qvm). It is based on the Quake III Arena virtual machine and includes a complete C compiler (LCC) to produce bytecode. It is designed to be easy to integrate into C projects as a single file (vm.c).

How do I integrate Q3VM into my project?

Drop vm.c and vm.h into your project's source tree, compile them along with your code, and implement the four required callback functions: Com_malloc, Com_free, Com_Error, and systemCalls. Then call VM_Create and VM_Call to run bytecode in your application.

What are the performance characteristics?

Q3VM uses computed gotos for faster interpretation when compiled with GCC. Benchmarks show it is significantly faster than the Triseism Q3VM interpreter. It uses static memory allocation and does not have a garbage collector, making performance predictable.

Can I use Q3VM for sandboxing untrusted code?

Yes. Q3VM can execute bytecode in a sandboxed environment, with bounded CPU time, bounded memory, and restricted access to peripheral devices. This makes it suitable for running code downloaded from a web server or other untrusted sources.