Custom mods

AssaultCube allows 3rd party developers to "MOD" the game by using the existing AssaultCube engine/data for their own modifications, so long as they don't break any of the license agreements for the particular media they're modifying.

However, many don't realise that you can release your MOD without needing to overwrite existing data (a.k.a: content replacement). The advantage of this is that it allows you to add MODS cleanly without placing the files inside the main AssaultCube directory. This means, that if you don't want to play AssaultCube using the MOD, or want to play AssaultCube using a different MOD, you can without having to install several copies of AssaultCube.

How to set up a MOD in this way is quite easy. How it works, is when AssaultCube loads files for the game, it looks into several directories to find the files needed to load the game. This list of directories can be simply extended, by using the --mod argument which lets you add a custom directory to recursively load additional files from.

While using the --mod argument, when AssaultCube looks for any resources it will load all its normal files first, then it will check your MOD folders for additional files and if any of the filepaths in that folder match files that need to be loaded, AssaultCube will then load these MOD files, instead of the original files.

IMPORTANT: Please ensure that if your users are using a "--home" directory, that they extract the mod into that directory (rather than the main AssaultCube directory), or else it won't work.

Please note: AssaultCube's main license forbids redistributing a MOD with ALL of AssaultCube's original files, as AssaultCube's files use a variety of different licenses. If you want to modify and/or redistribute anything from AssaultCube, you MUST check each redistributed file's license allows you to do this in the way you are redistributing it. This is the main reason that the --mod argument exists to begin with.

Example:

Assume you want to create a mod that provides a customized HUD-gun; here's how you would create a mod directory:

1. Create a "MOD" directory in the AssaultCube folder: ./mods/MyMod1/
2. Inside the MOD directory, place your customized HUD-gun files, using a folder scheme that matches how it would normally be placed within AssaultCube's packaging: ./mods/MyMod1/packages/models/hudguns/assaultrifle.md3
3. Now to make AssaultCube aware of this mod you'll need to start AssaultCube with the argument --mod="mods/MyMod1".

To start AssaultCube with the mod argument all the time, you can create your own AssaultCube launcher (this option is not available on Apple Mac OS X). Simply copy/paste the existing assaultcube.sh (Linux) or assaultcube.bat (Windows) file with a new filename. Then edit it with a notepad application.

For Windows users, add your new --mod command line option to the end of the file.
For Linux users, add your new --mod command line option into the CUBE_OPTIONS line.