Difference between revisions of "Zero-K:Developing"

From Zero-K
Jump to navigation Jump to search
(9 intermediate revisions by 4 users not shown)
Line 2: Line 2:
  
 
== ZK's Devving Philosophy (social rules) ==
 
== ZK's Devving Philosophy (social rules) ==
* "War is anticommunication!"  
+
* "War is a product of anticommunication"
 
** Communicate with other devs about your changes/fixes, let them understand the issue. Do not make 'random' changes.
 
** 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."
 
* "Do not create work for other people."
Line 17: Line 17:
 
* [https://github.com/ZeroK-RTS/Zero-K Zero-K] contains the game proper
 
* [https://github.com/ZeroK-RTS/Zero-K Zero-K] contains the game proper
 
** units folder contains unit definition files
 
** units folder contains unit definition files
** you can read wiki about game development for [https://springrts.com/wiki/Main_Page spring engine]  
+
*** 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]
 
* [https://github.com/ZeroK-RTS/Zero-K-Infrastructure Zero-K-Infrastructure]
** ZeroKLobby - is the lobby program for windows used as main interface and downloader
+
** Zero-K.info: Website sources
** Zero-K.info - is the 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/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
 
* [https://github.com/ZeroK-RTS/SpringRTS-Tools SpringRTS-tools] contains various dev tools
Line 28: Line 30:
  
 
== Getting sources ==
 
== Getting sources ==
* Get a [https://github.com/ GitHub] account and download [https://desktop.github.com/ Github for desktop]
+
* Get a [https://github.com/ GitHub] account and download [https://desktop.github.com/ GitHub Desktop]
* [https://github.com/ZeroK-RTS Locate] repository you want to edit and click "clone in desktop" button on website
+
* [https://github.com/ZeroK-RTS Locate] the repository you want to edit and click the "Fork" button on the GitHub website to create your own copy on GitHub
**''' After you finish modifying sources click '''Pull request* in Github for windows and submit your changes for review
+
* Locate your fork and click the "Clone or download -> Open in Desktop" button on the GitHub website to create a local repository on your computer
 +
* Before you start modifying sources:
 +
** Use GitHub Desktop to create a new branch in your repository for the specific changes you want to make; create the new branch from the master branch in the original ZeroK-RTS repository
 +
* After you finish modifying sources:
 +
** Use GitHub Desktop to commit your changes to your local repository
 +
** Use GitHub Desktop to publish or sync your commits to your repository on GitHub
 +
** Submit your changes for review: Use GitHub Desktop or the GitHub website to create a Pull Request from your new branch in your fork (the "head fork") into the master branch in the original ZeroK-RTS repository (the "base fork")
  
 
== Modifying the game ==
 
== Modifying the game ==
<ol>
+
:''For personal modding, see [[Mod Creation]]''
  <li>Locate data folder of your game - in Zero-K lobby settings click open game data folder</li>
+
#Create a folder <code>games/zk.sdd</code> in the Zero-K installation folder.
  <li>Create a folder games/zk.sdd in game data folder</li>
+
#Clone to desktop [https://github.com/ZeroK-RTS/Zero-K Zero-K game] and save it to <code>zk.sdd/</code>. This folder should contain multiple files/folders, such as <code>modinfo.lua</code>.
  <li>Clone to desktop [https://github.com/ZeroK-RTS/Zero-K Zero-K game] and save it to zk.sdd</li>
+
#To test source modifications, you'll need to 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.
  <li>To test source modifications, you'll need to enable developer mode in Chobby. Do this by creating an empty text document "devmode.txt" in the same directory. You may need to restart the lobby.</li>
+
#In the Settings menu a new tab appears: Developer. Edit the Singleplayer setting to be Zero-K Dev.
  <li>In the Settings menu a new tab appears: Developer. Edit the Singleplayer setting to be Zero-K Dev</li>
+
#Your skirmish games should now use your modified local copy of zk.sdd.
  <li>Your skirmish games should now use your modified local copy of zk.sdd</li>
+
 
</ol>
+
== Modifying lobby menu ==
 +
#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>.
 +
#Launch Zero-K.exe with the <tt>dev</tt> arg (i.e. <code>Zero-K.exe dev</code>)
 +
 
 +
== 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 ==  
 
== Modifying infrastructure/tools ==  
<ol>
+
* Install [https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx Visual Studio Community edition]
<li>Install [https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx Visual Studio Community edition]</li>
+
* Install [http://www.microsoft.com/en-us/server-cloud/products/sql-server-editions/sql-server-express.aspx SQL Server express]
<li>Install [http://www.microsoft.com/en-us/server-cloud/products/sql-server-editions/sql-server-express.aspx SQL Server express]</li>
+
* Clone to desktop [https://github.com/ZeroK-RTS/Zero-K-Infrastructure Zero-K infrastructure]
<li>Clone to desktop [https://github.com/ZeroK-RTS/Zero-K-Infrastructure Zero-K infrastructure]</li>
+
* Test by opening Zero-K.sln in Visual Studio
<li>Test by opening Zero-K.sln in Visual Studio</li>
+
 
</ol>
+
=== 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.
 +
 
 +
[[File:zk-database-setup.png]]
  
 
=== Debugging infrastructure ===
 
=== Debugging infrastructure ===
* Right click asp.net -> properties -> web -> check "Specific Page" and leave it blank. Otherwise you get errors when trying to host locally.
 
 
* 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]
 
* 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]
* Note: in order 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.
+
* 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.
 +
** 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> to say something like:<br/><code>Data Source=<hostname (usually your computer name)>\SQLEXPRESS</code>
  
 
== Artwork ==
 
== Artwork ==
See [[Development Artwork]]
+
See [http://zero-k.info/Wiki/Development_Artwork Development Artwork] (outdated)
  
 
== Missions ==
 
== Missions ==
See [[Mission Editor]]
+
=== 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]]
 +
 
 +
=== 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 ==
 
== Engine ==
 +
See [https://springrts.com/wiki/Development:Getting_Started Spring Engine Development]
  
See [https://springrts.com/wiki/Development:Getting_Started Spring Engine Development]
+
[[Category:Development]]

Revision as of 04:07, 25 June 2018

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

Getting sources

  • Get a GitHub account and download GitHub Desktop
  • Locate the repository you want to edit and click the "Fork" button on the GitHub website to create your own copy on GitHub
  • Locate your fork and click the "Clone or download -> Open in Desktop" button on the GitHub website to create a local repository on your computer
  • Before you start modifying sources:
    • Use GitHub Desktop to create a new branch in your repository for the specific changes you want to make; create the new branch from the master branch in the original ZeroK-RTS repository
  • After you finish modifying sources:
    • Use GitHub Desktop to commit your changes to your local repository
    • Use GitHub Desktop to publish or sync your commits to your repository on GitHub
    • Submit your changes for review: Use GitHub Desktop or the GitHub website to create a Pull Request from your new branch in your fork (the "head fork") into the master branch in the original ZeroK-RTS repository (the "base fork")

Modifying the game

For personal modding, see Mod Creation
  1. Create a folder games/zk.sdd in the Zero-K installation folder.
  2. Clone to desktop Zero-K game and save it to zk.sdd/. This folder should contain multiple files/folders, such as modinfo.lua.
  3. To test source modifications, you'll need to 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.
  4. In the Settings menu a new tab appears: Developer. Edit the Singleplayer setting to be Zero-K Dev.
  5. Your skirmish games should now use your modified local copy of zk.sdd.

Modifying lobby menu

  1. Create a folder games/chobby.sdd in the Zero-K installation folder.
  2. Clone to desktop Chobby and save it to chobby.sdd/. This folder should contain multiple files/folders, such as modinfo.lua.
  3. Launch Zero-K.exe with the dev arg (i.e. Zero-K.exe dev)

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

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.

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. Setup
  • To run asp.net:
    • It's required that you install MS SQL Express on your local PC. Get one from 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.
    • 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 to say something like:
      Data Source=<hostname (usually your computer name)>\SQLEXPRESS

Artwork

See Development Artwork (outdated)

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

Unit pages

Part of each unit page is autogenerated by the Unit Guide tool, and uploaded by the Wiki bot.

Run export_unit_templates.sh to generate wiki templates for each unit (see export_unit_templates.lua 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 (zero-k.info/zkmanual/www/unitpics and /icons respectively). Contact Licho or Histidine for login details.

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