Skip to content

Installation

Jump to bottom
Kevin Masterson edited this page Apr 15, 2025 · 21 revisions

Installation

Getting Started

The basic concept to operation is for QMM to be loaded as if it were the mod dll, and then it loads the original mod dll file.

Each game uses a different filename for the mod. Refer to this list when you are asked to rename the QMM DLL in step 2:

Game Windows DLL Linux SO QVM
Quake 3 Arena qagamex86.dll qagamei386.so qagamex86_64.dll
Return to Castle Wolfenstein (Multiplayer) qagame_mp_x86.dll qagame.mp.i386.so
Wolfenstein: Enemy Territory qagame_mp_x86.dll qagame.mp.i386.so
Return to Castle Wolfenstein (Singleplayer) qagamex86.dll qagamei386.so
Jedi Knight 2: Jedi Outcast jk2mpgamex86.dll jk2mpgamei386.so vm/jk2mpgame.qvm
Jedi Knight: Jedi Academy jampgamex86.dll jampgamei386.so
Star Trek Voyager: Elite Force (Holomatch) qagamex86.dll qagamei386.so vm/qagame.qvm
Star Trek: Elite Force II gamex86.dll gamei386.so
Medal of Honor: Allied Assault gamex86.dll gamei386.so
Medal of Honor: Spearhead gamex86.dll gamei386.so
Medal of Honor: Breakthrough gamex86.dll gamei386.so
Soldier of Fortune II: Double Helix (MP) sof2mp_gamex86.dll sof2mp_gamei386.so vm/sof2mp_game.qvm
Quake 2 Remastered game_x64.dll
Quake 2 gamex86.dll gamei386.dll

Installation Steps:

  1. Locate the mod file (listed above) in the mod directory and rename it to qmm_<name>. Skip this step for QVM mods.
  2. Place qmm2.dll/qmm2.so into the mod directory and rename it to the old mod file name (listed above)
  3. Place qmm2.json into the mod directory
  4. Configure qmm2.json (see Configuration section for details)

Note for Jedi Academy (standard mod) on Windows: You will have to run a server without QMM first to extract the original jampgamex86.dll file from the .pk3 files, so that you can rename it to qmm_jampgamex86.dll in step 1. JA stores the .dll file inside .pk3s, but it must be outside a .pk3 in order for Windows to load it, so JA will read it from the .pk3 and write it to disk.

Also, for step 2, place the zzz_qmm_jamp.pk3 file in the mod directory instead of the qmm2.dll. This is necessary because Quake 3-based games will load files from .pk3 files BEFORE real files, and the .pk3s are loaded in alphabetical order. This means that the zzz_qmm_jamp.pk3 file will be loaded last, ensuring it contains the jampgamex86.dll file that gets loaded by the server.

Configuration

The configuration for QMM primarily comes from the qmm2.json file. This should be placed in the mod directory, the same place the qmm DLL is located. Other than the plugins list, most settings generally aren't needed and QMM will load with default settings in all tested game engines.

The QMM config contains several options:

  • game - valid options:

    • auto (default) = attempt to automatically determine engine
    • Q3A = Quake 3 Arena
    • RTCWSP = Return to Castle Wolfenstein (Singleplayer)
    • RTCWMP = Return to Castle Wolfenstein (Multiplayer)
    • WET = Wolfenstein: Enemy Territory
    • JK2MP = Jedi Knight II: Jedi Outcast
    • JAMP = Jedi Knight: Jedi Academy
    • STVOYHM = Star Trek Voyager: Elite Force (Holomatch)
    • STEF2 = Star Trek: Elite Force II
    • MOHAA = Medal of Honor: Allied Assault
    • MOHSH = Medal of Honor: Spearhead
    • MOHBT = Medal of Honor: Breakthrough
    • Q2R = Quake 2 Remastered
    • QUAKE2 = Quake 2 Remastered
    • SOF2MP = Soldier of Fortune II: Double Helix (Multiplayer)

  • mod - path to mod file. specify "auto" to attempt to automatically determine mod filename based on the game engine. default = "auto"

  • execcfg - name of Quake config file to execute after QMM and plugins are loaded. specify an empty string to explicitly disable this function. default = "qmmexec.cfg"

  • plugins - list of plugin filenames to load

  • logseverity - severity of logging. valid options:

    • TRACE - all calls into QMM (including GetGameAPI hooks, excluding G_PRINT)
    • DEBUG - all calls into QMM except mod funcs that happen every frame (GAME_RUN_FRAME, etc)
    • INFO - information during config/mod/plugin loading and engine detection steps
    • NOTICE - information regarding final status of config/mod/plugin loading and engine detection
    • WARNING - NoCrash code detected msgboom behavior, plugin fails to set a result flag
    • ERROR - error while loading mod, plugin sets QMM_ERROR result flag
    • FATAL - unable to detect engine or load mod, error during QVM execution
    • [blank] - use default. the default for the release build is INFO and the default for the debug build is DEBUG

  • qvmstacksize - size (in MiB) of the QVM stack for QVM mods. default = 1

Notes

File Locations

Quake 3 engine games will generally attempt to load game files from 2 locations:

  • home directory: from <home>/.q3a/ (i.e. C:\Users\user\.q3a\ or /home/user/.q3a/)
  • game directory: where the game/server .exe file is (i.e. C:\Program Files\Quake 3 Arena\ or /opt/q3server/)

QMM will attempt to load files from various paths in order to best work with these multiple locations.

In the following lists, you will see these placeholders used:

  • <qmmdir> - the directory where the QMM DLL is located
  • <exedir> - the directory where the game executable is located
  • <moddir> - the mod the game is running (i.e. "baseq3", "main", etc)
  • <mod> - the "mod" setting in the config file
  • <qvmname> - the default name of a QVM mod for the game engine
  • <dllname> - the default name of a DLL mod for the game engine
  • <plugin> - a plugin file string given in the "plugins" list in the config file

Config file

The config file will be loaded from the following locations in order:

  1. <qmmdir>/qmm2.json
  2. <exedir>/<moddir>/qmm2.json
  3. ./<moddir>/qmm2.json

Mod file

The mod file can be specified in the config either as an absolute or relative path, or as "auto" (the default).

If an absolute path is given, only that path is loaded.

If a relative path is given, the mod file will be loaded from the following locations in order:

  1. <mod>
  2. <qmmdir>/<mod>
  3. <exedir>/<moddir>/<mod>
  4. ./<moddir>/<mod>

If "auto" is used, the mod file will loaded from the following locations in order:

  1. <qvmname> (if the game engine supports QVM mods)
  2. <qmmdir>/qmm_<dllname>
  3. <exedir>/<moddir>/qmm_<dllname>
  4. <exedir>/<moddir>/<dllname>
  5. ./<moddir>/qmm_<dllname>

If QMM is unable to load a mod after checking all the above locations, it will exit with an error.

QMM will not attempt to load a mod file if it thinks it is QMM itself.

Plugins

A plugin file can be specified in the config either as an absolute or relative path.

If an absolute path is given, only that path is loaded.

If a relative path is given, the plugin file will be loaded from the following locations in order:

  1. <qmmdir>/<plugin>
  2. <exedir>/<moddir>/<plugin>
  3. ./<moddir>/<plugin>

Quake 3 and Jedi Knight 2

In the event your mod uses a QVM (Quake Virtual Machine) file (the default mods do), you must set the vm_game cvar to 0 in order for the QMM dll to be loaded. You can do this by adding the following to <mod>/autoexec.cfg (create it if it does not exist):

seta vm_game 0

Listen Servers

You can get rid of the DLL "Security Warning" message by setting the com_blindlyLoadDLLs cvar to 1. You can do this by adding the following to <mod>/autoexec.cfg (create it if it does not exist):

seta com_blindlyLoadDLLs 1

Clone this wiki locally