102 — Blueprint merge

A working example of the tangible results of this tutorial can be found here.

The very simplest form of functional mod is the blueprint merge.

The primary purpose of the blueprint merge is to change selected values inside of unit blueprints. Generally for the purpose of balance changes and other tweaks.

These are done in .bp files. The game will actively load any .bp from inside your mod regardless of what it's called and where in the mod it is placed. Any directory structure housing them basically exists only for your personal organisational needs.

Anatomy of a .bp file and blueprints

As with .lua files, .bp files are plaintext files. A unit blueprint consists of the function UnitBlueprint called with a Lua table; the specification of that blueprint. Lua tables consist of curly brackets { } with entries separated by commas ,. The last entry can optionally have a comma after it to make rearranging lines easier and less-missing-comma-error prone.

If an entry doesn't contain an equals sign = defining the separation between 'key' and 'value' of that entry or cell, then the key is implicitly defined as a number; sequentially continuing from the previous number starting from 1. This differentiation is what separates any old table from an array; an array has sequential uninterrupted numbers for keys, that are often implicit rather than explicitly written, starting from 1 not 0

The values of the cells can be a number, simple maths equation, string, Boolean, another fully nested table, or the Sound function called with a table. Any other values will likely cause an error.

The most common reason for a .bp to not load is an error with commas, or an error with not properly nested tables. The game log will issue a warning saying that it failed to load the bp in this eventuality.

Blueprints and the blueprint ID

A .bp file can contain any number of blueprints as long as those blueprints define BlueprintId. The blueprint ID should always be lowercase. If the blueprint doesn't define BlueprintId, then it will derive the ID from the file name. If the filename contains the suffix _unit then the ID will be the part prior to that, converted to lowercase. If filename doesn't contain _unit then the entire file path, converted to lowercase, will be used as the ID. This is something to be avoided.

The merge

A blueprint merge is defined by setting Merge = true. This will cause the game to load the contents of the blueprint as an overwrite for whatever the blueprint ID defines. This means you can change a select few stats without having to include the whole of the original.

Creating a merge

Finding the target original

First thing you're going to want to do is locate the original blueprint. Be mindful of where you plan to use the mod when doing this. It shouldn't make too much difference since you're only going to be including changed values in your merge, but different environments have different balance, and sometimes some other crucial changes, but it makes it easier to compare changes if you are working from the correct version. For FAF and LOUD these files can be located in their respective Github pages. For all other versions of the game, these files can be located inside the gamedata folder, within the games directory, inside of units.scd. .scd is just a renamed .zip file, so either treat it as such, or rename a copy to that.

Assembling your merge

Look down the original for the values you want to change, and take note of what tables they are in. If you are using Atom or some other vaguely competent editor you should be able to collapse tables with a click when you see they contain nothing you're interested in, or you've dealt with them.

In your merge you will need to mirror the table structure for the values you wish to change. For example, if you wish to change a units max shield health, that will need to be in a Shield table, in the Defense table. If you have multiple keys with the same name within a given table, the later will replace the former, so it's best to avoid that.

One thing to be wary of is things like the Categories array; editing these can be problematic from a merge, and if you wish to do so in the 'best practice' way, that is covered in 103 § Closing with categories, so wait until you get there, or just replace the whole array with your changed version.

Aeon_Merge.bp

The following is an example taken from BrewLAN:

UnitBlueprint {
    Merge = true,
    BlueprintId = "xab3301", --T3 Quantum Optics
    Footprint = {
        SizeX = 3,
        SizeZ = 3,
    },
    Physics = {
        SkirtOffsetX = -2.5,
        SkirtOffsetZ = -2.5,
        SkirtSizeX = 8,
        SkirtSizeZ = 8,
    },
}

UnitBlueprint {
    Merge = true,
    BlueprintId = "ual0303", --Harbinger
    Defense = {
        Health = 2125,
        MaxHealth = 2125,
        Shield = {
            ShieldMaxHealth = 1200,
        },
    },
    Economy = {
        BuildCostEnergy = 5400,
        BuildCostMass = 480,
        BuildTime = 2400,
    },
    Physics = {
        MaxAcceleration = 4,
        MaxBrake = 4,
        MaxSpeed = 4,
    },
    Weapon = {
        [1] = {
            Damage = 150,
            MaxRadius = 20,
        },
    },
}