| Latest revision |
Your text |
| 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. [//c2.com/cgi/wiki?RulesOfOptimization Remember the rules of optimization]: | + | ** Optimize code but not to the point of unreadability. [http://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/ TortoiseGit]. The game sources are used as an example, however this method applies to other subprojects as well.
| + | * Get a [https://github.com/ GitHub] account and download [https://desktop.github.com/ GitHub Desktop] |
| − | * Install [https://tortoisegit.org/download/ TortoiseGit].
| + | * [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 |
| − | * Create a [https://github.com/ GitHub] account.
| + | * 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 |
| − | [[File:ForkZK.jpg]]
| + | * Before you start modifying sources: |
| − | * Log in to GitHub and [https://github.com/ZeroK-RTS Locate] the repository you want to edit. | + | ** 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 |
| − | * Click the "Fork" button on the GitHub website to create your own copy on GitHub.
| + | * After you finish modifying sources: |
| − | [[File:ZKCloneCopy.png|1103px]]
| + | ** Use GitHub Desktop to commit your changes to your local repository |
| − | * Locate your fork on GitHub and click "Code". | + | ** Use GitHub Desktop to publish or sync your commits to your repository on GitHub |
| − | * Copy the web URL to your clipboard.
| + | ** 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") |
| − | [[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 == | | == 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 [//notepad-plus-plus.org/download/ Notepad++].
| + | #Create a folder <code>games/zk.sdd</code> in the Zero-K installation folder. |
| − | | + | #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>. |
| − | To test your changes: | + | #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. |
| − | * (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.)
| + | #In the Settings menu a new tab appears: Developer. Edit the Singleplayer setting to be Zero-K Dev. |
| − | * Create an empty text file named 'devmode.txt' in the same directory as Zero-K.exe.
| + | #Your skirmish games should now use your modified local copy of zk.sdd. |
| − | * 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:
| + | == Modifying lobby menu == |
| − | * 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.
| + | #Create a folder <code>games/chobby.sdd</code> in the Zero-K installation folder. |
| − | * Launch Zero-K and create a passworded multiplayer lobby.
| + | #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>. |
| − | * Set the room type to Custom.
| + | #Launch Zero-K.exe with the <tt>dev</tt> arg (i.e. <code>Zero-K.exe dev</code>) |
| − | * 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 == | | == Zero-K.exe launch flags == |
| Line 133: |
Line 59: |
| | == 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 the developer or express edition, whichever works best for [https://www.microsoft.com/en-us/sql-server/sql-server-downloads SQL Server express] | + | * Install [http://www.microsoft.com/en-us/server-cloud/products/sql-server-editions/sql-server-express.aspx 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 (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. | + | 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. |
| − | | |
| − | (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 148: |
Line 70: |
| | === 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. |
| − | *[[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. | + | * 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: | | * To run asp.net: |
| − | ** It's required that you install MS SQL Server on your local PC. | + | ** 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. |
| − | *** 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).
| + | ** Right click asp.net -> properties -> web -> check "Specific Page" and leave it blank. Otherwise you get errors when trying to host locally. |
| − | *** 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]]
| + | ** 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> |
| − | ** 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 202: |
Line 101: |
| | == 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 === |
| Line 223: |
Line 119: |
| | == 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]] |
