Difference between revisions of "Zero-K:Developing"

From Zero-K
Jump to navigation Jump to search
(→‎Wiki: Update unit page instructions)
 
(51 intermediate revisions by 11 users not shown)
Line 7: Line 7:
 
** Have responsibility for your changes/commit. Do not leave bugs that require other people to fix.
 
** Have responsibility for your changes/commit. Do not leave bugs that require other people to fix.
 
* "Readability & performance are equally important."  
 
* "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]:
+
** Optimize code, but not to the point of unreadability. [//c2.com/cgi/wiki?RulesOfOptimization Remember the rules of optimization]:
 
*** Don't.
 
*** Don't.
 
*** Don't (yet).
 
*** Don't (yet).
Line 28: Line 28:
 
** MapIconBuilder - unit map icon sources are here
 
** 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
 
* [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 ==
 
== Getting sources ==
This is a guide to downloading Zero-K sources from [https://github.com/ GitHub] using [https://tortoisegit.org/ TortiseGit]. The game sources are used as an example, however this method applies to other subprojects as well.
+
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/ TortiseGit].
+
* Install [https://tortoisegit.org/download/ TortoiseGit].
 
* Create a [https://github.com/ GitHub] account.
 
* Create a [https://github.com/ GitHub] account.
 
[[File:ForkZK.jpg]]
 
[[File:ForkZK.jpg]]
 
* Log in to GitHub and [https://github.com/ZeroK-RTS Locate] the repository you want to edit.
 
* 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.
 
* Click the "Fork" button on the GitHub website to create your own copy on GitHub.
[[File:cloneZK.jpg]]
+
[[File:ZKCloneCopy.png|1103px]]
* Locate your fork on GitHub and click "Clone or Download".
+
* Locate your fork on GitHub and click "Code".
 
* Copy the web URL to your clipboard.
 
* Copy the web URL to your clipboard.
 
[[File:localCloneZK.jpg]]
 
[[File:localCloneZK.jpg]]
Line 48: Line 67:
 
* Wait for the sources to download.
 
* Wait for the sources to download.
 
* Your 'zk.sdd' folder should look something like the image above.
 
* 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 ==
 
== Modifying the game ==
 
:''For personal modding, see [[Mod Creation]]''
 
:''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++].
+
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-plus-plus.org/download/ Notepad++].
  
 
To test your changes:
 
To test your changes:
* Create an empty file named 'devmode.txt' in the same directory as Zero-K.exe.
+
* (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.
 
* Launch Zero-K.exe.
 
[[File:enableDevMode.jpg]]
 
[[File:enableDevMode.jpg]]
* Select 'Zero-K Dev' in Settings -> Developer -> Singleplayer (you may need to scroll down).
+
* Select 'Zero-K Dev' in Settings Developer Singleplayer (you may need to scroll down).
 
[[File:startTest.jpg]]
 
[[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'.
+
* 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.
 
* In the game, press F8 to open debug console. It'll display errors and output to the log.
  
To submit your changes:
+
To test game changes in multiplayer:
* Commit your changes by right clicking on 'zk.sdd' and selecting 'Git Commit'.
+
* 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'.
 
* Write a description of the changes and click 'Commit'.
* Right click on 'zk.sdd' and select TortiseGit -> Push.
+
* 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.
 
* 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".
 
* Navigate to https://github.com/ZeroK-RTS/Zero-K/pulls and click "New Pull Request".
 
* Click "compare across forks" to make your fork visible.
 
* Click "compare across forks" to make your fork visible.
* Set the head repository to be your fork.
+
* Set your fork to be the head repository.
* Write a title and description, then create the pull request.
+
* 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.
 
This creates a proposal to apply your changes to the main game. Be sure to check up on it and respond to comments.
  
== Modifying lobby menu ==
+
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.
#Create a folder <code>games/chobby.sdd</code> in the Zero-K installation folder.
+
 
#Clone to desktop [https://github.com/ZeroK-RTS/Chobby Chobby] and save it to <code>chobby.sdd/</code>. This folder should contain multiple files/folders, such as <code>modinfo.lua</code>.
+
Make sure to keep your repository up to date to make merges less difficult.
#Launch Zero-K.exe with the <tt>dev</tt> arg (i.e. <code>Zero-K.exe dev</code>)
+
 
 +
== 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 launch flags ==
Line 84: Line 133:
 
== Modifying infrastructure/tools ==  
 
== Modifying infrastructure/tools ==  
 
* Install [https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx Visual Studio Community edition]
 
* Install [https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx Visual Studio Community edition]
* Install [http://www.microsoft.com/en-us/server-cloud/products/sql-server-editions/sql-server-express.aspx SQL Server express]
+
* 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]
 
* Clone to desktop [https://github.com/ZeroK-RTS/Zero-K-Infrastructure Zero-K infrastructure]
 
* Test by opening Zero-K.sln in Visual Studio
 
* Test by opening Zero-K.sln in Visual Studio
 +
* Infra overview/structure [[Zero-K Infra Guide]] (Incomplete/WIP)
  
 
=== Initializing Website Database ===
 
=== 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, 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.  
+
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]]
 
[[File:zk-database-setup.png]]
Line 95: Line 148:
 
=== Debugging infrastructure ===
 
=== Debugging infrastructure ===
 
* To run a project right click it, choose "set as startup project" and hit F5 to run using debugger.
 
* 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]
+
*[[File:Startup projects.png|thumb|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:
 
* To run asp.net:
** It's required that you install MS SQL Express on your local PC. Get one from [https://www.microsoft.com/en-us/download/confirmation.aspx?id=42299| here]. 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 leave all the parameters default except that I changed server name to SQLEXPRESS in one of the first steps of wizard.
+
** It's required that you install MS SQL Server on your local PC.  
** Right click asp.net -> properties -> web -> check "Specific Page" and leave it blank. Otherwise you get errors when trying to host locally.
+
*** 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).  
** 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> to say something like:<br/><code>Data Source=<hostname (usually your computer name)>\SQLEXPRESS</code>
+
*** 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 ==
 
== Artwork ==
 
See [http://zero-k.info/Wiki/Development_Artwork Development Artwork] (outdated)
 
See [http://zero-k.info/Wiki/Development_Artwork Development Artwork] (outdated)
 +
 +
[[Blender_To_Zero-K|Blender To Zero-K]]
  
 
== Missions ==
 
== Missions ==
Line 126: Line 202:
 
== Wiki ==
 
== Wiki ==
 
See [[Editing Help]]
 
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 ===
 
=== 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].
+
Unit infoboxes can now be automatically kept up to date using [[Template:Autoinfobox zkunit]]. See the template page and [[Module:UnitData]] for more information.
  
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 require manual uploading to the Zero-K website. (<code>zero-k.info/zkmanual/www/unitpics</code> and <code>/icons</code> respectively). If an icon is missing, poke Licho or Histidine to fix it. Alternatively, buildicons can be obtained directly from the GitHub CDN.
 
 
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 ==
 
== itch.io builds ==
Line 144: Line 221:
 
== Engine ==
 
== Engine ==
 
See [https://springrts.com/wiki/Development:Getting_Started Spring Engine Development]
 
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]]
 
[[Category:Development]]

Latest revision as of 20:55, 11 May 2024

New developers should read this before touching the source.

ZK's Devving Philosophy (social rules)[edit]

  • "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."
  • "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[edit]

  • Zero-K contains the game proper
    • units folder contains unit definition files
  • 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[edit]

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[edit]

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.

ForkZK.jpg

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

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.

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.

CloneSuccess.jpg

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

Updating sources[edit]

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[edit]

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.

EnableDevMode.jpg

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

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 !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[edit]

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

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

Zkmenufolder.jpg

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. TargetZK.jpg

Submitting changes[edit]

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[edit]

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[edit]

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[edit]

Initializing Website Database[edit]

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

Zk-database-setup.png

Debugging infrastructure[edit]

  • 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[edit]

  • 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[edit]

  • 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[edit]

See Development Artwork (outdated)

Blender To Zero-K

Missions[edit]

Campaign[edit]

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

Standalone missions[edit]

See Mission Editor start page

Updating PlanetWars for new round[edit]

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[edit]

See Editing Help

Making/Editing a unit[edit]

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[edit]

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[edit]

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[edit]

See Spring Engine Development

Releasing Zero-K on steam[edit]

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