Zero-K:Developing

New developers should read this before touching the source.

ZK's Devving Philosophy (social rules)

"War is a product of anticommunication"
- Communicate with other devs about your changes/fixes, let them understand the issue. Do not make 'random' changes.
"Do not create work for other people."
- Have responsibility for your changes/commit. Do not leave bugs that require other people to fix.
"Readability & performance are equally important."
- Optimize code, but not to the point of unreadability. Remember the rules of optimization:
  - Don't.
  - Don't (yet).
  - Profile before doing it.
"If it ain't broke, don't fix it."
- Don't code fixes that nobody wants to problems that don't exist.

What is in source codes

Zero-K contains the game proper
- units folder contains unit definition files
  - You can read the wiki about game development for Spring Engine
Zero-K-Infrastructure
- Zero-K.info: Website sources
- ZkLobbyServer: Lobby server (for MP)
- ZkData: Website/server database structure
Chobby contains the lobby client
Zero-K-Artwork contains sources for 2D art, 3D art and sounds
SpringRTS-tools contains various dev tools
- Upspring - required to edit the .3do and .s3o model files used in the game
- MapIconBuilder - unit map icon sources are here
Zero-K-Missions contains source files for official ZK missions

Style Guide

The lua in the menu (chobby) and game proper should use the following whitespace:

Indent with tabs.
A tab may only follow a newline or another tab.
If the text across two lines is being aligned (such as for a long function) then the two lines must have the same number of tabs.
Don't try stack flow of control into one line. For example, put newlines after then and else.
End files with a newline.
Commas should be followed by whitespace. Relations (=, <, <=, >=, ==, ~=) should have whitespace on each side.
if a conditional is to take up multiple lines, double indent the extra lines and end the line with a conjunction as shown:
Proper multiline if statement
Example of stacked flow control

These guidelines are not necessarily followed in old files so updating them with a separate commit is a good idea prior to making large changes. Also, unitdefs use two-space indentation instead of tabs.

There are a few guildines for dealing with Spring functions.

Localisation of Spring.Function should be named spFunction.
Localisation of Spring.MoveCtrl.Function should be named spMoveCtrlFunction.
Spring.GetCommandQueue should be used rather than Spring.GetUnitCommands (it's an alias, we just picked one).

Getting sources

This is a guide to downloading Zero-K sources from GitHub using TortoiseGit. The game sources are used as an example, however this method applies to other subprojects as well.

Install TortoiseGit.
Create a GitHub account.

Log in to GitHub and Locate the repository you want to edit.
Click the "Fork" button on the GitHub website to create your own copy on GitHub.

Error creating thumbnail: File missing

Locate your fork on GitHub and click "Code".
Copy the web URL to your clipboard.

Create a folder called 'zk.sdd' in your Zero-K install under games.
Right click on 'zk.sdd' and select 'Git Clone...' from the context menu.

Copy the web URL into the 'URL:' field of the clone interface.
Ensure that the 'Directory:' field ends in 'zk.sdd'. It is likely to automatically contain the path '...\Zero-K\games\zk.sdd\Zero-K' so be sure to delete the '\Zero-K' at the end.

Wait for the sources to download.
Your 'zk.sdd' folder should look something like the image above.

Updating sources

Keep your sources up to date by periodically syncing your fork to the original repository (using 'compare', see: https://github.com/KirstieJane/STEMMRoleModels/wiki/Syncing-your-fork-to-the-original-repository-via-the-browser, then do "rebase and merge" instead of "merge") and doing TortoiseGit → Pull on your repository folder to take the changes from GitHub to your local files.

Modifying the game

For personal modding, see Mod Creation

Follow the instructions in 'Getting sources' the download the Zero-K game sources. Feel free to inspect and edit the game files. Most developers using Windows edit lua files with Notepad++.

To test your changes:

(If using Windows make sure your file explorer has file name extensions enabled; for example the chobby_wrapper_port file should have a .txt on the end of its name.)
Create an empty text file named 'devmode.txt' in the same directory as Zero-K.exe.
Launch Zero-K.exe.

Select 'Zero-K Dev' in Settings → Developer → Singleplayer (you may need to scroll down).

From the main menu select Singleplayer → Skirmish → Advanced → Start to launch a test game. Note that the game type should be automatically set to 'Zero-K $VERSION'.
In the game, press F8 to open debug console. It'll display errors and output to the log.

To test game changes in multiplayer:

Make sure all players have a zk.sdd folder with the same exact files on their local Zero-K installation, or the game will desync.
Launch Zero-K and create a passworded multiplayer lobby.
Set the room type to Custom.
Type !game zk:dev to set the game type to 'Zero-K $VERSION'.
Launch the game normally once the other testers have joined.

Modifying the lobby menu

Follow the instructions in 'Getting sources' with the following adjustments:

The repository that you want to edit is https://github.com/ZeroK-RTS/Chobby.
It is best to call the folder something like 'zkmenu.sdd', to avoid confusion.

Make sure that the 'Directory:' field ends in '.sdd'. You should end up with something like this:

To test your changes launch Zero-K.exe with the dev arg (i.e. Zero-K.exe dev). On windows this is best done by creating a shortcut and changing the target, as shown below.

Submitting changes

Git provides a systematic way to review and merge changes into the main repositories. The main game repository is used as example, but this method works for other repositories as well.

The simple way to commit changes is as follows.

Make some changes to your local files.
Right click on 'zk.sdd' and select 'Git Commit'.
Write a description of the changes and click 'Commit'.
Right click on 'zk.sdd' and select TortiseGit → Push.
Enter your GitHub login and password when prompted. The changes should now appear on your fork in GitHub.
Navigate to https://github.com/ZeroK-RTS/Zero-K/pulls and click "New Pull Request".
Click "compare across forks" to make your fork visible.
Set your fork to be the head repository.
Write a title and description of the changes, then create the pull request.

This creates a proposal to apply your changes to the main game. Be sure to check up on it and respond to comments.

A more advanced method involves creating branches locally with TortiseGit → Create Branch and committing blocks of related changes to a single branch. You are then able to make pull requests from branches. This allows branches to be smaller and more focused, which is desirable when merging.

Make sure to keep your repository up to date to make merges less difficult.

Returning to default settings

Personalized config changes and widgets in-use can be reset for both the game and lobby.

For the lobby, rename or remove the 'luamenu' folder from the base directory.
To set in-game widgets and settings to default, rename or remove the 'luaui' folder from the base directory.

Zero-K.exe launch flags

Zero-K.exe [rapid tag] [engine version]

Note that the engine specified in arg won't automatically use the main Zero-K folder as its datadir. Add a springsettings.cfg file to the engine version's folder with the tag SpringData = path_to_Zero-K_folder

Modifying infrastructure/tools

Install Visual Studio Community edition
Install the developer or express edition, whichever works best for SQL Server express
Recommended but perhaps not strictly necessary: Install SQL Server Management Studio
Clone to desktop Zero-K infrastructure
Test by opening Zero-K.sln in Visual Studio
Infra overview/structure Zero-K Infra Guide (Incomplete/WIP)

Initializing Website Database

You may need to setup the database connection for the website. In order to do that: Open Visual Studio, open the Server Explorer panel (under the View menu), right click Data Connections → Add Connection → Sql Server. Enter (localdb)\mssqllocaldb in the Server Name field, after which zero-k_local will appear in the dropdown list of databases.

(If zero-k_local does not appear, type it in the text box and press OK; Visual Studio will ask whether you would like to create the database. This may require you to have administrator rights on the computer.)

Debugging infrastructure

To run a project right click it, choose "set as startup project" and hit F5 to run using debugger.
Error creating thumbnail: File missing

Startup projects setup.
You can enable multiple startup projects to test entire infrastructure locally (game servers, lobby etc). Enable asp.net, springie and ZeroKLobby projects to test it all together.
To run asp.net:
- It's required that you install MS SQL Server on your local PC.
  - You can get SQL Server 2019 (For Windows 10) here or SQL Server 2017 (for Windows 8 and later) here or SQL Server 2014 (for Windows 7) here. For SQL Server 2014, the file you will need is called SQLEXPR_x64_ENU or SQLEXPR_x86_ENU. Make sure you install version that matches your version of Windows (i.e. x86 vs x64).
  - During the installation, set collation to SQL_Latin1_General_CP1_CI_AS. Leave all the parameters default except that I changed server name to SQLSERVER in one of the first steps of wizard.
    Error creating thumbnail: File missing
- Right click asp.net → properties → web → check "Specific Page" and leave it blank. Otherwise you get errors when trying to host locally.
- Make sure SQL Server is running (check the Sql Server Configuration Manager in the Start Menu). If you can't connect, edit the data source for ModeType.Local in GlobalConst.cs (currently line 46) to say something like:
  Data Source=<hostname (usually your computer name)>\SQLSERVER
- To make things run smoothly the following changes might also be a good idea: In Shared/PlasmaShared/GlobalConst.cs (currently line 137) replace the DefaultEngineOverride with whatever engine version is current. Comment out lines 190 and 238-298 of Zero-K.info/AppCode/PlasmaServer.cs unless somebody can supply instructions on how to make the torrent errors go away.
- (As of June 2023) a few extra steps: in Visual Studio open Tools - Options - Projects and Solutions - Web Projects and tick "Use the 64 bit version of IIS Express...". In ZkLobbyServer/ZkLobbyServer.cs you may need to comment out the line Task.Factory.StartNew(()=>ReplayStorage.Instance.MigrateReplays(), TaskCreationOptions.LongRunning); currently on line 104.

TODO: add download links for sample database tables here. Users and clans are probably easier to make yourself for most purposes. For now, if you need this ask Licho, Histidine, DeinFreund or Anarchid. Aquanim has sample tables for maps and Planetwars structures, if that is all that you need.

Testing

When you run the server locally a browser window with the website should appear. You can connect to your local server with the normal lobby by going to Settings and setting the target to "localhost" rather than "zero-k.info".
Once you have created an account you can make it an admin account by editing the database with SQL Server Management Studio. Open the list of databases in the tree on the left, open the Zero-K database, then in the Tables folder right-click on dbo.Accounts and select "Edit Top 200 Rows". Set the "AdminLevel" of your account to 2 for full admin powers.

If you are running Zero-K infrastructure on a separate machine on your local network, you will likely get a 400 Bad Hostname error on connecting to the website or the lobby. This is an issue with port opening and a likely fix is here.

Modifying The Database Structure

Modify the appropriate files in ./ZkData/Ef/... and elsewhere ( this commit should be a reasonable guide; don't worry about the migration files, they are created later )
In Visual Studio open Tools > NuGet Package Manager > Package Manager Console
At the top of the window which appears, there is a "Default project" dropdown box. Set this to ZkData.
Type the command Add-Migration [description-of-change-here] into the package manager console. This should create some migration files with your description and a timestamp in the name in the Migrations folder of ZkData.
In some cases you may now need to manually edit the created migration files to set defaults and the like?
Type the command Update-Database into the package manager console. This should update the database structure.
To revert a migration that has not yet been pushed to the main repository, run Update-Database –TargetMigration: TheLastGoodMigration then delete your bad migration files.

Artwork

See Development Artwork (outdated)

Blender To Zero-K

Missions

Campaign

Campaign planets/missions are defined in Chobby/campaign/sample

Standalone missions

See Mission Editor start page

Updating PlanetWars for new round

TODO

Changing faction:

Faction ID, name, color in dbo.Faction
Faction blurb Faction<Name> on sitewiki
Add/change icons if needed
- Site: img/factions/<name>.png
- Game: LuaUI/Configs/Factions
- Chobby: LuaMenu/Images/Factions
- Does chobby download them automatically? Presumably not

Using Planetwars admin interface: Change to a different galaxy if desired, reset PW

Wiki

See Editing Help

Making/Editing a unit

See the Blender to Zero-K page for a comprehensive guide on modelling, texturing, and baking aoplates for Zero-K units: Blender to Zero-K Page

Unit pages

Unit infoboxes can now be automatically kept up to date using Template:Autoinfobox zkunit. See the template page and Module:UnitData for more information.

Unit buildicons and radar icons require manual uploading to the Zero-K website. (zero-k.info/zkmanual/www/unitpics and /icons respectively). If an icon is missing, poke Licho or Histidine to fix it. Alternatively, buildicons can be obtained directly from the GitHub CDN.

itch.io builds

Instructions for updating the portable build on itch.io:

Download latest Zero-K portable from https://zerok.itch.io/zero-k, extract to a folder
Download butler (see guide at https://itch.io/docs/butler/)
Modify extracted portable folder so that its contents are the same as what the user will download
Run butler with command: butler push <portable folder> zerok/zero-k:portable

Engine

See Spring Engine Development

Releasing Zero-K on steam

Force push master to stable branch
Go to zero-k.info engine list, click rebuild steam on current engine version