Skip to content

Developer Guide

Jump to bottom
dzfischer edited this page Aug 20, 2022 · 18 revisions

Setup

There is a video here that shows how to get setup to develop this mod using Github Desktop.

However I would suggest if you are doing anything non-trivial you should consider using GitKraken instead. It is almost as easy to install and setup, but provides more powerful functionality than GitHub Desktop. Once you have installed GitKraken you should make sure to change your default Pull mode to Pull (rebase) so we can keep our master branch history linear.

Steps:

  1. Create a github account.
  2. If you are a core dev then request access to the main repository via forums or discord, otherwise create your own fork to work in.
  3. Install GitKraken.
  4. Make sure you have git tools installed if not already: Installing Git
  5. Clone the main repo (if you are a core dev) or your fork, somewhere OTHER than the Mods folder. e.g. My Documents or your Desktop.
  6. Set Pull mode to Pull (rebase).
  7. Run DevSetup.bat in the repository root and follow the instructions (really just read the blurbs if you want to know what it is doing, there isn't anything you need to do except press a key to step through the process). If you run into problems here please ask on the forums or discord for support. You might need to restart after running this.
  8. Done!

What is DevSetup.bat doing?

  1. Install git command line tools if they are not already installed, importantly making sure to add them to the PATH. If you already have them installed but NOT in the PATH then this will cause problems. Please either add the git bin folder to the PATH, or uninstall them and let DevSetup.bat install them how it likes.
  2. Link directories in your git directory to your Mods directory so that the game can find the files it needs to run the mod in the correct location. These links mean that changes you do in the git directory will be reflected in the game without you needing to copy anything. The game sees the same directory you do.
  3. Make the initial build of the DLL. The default build configuration is Release. This will take a couple of minutes to build the first time. If you want to use a different configuration then you can run one of the MakeDLL*.bat scripts in the Tools directory, after you finished running DevSetup.bat. FinalRelease is the fastest to play with, but takes the longest to build (15 minutes on a fast PC), Assert is optimized but has asserts enabled, and as such is good for testing Python and XML changes.
  4. Automatically set Visual Studio debugging settings based on your Mods directory location.

After Setup

After you have run DevSetup.bat once you do not need to run it (or any other update scripts) again. Compiling of the DLL and packing of the FPKs is automated by tools that are run when the game is started.

FPKLive

This program keeps .FPK files up to date with content added to the UnpackedArt folder. It is run automatically when the game starts up (when our DLL is attached). The first time it runs it will take a while (30s to a minute), as it is making the initial FPK set. On consecutive runs it is a lot faster, as it uses git to determine what files have changed since the initial FPK set was created, and makes a patch containing only those files. This tool means that new art can be placed into the UnpackedArt folder, and nobody needs to worry about manually editing FPK files.

Autobuild

When the DLL is first loaded by the game it will check if it is up to date (i.e. incorporates the latest code changes). If it is NOT up to date then the DLL is built using the latest changes, and the game restarts automatically and loads the newly updated DLL. This means that you cannot accidentally run the game with an out of date DLL, and you do not need to worry about building it yourself after pulling from github.

Development

Conventions

  • Tabs not spaces for all source files and XML

  • Auto CRLF (this is set via .gitattributes file already)

  • Pull (rebase) when working in master

  • Bigger or controversial changes done in branches, and integrated via Pull Requests to master

  • Constrain pull requests to individual changes where possible - Simple changes are more easily integrated and tested. Pull requests with many changes, where there are issues with one change in particular, will delay the integration of all changes. Pull requests that change or add large amounts of functionality are harder to test and will take much longer to integrate, increasing the likelihood of conflicts.

  • Avoid refactoring and formatting changes mixed with functional changes - Behavior altering changes (fixes, enhancements and new features) mixed with style changes or refactoring cleanup make changes more difficult to integrate. Please consider splitting these changes so they can more easily be individually integrated.

  • Branch names use lowercase-hyphen-style

  • Commits use conventional commit style for commits players will be interested in, and plain style for other commits.
    This includes changes that they can notice in game, and excludes refactoring of our code, new tools, and other such invisible changes.

    type(scope): message

    fix, feat, balance, perf are the types that are supported. Others types will be ignored, if none of these fit exactly then use feat.
    scope can be whatever makes sense.

    For example:

    • fix(Animation): air bomb animation working again
    • feat(Siege): improved siege mechanics
    • balance(Buildings): pharmacy doesn't give gold any more

    Commits for players should be described in a way most C2C players will understand:

    • They should refer to general game concepts, mod concepts, units, civics etc.,
    • They should NOT refer to code, files, etc.
    • They can refer to the related github issue, or link to forum posts where it makes sense.

    Commits not for players should just use plain commit style (there are many guides).

DLL

Open the C2C (VS2019).sln file in the Sources directory and start hacking! Debugging settings should have been configured automatically by DevSetup.bat, so you can just select a build configuration and start debugging.

See Debugging the Disassembly for a guide on debugging in the EXE.

Short guide to turn time profiling.

Logging

  • In dll, it is recommended to use logBBAI, example: logBBAI("City %S has threat level %d", getName().GetCString(), iOurThreat);
  • For temp examination, logMsg is useful for directing output to a specific file, example: logging::logMsg("Test.log", "Culture level %d", iLevel);

Python

Just start editing.

BTS Python API.

Short guide to python performance testing.

Art

All art except .bik files goes into the the UnpackedArt\art directory. From here it is automatically packed by FPKLive as described above.

XML

Just start editing.

References

Modders documentation on the forum: https://forums.civfanatics.com/threads/modders-documentation.441325/

Clone this wiki locally