Editing 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. [http://c2.com/cgi/wiki?RulesOfOptimization 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 ==
* [https://github.com/ZeroK-RTS/Zero-K Zero-K] contains the game proper
** units folder contains unit definition files
*** You can read the wiki about game development for [http://springrts.com/wiki/Main_Page Spring Engine] 
* [https://github.com/ZeroK-RTS/Zero-K-Infrastructure Zero-K-Infrastructure]
** Zero-K.info: Website sources
** ZkLobbyServer: Lobby server (for MP)
** ZkData: Website/server database structure
* [https://github.com/ZeroK-RTS/Chobby Chobby] contains the lobby client
* [https://github.com/ZeroK-RTS/Zero-K-Artwork Zero-K-Artwork] contains sources for 2D art, 3D art and sounds
* [https://github.com/ZeroK-RTS/SpringRTS-Tools 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
* [https://github.com/ZeroK-RTS/Zero-K-Missions 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 <code>then</code> and <code>else</code>.
* 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: <gallery widths="329px">
Styleguide-if-example.JPG|Proper multiline if statement
Styleguide-stackflow.JPG|Example of stacked flow control
</gallery>
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 [https://github.com/ GitHub] using [https://tortoisegit.org/ TortoiseGit]. The game sources are used as an example, however this method applies to other subprojects as well.
* Install [https://tortoisegit.org/download/ TortoiseGit].
* Create a [https://github.com/ GitHub] account.
[[File:ForkZK.jpg]]
* Log in to GitHub and [https://github.com/ZeroK-RTS Locate] the repository you want to edit.
* Click the "Fork" button on the GitHub website to create your own copy on GitHub.
[[File:ZKCloneCopy.png|1103px]]
* Locate your fork on GitHub and click "Code".
* Copy the web URL to your clipboard.
[[File:localCloneZK.jpg]]
* 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.
[[File:cloneUIZK.jpg]]
* 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.
[[File:cloneSuccess.jpg]]
* 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 [https://notepad-plus-plus.org/download/v7.6.6.html 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.
[[File:enableDevMode.jpg]]
* Select 'Zero-K Dev' in Settings → Developer → Singleplayer (you may need to scroll down).
[[File:startTest.jpg]]
* 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 <code>!game zk:dev</code> 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:

[[File:zkmenufolder.jpg]]

To test your changes launch Zero-K.exe with the <tt>dev</tt> arg (i.e. <code>Zero-K.exe dev</code>). On windows this is best done by creating a shortcut and changing the target, as shown below.
[[File:targetZK.jpg]]

== 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 ==
<pre>Zero-K.exe [rapid tag] [engine version]</pre>
Note that the engine specified in arg won't automatically use the main Zero-K folder as its datadir. Add a <tt>springsettings.cfg</tt> file to the engine version's folder with the tag <code>SpringData = path_to_Zero-K_folder</code>

== Modifying infrastructure/tools == 
* Install [https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx Visual Studio Community edition]
* Install the developer or express edition, whichever works best for [https://www.microsoft.com/en-us/sql-server/sql-server-downloads SQL Server express]
* Recommended but perhaps not strictly necessary: Install [https://docs.microsoft.com/en-us/sql/ssms/download-sql-server-management-studio-ssms?view=sql-server-ver15 SQL Server Management Studio]
* Clone to desktop [https://github.com/ZeroK-RTS/Zero-K-Infrastructure 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 <code>(localdb)\mssqllocaldb</code> 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.)

[[File:zk-database-setup.png]]

=== Debugging infrastructure ===
* To run a project right click it, choose "set as startup project" and hit F5 to run using debugger.
* 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. [http://i.imgur.com/2mgizUJ.png Setup]
* 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) [https://www.microsoft.com/en-us/sql-server/sql-server-downloads here] or SQL Server 2017 (for Windows 8 and later) [https://www.microsoft.com/en-us/sql-server/sql-server-2017 here] or SQL Server 2014 (for Windows 7) [https://www.microsoft.com/en-ie/download/details.aspx?id=42299 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 <code>SQL_Latin1_General_CP1_CI_AS</code>. Leave all the parameters default except that I changed server name to SQLSERVER in one of the first steps of wizard.[[File:SQL server collation.png|405px|none]]
** 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 <code>ModeType.Local</code> in <code>GlobalConst.cs</code> (currently line 46) to say something like:<br/><code>Data Source=<hostname (usually your computer name)>\SQLSERVER</code>
** To make things run smoothly the following changes might also be a good idea: In <code>Shared/PlasmaShared/GlobalConst.cs</code> (currently line 137) replace the DefaultEngineOverride with whatever engine version is current. Comment out lines 190 and 238-298 of <code>Zero-K.info/AppCode/PlasmaServer.cs</code> 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 <code>ZkLobbyServer/ZkLobbyServer.cs</code> you may need to comment out the line <code>Task.Factory.StartNew(()=>ReplayStorage.Instance.MigrateReplays(), TaskCreationOptions.LongRunning);</code> 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 [https://stackoverflow.com/a/42989832 here].

=== Modifying The Database Structure ===
* Modify the appropriate files in ./ZkData/Ef/...  and elsewhere ( [https://github.com/ZeroK-RTS/Zero-K-Infrastructure/commit/61addee11e74b09dd5dd73e12d31a28030d84e81 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 <code>Add-Migration [description-of-change-here]</code> 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 <code>Update-Database</code> 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 <code>Update-Database –TargetMigration: TheLastGoodMigration</code> then delete your bad migration files.

== Artwork ==
See [http://zero-k.info/Wiki/Development_Artwork Development Artwork] (outdated)

[[Blender_To_Zero-K|Blender To Zero-K]]

== Missions ==
=== Campaign ===
Campaign planets/missions are defined in [//github.com/ZeroK-RTS/Chobby/tree/master/campaign/sample Chobby/campaign/sample]

=== Standalone missions ===
See [[Mission Editor|Mission Editor start page]]

== Updating PlanetWars for new round ==
:''TODO''
Changing faction:
* Faction ID, name, color in dbo.Faction
* Faction blurb <tt>Faction<Name></tt> 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 [https://zero-k.info/PlanetwarsAdmin 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: [https://zero-k.info/mediawiki/index.php?title=Blender_To_Zero-K Blender to Zero-K Page]

=== Unit pages ===
Part of each unit page is autogenerated by the [//github.com/ZeroK-RTS/SpringRTS-Tools/tree/master/unitguide Unit Guide tool], and uploaded by the [//github.com/ZeroK-RTS/Zero-K-Infrastructure/blob/master/Fixer/WikiPortingMW.cs Wiki bot].

Run <code>export_unit_templates.sh</code> to generate wiki templates for each unit (see <code>export_unit_templates.lua</code> for some configuration options), then have the bot read the generated text files and edit the unit pages accordingly (requires Visual Studio setup as detailed above). The text output can also be used to manually edit pages.

Unit buildicons and radar icons should be uploaded by FTP to manual.zero-k.info (<code>zero-k.info/zkmanual/www/unitpics</code> and <code>/icons</code> respectively). Contact Licho or Histidine for login details.

== itch.io builds ==
Instructions for updating the portable build on [https://itch.io/ 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: <code>butler push <portable folder> zerok/zero-k:portable</code>

== Engine ==
See [https://springrts.com/wiki/Development:Getting_Started 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

[[Category:Development]]