New Game

Spearmint supports running multiple games without modifying the engine. You may also choose to modify the engine to change the default loaded game or make change that are incompatible with Spearmint.

There is essentially no difference between a game and a mod. A game can choose to inherit data files from other game directories which makes it a mod, though the engine does nothing different beside literally inherit data files.

Basic Overview

Each game or mod has a separate "fs_game" directory. Usually the game directory name is all lowercase without spaces. For example, Quake 3's is baseq3. To create a new game or mod simply create a new directory and add data files in a zip file with the file extension changed to .pk3.

The engine will load the game logic code from the game directory when it is loaded using spearmint_x86.exe +set fs_game baseq3 or selecting it in the mods menu. The game logic is written in the C programming language (based on ANSI/C89 standard) and compiled to cross-platform QVM (Quake Virtual Machine) bytecode. See mint-arena for Spearmint's Quake 3 game logic code.

The Spearmint engine and Quake 3 game code are licensed under the GPL General Public License version 3 (with additional changes by ZeniMax). If you modify them you will be required to give the source code to anyone that has the binaries. If distributing the binaries to the public online, for convince for all parties involved it would be best to create a source code repository online on GitHub or some other website.

Game Window Branding

The engine loads the game window title from description.txt in the game directory (example: baseq3/description.txt). The engine defaults to the fs_game value (example: baseq3) if description.txt file is not found.

The engine loads the window icon from either windowicon32.png (32x32; Windows) or windowicon.png (1024x1024; GNU/Linux, OS X, or other platforms) from the game search path (example: baseq3/spearmint-patch-0.5.pk3). For testing you enable/disable using windowicon32 using r_forceWindowIcon32 1 or r_forceWindowIcon32 0.

Game Improvements

Due to Spearmint Quake 3 being limited to Quake 3's data files (plus TrueType fonts...) there are various improvements or changes that aren't included.

You may want to add new CTF/1FCTF/Overload sounds for splitscreen, see New Sounds page.

Some cvars that were moved from client to cgame have not been renamed to keep Team Arena menu compatibility. If you rename them, update q3_ui too.

• cl_freelook -> cg_freelook
• cl_run -> cg_run

Standalone Games

Game Separation

If you want your game to be separate from Spearmint Quake 3 you should change the the settings directory, network game name, and demo (game replay) file extension.

Change the settings (home path) directory so that settings and downloaded mods will be separate from ones for the main Spearmint home path (which may be used by Spearmint Quake 3 and other games). If these are not changed, there could be mods auto downloaded that are shown in both Spearmint and your game but only function in one or the other, which would be annoying for users.

Change the 'network game name' so that only your game and mods for it will be shown in the server browser.

Change the the game demonstration file extension so that it can be associated with a separate engine binary.

These changes can be set using a file named mint-game.settings in your game directory. This can be unzipped for testing but needs to be in a pk3 when you distribute your game.

cvarDefault com_homepath "Jump Land Adventure"
cvarDefault com_gamename JumpLand
cvarDefault com_demoext jumplanddemo

By default settings directory is used if it exists instead of com_homepath, otherwise the following are used. com_homepath can have spaces. On Linux, com_homepath is converted to lowercase and spaces are replaced with hyphens (com_homepath "Jump Land Adventure" is converted to jump-land-adventure).

• Windows: %APPDATA%\Jump Land Adventure\baseq3\
• macOS: /Users/username/Library/Application Support/Jump Land Adventure/baseq3/
• GNU/Linux and other Unix-like platforms: /home/username/.local/share/jump-land-adventure/baseq3/

com_gamename cannot have spaces (it would cause dpmaster not to show your game servers). com_gamename is never displayed to the user in-game, so it doesn't matter what it is as long as it's unique to your game (i.e., not Spearmint or the game name of another game that uses DPmaster protocol).

Distribution

For standalone games (i.e., not a mod) it is probably most convenient for users if you include the engine in your game download. This isn't a requirement, having the user download Spearmint separate would work fine.

If you include the engine, you can include a file named spearmint-gamelist.txt to automatically load your game. Only include it if bundling the engine, otherwise it will overwrite Spearmint Quake 3's file when extracted.

If not including the engine, you may want to have a Windows .bat file or Unix shell script to auto load your game using spearmint_x86.exe +set fs_game jumpland or similar. Otherwise the user will need to have Spearmint Quake 3 installed to choose to load your game through the menu. This would ideally be solved in the future by loading a game launcher if Quake 3 is not installed.

Alternatively you can compile the engine with BASEGAME set to your game directory.

Custom Built Engine

Turtle Arena ships Spearmint binaries from the release downloads. You can optionally use a custom built engine to set the default game and Windows EXE icon that is still compatible with Spearmint. You will need to compile the engine for each platform (Windows, GNU/Linux, macOS, ..) you want to support.

If you have not compiled Spearmint, you should probably figure that out before getting to far into this. See Compiling.

macOS requires additional changes to make-macosx-app.sh for customizing the AppBundle. They are not documented here. For Turtle Arena, Spearmint.app/Contents/Info.plist from the release download is modified instead changing make-macosx-app.sh.

The Windows EXE icon is located at misc/quake3.ico.

The default loaded game BASEGAME is in engine's Makefile and code/qcommon/qcommon.h. Changing it does not break network compatibility.

It would be useful to leave PRODUCT_NAME and PRODUCT_VERSION (in both Makefile and code/qcommon/qcommon.h) as they are, to show what version of Spearmint this is based on.

You will be required to give the source code to anyone that has the engine binaries. If distributing the binaries to the public online, for convince for all parties involved it would be best to create a source code repository online on GitHub or some other website.

Extending the Engine, Incompatible with Spearmint

After you have a custom compiled version of Spearmint, you may decide to add a new features or make changes that make your engine incompatible with Spearmint.

Some examples for incompatible changes are when you change the data that is passed between the engine and renderer, engine and Game VM, engine and CGame VM, or change the behavior of shader keywords. New shader keywords should maybe be considered a incompatible change too.

If you make the engine incompatible with Spearmint, there are some changes that would be nice if you made. I'd like to avoid crashes or issues when someone tries to mix Speamint API and custom API engines and game logic. So if you want to make the all the changes without being concerned about which APIs you've actually changed, that's fine.

Change PRODUCT_NAME (in code/qcommon/qcommon.h) from Spearmint to Jump Land Engine and optionally change PRODUCT_VERSION (in both Makefile and qcommon.h) to show that the engine is not compatible with Spearmint.

If you have not already renamed the engine client and server, please do so; This can be done by changing CLIENT and SERVER in Makefile.

Files and Network

In the engine source files Makefile and code/qcommon/qcommon.h there are options that correspond to the command line options / mint-game.settings cvarDefaults already discussed.

While it's possible to set these on a per-game directory basis, if your engine is incompatible with Spearmint it would be best to change the defaults.

BASEGAME is in both Makefile and code/qcommon/qcommon.h. The other options are only in code/qcommon/qcommon.h.

• BASEGAME corresponds to fs_game
• GAMENAME_FOR_MASTER corresponds to com_gamename (default "Spearmint")
• HOMEPATH_NAME corresponds to com_homepath (default "Spearmint")
• DEMOEXT corresponds to com_demoext (default "mintdemo")

Renderer API

If you change code/renderercommon/tr_public.h or code/renderercommon/tr_types.h which contains the renderer API, change the value of RENDERER_PREFIX in Makefile and code/qcommon/qcommon.h from spearmint-renderer- to jumpland-renderer-.

Game / CGame VM API

If you change the Game/CGame VM APIs you may want to change the name of the VMs to allow a game to have VMs for both your engine and Spearmint or make it obvious what game they are for. Change VM_PREFIX in (game code) Makefile and (engine) code/qcommon/qcommon.h from mint- to jumpland-.

If you change what the engine expects from Game VM syscalls or what the engine passes to vmMain calls, change GAME_API_NAME in code/game/g_public.h from "SPEARMINT_GAME" to "JUMPLAND_GAME" in both the engine and your game code projects.

If you change code/renderercommon/tr_types.h or what the engine expects from CGame VM syscalls or what the engine passes to vmMain calls, change CG_API_NAME in code/cgame/cg_public.h from "SPEARMINT_CGAME" to "JUMPLAND_CGAME" in both the engine and your game code projects.