Welcome to q3py’s documentation!

q3py is a Quake 3 to Python bridge.


This is a work in progress and not meant for public use (yet)!

Quake 3 uses separate modules for its game logic, i.e. client, server and user interface. Those modules can be loaded either in QVM (a .qvm file) or shared native library (a .dll, .so or .dylib file) format.

Now q3py is a shared library which implements the API that Quake 3 expects, but it relays all calls to a Python module. To do so, q3py embedds libpython3 and provides a Python extension module to allow the Python code to call back into Quake 3.

digraph q3py {
	subgraph cluster_exe {
		quake3 -> q3py -> libpython3 -> script;
		script -> libpython3 -> q3py -> quake3;

		quake3 [label="Q3"];
		q3py [label=<q3py<br/><i>qagamex86_64.so</i>>];
		libpython3 [label=<Python<br/><i>libpython3.2.so</i>>];
		script [label=<<i>script.py</i>>];

		label=<Quake 3<br/><i>ioq3ded.x86_64</i>>;


The SVG/PNG generated by Sphinx has a random name and thus can not be linked to from the GitHub README.rst

What q3py allows you to do is write Quake 3 game logic, also known as “mods”, with Python. However, you need to provide all of the logic. To add e.g. homing missiles to the BFG, you would need to implement players, items, pyhsics and weapons in Python as well, you can not extend upon the C code of an existing Quake 3 game module.


All of q3py (the code, its documentation and build scripts) is licensed under the MIT license, see the LICENSE file.

Indices and tables