Difference between revisions of "Mod Creation"

From Zero-K
Jump to navigation Jump to search
(add local colors)
 
(15 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
For instructions on how to play someone else's mod go to [[How To Play Mods]]. For how to create and run a stat tweak go to [[Quick Stat Tweaks]], and to save them look at [[Custom Modes]].
 +
 
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].
 
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].
  
Line 4: Line 6:
  
 
== Cosmetic and UI changes ==
 
== 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.
+
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. Everything in the main menu repository can be overridden.
 +
 
 +
=== Common Changes ===
 +
Configuration files from the [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaUI/Configs Zero-K repositry] can be copied to <code>Zero-K/LuaUI/Configs</code> and modified. Some are made with configuration in mind while others are a bit challenging to modify. Two easy to configure aspects of the interface are as follows.
 +
* To configure teamcolours, unzip [[:File:LocalColors.zip|this file]] so that you have <code>LuaUI/Configs/LocalColors.lua</code>. Modify the values within and select 'Custom' in the dropdown menu at the top left corner of the screen ingame.
 +
* To configure the position of commands and states in the command panel, copy [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaUI/Configs/integral_menu_commands.lua this file] to <code>Zero-K/LuaUI/Configs/integral_menu_commands.lua</code> and edit it.
 +
 
 +
=== Widgets ===
 +
To add widgets or override existing widgets you must enabled local widgets and load local widgets first through the advanced settings in <code>Settings/Interface/Misc</code>.
 +
 
 +
== 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.
 +
 
 +
This page tells you how to use Zero-K to easily set up a modding environment and how to run mods on the Zero-K server. For specific information on the components that make up a mod consult the [https://springrts.com/wiki/Gamedev:Main SpringRTS wiki].
 +
 
 +
=== 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. Here is an example mutator to get you started ([[:File:BaseMod.sdd.zip|download]]). Unzip it in Zero-K/games, and yes, the folder should be named with the extension ".sdd". Your file stucture should look like this.
  
Here's [[:File:LocalColors.zip|an example config replacement]] for team colour config that you can place in <code>LuaUI/Configs/LocalColors.lua</code>.
+
[[File:baseModFile.png]]
  
Everything in the main menu repository can be overridden.
+
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.
  
=== Widgets ===
+
=== Downloading the Zero-K repository ===
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.
+
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 ===
 +
Go to Settings -> Lobby and enable 'Show technical mods list'.
 +
 
 +
[[File:TechnicalMods.png]]
 +
 
 +
Open a skirmish via the singleplayer menu and click 'Adv Options'.
 +
 
 +
[[File:AdvOptions.png]]
 +
 
 +
Click 'Select Mod' and select your mod from the list. Note that this button only appears if 'Show technical mods list' is enabled, and you may have to restart the lobby to apply the setting. The example above is called 'Zero-K Base Mutator v1'. Click Apply.
 +
 
 +
[[File:SelectMod2.png]]
 +
 
 +
The text beneath the Adv Options button should change from 'Zero-K vX.Y.Z.W' to the name of your mod.
  
== Mechanics changes ==
+
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.
Changing animations, unit behaviour, game mechanics or statistics is a little trickier than cosmetic changes. These changes are also incompatible with the base game. There are two ways to make these changes.
 
  
=== Mutator ===
+
=== Running your mod - Multiplayer ===
The relatively simple way is to make a mutator, this is a game package that depends on the base game. Here is an example mutator [[:File:Zk.sdd.zip|zk.sdd.zip]] to get you started. Unzip it in games, and yes, the folder should be named with the extension ".sdd". Your file stucture should look like this.
+
First check modinfo.lua to make sure that your mod's name, shortname and version are unlikely to clash with any other existing mod. Then turn your sdd into a sdz by first zipping it (as follows on Windows) and renaming it such that the file extension is <code>.sdz</code>.
  
[[File:Capture1.PNG]]
+
[[File:Zipgame.jpg]]
  
Overwrite any files to make edits.
+
Here is a zip containing <code>baseMod.sdz</code>, the packaged version of <code>baseMod.sdd</code> ([[:File:BaseModPackaged.zip|download]]). Test that your <code>.sdz</code> file runs and upload it to [https://zero-k.info/Maps zero-k.info/Maps].
  
=== Full repository ===
+
[[File:MapUpload.png]]
Fork and clone the game repository as seen on the [[Developing]] page. This gives you a standalone version of the game that depends on nothing. Be warned, you will need to pull changes via git in order to receive updates. The advantages of this method are version control, a locally searchable repository, and the ability to eventually open pull requests and push content to be included in the base game (if you're keen).
 
  
=== Running your mod ===
+
# Host a Custom passworded multiplayer battle.
Start a Custom battle lobby, with a password, on the multiplayer server. Type <code>!game zk:dev</code> to switch to your mod, make sure you have a green tick. Other players can join and play your mod if they have the exact same mod files. If you made a mod with the full repository method then they can clone your fork on GitHub.
+
# Select your mod from the 'Select Mod' list under 'Adv Options' (just as you would for singleplayer).
 +
# Other players that join the room will automatically download your mod.
 +
# Click start to play.
  
=== Running your mod, singleplayer ===
+
It is best if you play from your sdz version rather than your sdd version, as any changes between your local version and uploaded archive could cause desync. It is a good idea to give your development .sdd version a unique version name.
* 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?) ===
+
You can now use [[Custom Modes]] to make a preset that hosts your mod. There is currently no site-based way to distribute custom modes, but they can be included manually in lobby releases.
* 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}}
 
[[Category:Development]]{{Navbox manual}}

Latest revision as of 18:22, 18 November 2020

For instructions on how to play someone else's mod go to How To Play Mods. For how to create and run a stat tweak go to Quick Stat Tweaks, and to save them look at Custom Modes.

Zero-K runs on the 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 gamedev page.

Familiarity with the game repository or 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. Everything in the main menu repository can be overridden.

Common Changes

Configuration files from the Zero-K repositry can be copied to Zero-K/LuaUI/Configs and modified. Some are made with configuration in mind while others are a bit challenging to modify. Two easy to configure aspects of the interface are as follows.

  • To configure teamcolours, unzip this file so that you have LuaUI/Configs/LocalColors.lua. Modify the values within and select 'Custom' in the dropdown menu at the top left corner of the screen ingame.
  • To configure the position of commands and states in the command panel, copy this file to Zero-K/LuaUI/Configs/integral_menu_commands.lua and edit it.

Widgets

To add widgets or override existing widgets you must enabled local widgets and load local widgets first through the advanced settings in Settings/Interface/Misc.

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.

This page tells you how to use Zero-K to easily set up a modding environment and how to run mods on the Zero-K server. For specific information on the components that make up a mod consult the SpringRTS wiki.

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. Here is an example mutator to get you started (download). Unzip it in Zero-K/games, and yes, the folder should be named with the extension ".sdd". Your file stucture should look like this.

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

Go to Settings -> Lobby and enable 'Show technical mods list'.

TechnicalMods.png

Open a skirmish via the singleplayer menu and click 'Adv Options'.

AdvOptions.png

Click 'Select Mod' and select your mod from the list. Note that this button only appears if 'Show technical mods list' is enabled, and you may have to restart the lobby to apply the setting. The example above is called 'Zero-K Base Mutator v1'. Click Apply.

SelectMod2.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

First check modinfo.lua to make sure that your mod's name, shortname and version are unlikely to clash with any other existing mod. Then turn your sdd into a sdz by first zipping it (as follows on Windows) and renaming it such that the file extension is .sdz.

Zipgame.jpg

Here is a zip containing baseMod.sdz, the packaged version of baseMod.sdd (download). Test that your .sdz file runs and upload it to zero-k.info/Maps.

MapUpload.png

  1. Host a Custom passworded multiplayer battle.
  2. Select your mod from the 'Select Mod' list under 'Adv Options' (just as you would for singleplayer).
  3. Other players that join the room will automatically download your mod.
  4. Click start to play.

It is best if you play from your sdz version rather than your sdd version, as any changes between your local version and uploaded archive could cause desync. It is a good idea to give your development .sdd version a unique version name.

You can now use Custom Modes to make a preset that hosts your mod. There is currently no site-based way to distribute custom modes, but they can be included manually in lobby releases.