These are the balancing scripts for Empires (available for free on Steam).

Empires Scripts

These are the balancing scripts for Empires (available for free on Steam). These instructions will help you view, test and contribute changes (between released versions, the current beta, or work in progress). You will need to install Empires and in order to test out any changes.

Get git gui

The gitlab website has some built-in functionality for viewing this repository, but you gain a lot of freedom by checking out the repository yourself. I will be using GitExtensions, but I will add the git commands used; you can open a terminal (e.g. GitBash or linux native terminal) to achieve the exact same thing, or use a different git GUI such as Tower, GitGUI, GitEye, gitk, or SourceTree. Proceed once you have installed a git GUI.

In GitExtensions, choose Start > Clone Repository. The repository to clone is in a text field on the main gitlab page for the project, in this case:

  • git@gitlab.com:empiresmod/empires_scripts.git

check out to a new directory and open your Git GUI.

screenshot of GitExtensions, clean git status on develop
$ git status
On branch develop
Your branch is up-to-date with 'origin/develop'.
nothing to commit, working directory clean

Fetch often

You should fetch regularly by pressing Cntrl-Down in GitExtensions, and selecting fetch only as your default action (or executing git fetch in the terminal). This downloads changes made to remote branches (shown in green) from the remote repository. Your own, local branches are shown in red. You can switch to a different commit by either resetting your current branch to that commit (right-click -> Reset) or creating a new branch at that commit.

Note that from GitExtensions, you can open the terminal by clicking this black button in the top bar.

GitExtensions terminal button

View changes

When you click any commit in the tree, the changes will be shown for that commit. However, GitExtensions allows you to also view multiple commits' changes by first clicking e.g. the 2.6.9 tagged commit, 3c55cc89, and then holding cntrl while clicking a second commit, such as the one tagged 2.7.0. You can also filter changes (by file, for instance) with Cntrl-F. The git commandline gives infinite options for recombination, a small subset of those will have buttons assigned in your git GUI of choice.

Make changes

As you modify script files, git will track the difference in these files from the commit you are pointing to. So, when you start working on something, just always make sure you have a clean git status to begin with, and then just hack about carelessly, as your git status will tell you exactly what changed, and allows you to reset on a file or line-by-line basis. (see Reviewing the diff below)

When you want to test your changes, copy-paste the contents of your scripts repository into your steam Empires install scripts folder. (e.g. C:\Program Files (x86)\Steam\steamapps\common\Empires\empires\scripts) If you exclude the .git folder, it will be twice as fast. If you include the .git folder, you can start using the more advanced workflow explained in the last section, that does not require any more copy-pasting.

Start a feature

In 2.6.9, every commander worth his res goes for HEMG/DUMG and some sort of armour to pump out APCs. Sgt. Security suggested lowering their max weight and increasing the weight of those weapons to remedy this issue. Using this suggestion, I'll walk you through how to view and commit script changes.

Having confirmed we are on develop, which is up to date with origin/develop, either by seeing it or by entering git status in the terminal, we can create a branch from origin/develop, let's call it feature/apc_nerf Depending on your changes, the name of the branch should be one of:

  • bugfix/name
  • feature/name

Google "git flow" to know more about what each of these are for; the point of this naming convention is that we all know more or less what the intent is of each branch (and where it should be merged into when accepted) just from the name.

do "git branch feature/apc_nerf" or, in GitExtensions, press Cntrl-B and enter that as the branch name, and press "Create branch".

screenshot of GitExtensions, starting feature/apc_nerf branch

Reviewing the diff

Now we can make the first changes, and review the diff, either with "git status" or by opening the commit window in GitExtensions with Alt-C (or press the button "Commit").

screenshot of GitExtensions, viewing diff
$ git status
On branch feature/apc_nerf
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   vehicle_imp_apc.txt
        modified:   vehicle_nf_apc.txt

no changes added to commit (use "git add" and/or "git commit -a")

$ git diff vehicle_imp_apc.txt
diff --git a/vehicle_imp_apc.txt b/vehicle_imp_apc.txt
index 2fdba73..366ab4b 100644
--- a/vehicle_imp_apc.txt
+++ b/vehicle_imp_apc.txt
@@ -35,7 +35,7 @@ Vehicle_APC
                "Armor Angle 4"         "295"

                "Type"                  "9"             //which vehicle type this is 0=jeep, 1=apc, 2=tank, 3=artillery, 4=anti-air
-               "Max Weight"            "854"           //was 600
+               "Max Weight"            "809"           //was 600^M
                "Base Weight"           "614"
                "Cost"                  "100"           //cost of just the chassis in resources
                "Friendly Recycling Percentage" "0.25"  //The percentage of the cost of a friendly vehicle that is reimbursed when recycling a dead vehicle carcass.

Note the ^M we've added according to git diff; this is a windows line ending (CRLF). I know that when I installed GitExtensions, I chose the option to always replace these with unix line endings (LF) upon committing, so this won't be a problem, but if you chose the wrong option, the whole file will show up in the diff, instead of just the lines changed, in which case, you should run this in the terminal:

$ git config --global core.autocrlf true

When we're happy with this change (and also with the diff on vehicle_nf_apc.txt), we stage it, enter a commit message and commit message. On commandline, that would be:

$ git stage vehicle_imp_apc.txt vehicle_nf_apc.txt
$ git commit -m "Lowered max weight of NF&BE APCs by 45 (approx. 5%)"

In GitExtensions, I would select both lines with shift-down arrow, press "S" to stage, cntrl-4 to switch focus to the commit message window, type the message and press Alt-C.

Staged changes

After committing, your git status will be on the newly made commit. This commit is not yet pushed to the gitlab repository (origin), so no-one else can see these changes.

Screenshot of feature/apc branch after committing
$ git status
On branch feature/apc_nerf
Your branch is ahead of 'origin/feature/apc_nerf' by 1 commit.
  (use "git push" to publish your local commits)
nothing to commit, working directory clean

Pushing changes

To push your feature or bugfix, you will need a remote repository which you have write access to; Fork the Empires scripts repository to your own account to obtain a copy where you and you alone have write access - this means nobody can mess with your scripts unless you give them permission.

Fork button in gitlab

You will need to add this new repository as a remote to your local repository. Let's call it "fork", so we have our own fork and we have the Empires dev team's origin. In GitExtensions, choose Repository > Remote repositories and click new. Fill in "fork" as the name and enter your own copied project's git uri (at the top of your gitlab project page in a text field).

Adding remote

Once you push to fork with git push fork feature/apc_nerf (or cntrl-up arrow in most git GUI tools), the feature can be reviewed by others, but you can no longer modify your commits (messages, the order of the commits, or the changes included in each commit), so you are advised to first make your feature, test it, review each commit yourself, and only when you're sure it's correct, push the feature.

In this case, we're going to make another change that we consider tightly coupled with the max weight change; we're also going to increase the weight of vehicle MGs to 40 weight. If the change is not to be considered related, you should make a new feature/otherchange branch based on origin/develop and restart the process.

Following the same process above, I've made and committed changes. After reviewing them, I'm ready to push them with Cntrl-up arrow.

$ git push origin feature/apc_nerf

Screenshot after pushing to remote

Next, submit a pull request so that we can see and merge your changes into the Empires scripts repository. This creates a central place where comments can be placed on (parts of) the diff and you can see who has reviewed the changes. Gitlab does not currently seem to support pull requests, so just make a forum post where you link us to your repository and mention the branchname we should pull.

Your destination folder can be either:

  • Any new directory
  • The Empires steam install scripts folder (e.g. C:\Program Files (x86)\Steam\steamapps\common\Empires\empires\scripts)

Empires steam install scripts repo

This last step is optional and requires good understanding of git. You can easily upgrade to this later once you understand how git tracks a working directory.

You can clone the repository directly into the steam Empires install folder, (e.g. C:\Program Files (x86)\Steam\steamapps\common\Empires\empires\scripts) or, if you already have a local repository, just copy paste the .git folder into there.

If you install to the steam install folder, then updating Empires through steam, or switching branches, changes your working directory. This is more difficult, especially if you are new to git, but can give you greater flexibility, as you can immediately launch the game and start a new server from your own scripts branch, and gives you greater power as you can see exactly what script changes are in a steam release.

For an example of what happens when Empires updates, switch to the beta branch (Right-click Empires > Properties > Betas > enter the password "testingtime" and select "beta" from the dropdown) and update. If you were previously on master with a clean git status, you will now have some unstaged changes (36 files in my case). You should update your git index to point at the new commit. In git extensions, you can right click a commit (for beta we will select origin/develop) and select "Reset". A hard reset also resets your working directory, while a mixed reset will leave your working directory intact. Select "mixed" (or do git reset origin/develop --mixed on the commandline); you should now have a clean git status, which means that the commit you selected is exactly equal to the active steam branch.