Editing Mod Creation

Zero-K runs on the [https://springrts.com Spring engine], which supports a lot of modification of game files. The most advanced mods may amount to creating an entire new game. The Spring engine wiki is a valuable resource for game and mod development using the engine, especially the [https://springrts.com/wiki/Gamedev:Main gamedev page].

Familiarity with the [https://github.com/ZeroK-RTS/Zero-K game repository] or [https://github.com/ZeroK-RTS/Chobby main menu repository] is important for modding and downloading a searchable version is advised. See [[Developing#Getting_Sources]] for how to download a local version of the repository.

== Cosmetic and UI changes ==
Some changes can be made just by adding files to your install directory. The following subfolders of the game repository should support this (feel free to attempt more): unitpics, sounds, unittextures, bitmaps, anims, icons and LuaUI. Replace a file by perfectly matching its name and path.

Here's [[:File:LocalColors.zip|an example config replacement]] for team colour config that you can place in <code>LuaUI/Configs/LocalColors.lua</code>.

Everything in the main menu repository can be overridden.

=== Widgets ===
For LuaUI changes you will need to enabled local widgets and load local widgets first through the advanced settings in <code>Settings/Interface/Misc</code>. Completely new widgets can also be added and loaded.

== More Significant Changes ==
Changing animations, unit behaviour, game mechanics or statistics is a little trickier than cosmetic changes. These types of changes affect everyone in a multiplayer game (as opposed to local interface changes) so require the creation and distribution of a game archive. Entirely new games for the Spring engine can be made with this method.

=== Mutators ===
A mutator is a mod archive that can add and override files relative to a base archive. Mods that make relatively small changes to Zero-K should be made with a mutator, as this keeps filesizes low and allows the mod to stay up to date with fixes or changes to other parts of Zero-K. Even large projects should probably start out as mutators, as it enables the project to build up to handling every aspect of creating a full game archive.

is to make a mutator, this is a game package that includes modified files but otherwise uses the files of the base game. Here is an example mutator [[:File:BaseMod.sdd.zip|BaseMod.sdd.zip]] to get you started. Unzip it in Zero-K/games, and yes, the folder should be named with the extension ".sdd". Your file stucture should look like this.

[[File:baseModFile.png]]

Any file found in the mutator and the base game will be overridden by the version found in the mutator. New files can be added too.

=== Downloading the Zero-K repository ===
Maintaining a local development copy of Zero-K is very useful as poking around the repository can reveal a lot about the required structure for mutators, the names of files to override, and provides a place to trace errors. Clone the game repository as seen on the [[Developing]] page. The fork step can be skipped for now if you are just intending to take a look. Be sure to keep your local copy up to date by regularly using git to pull changes. With a local repository you can eventually open pull requests and push content to be included in the base game (if you're keen).

=== Running your mod - Singleplayer ===
Open a skirmish via the singleplayer menu and click 'Adv Options'.

[[File:AdvOptions.png]]

Click 'Select Mod' and select your mod from the list. The example above is called 'Zero-K Base Mutator v1'. Click Apply.

[[File:SelectMod.png]]

The text beneath the Adv Options button should change from 'Zero-K vX.Y.Z.W' to the name of your mod.

Click 'Start' to start. Note that friends invited via skirmish coop will not be able to join the game unless they have a copy of your mod.

=== Running your mod - Multiplayer ===
* Enable developer mode. Do this by creating an empty text document "devmode.txt" in the same directory as Zero-K.exe. You may need to restart the lobby.
* In the Settings menu a new tab appears: Developer. Edit the Singleplayer setting to be Zero-K Dev.
* Your skirmish/campaign games should now use your modified local copy of zk.sdd. In this mod, the [[Lotus]] has 10 times its normal range.

=== Advanced mutator creation (offline only?) ===
* Download and extract the [[:File:ZK mod template.zip|ZK mod template]] to your Zero-K folder. It should create the folder <code>Zero-K/games/newmod.sdd</code>.
* Enable developer mode (see above). Go to the Developer tab in Settings and edit the Singleplayer setting to 'Zero-K New Mod'.
* Your skirmish/campaign games should now use the contents of <tt>newmod.sdd</tt>. You can change this folder's contents to mod your game.
* To rename your mod or change the version number, change <code>Zero-K/games/newmod.sdd/modinfo.lua</code> and <code>Zero-K/LuaMenu/configs/gameConfig/newMod/mainConfig.lua</code>.
** Make sure <code>zkBaseConfig._defaultGameArchiveName</code> in <tt>mainConfig.lua</tt> matches the name and version in <tt>modinfo.lua</tt>.
** The folders <tt>games/newmod.sdd</tt> and <tt>LuaMenu/configs/gameConfig/newMod</tt> can also be renamed, if you wish to distribute your mod.

[[Category:Development]]{{Navbox manual}}