Modding Tutorial No. 1: Basics and the Blue Histri

Welcome to the first entry of our new modding blog where we'll be posting a new mod every week along with a step-by-step walkthrough on how you can make a similar mod of your own. If anyone has any suggestions for types of mods you really want to see, or if you feel that any step or part of the process is unclear, feel free to make a post! We understand that mod support has been a bit limited so far, but we hope these posts will help people explore what can be done.

Now, we want to start small to give us some room to shine a spotlight on the basics of mod creation, like what folders to use or how one uploads a mod. To that end, I figure one of the easiest places to start is with changing a faction's colour. It's a simple mod to make that will run through most of the basics that need to be covered, while also being something more than a few people have asked how to do.

## Modding Basics

So how do we go about creating a mod? Well, the first thing we need to do is to create a folder for it. There're a few different places mods can go, but to create a mod you'll want to go to My Documents/Longbow Digital Arts/Hegemony III/Mods. Once there, create a new folder and name it what you like. In our case, it will be named "Blue Histri". Once inside your Mods/Blue Histri folder, you're going to want to create a Resources folder.

Before we go into the Resources folder and start placing the files that make the mod actually function, I'd like to mention the other files that should go into the Blue Histri folder. The first is guicover.png: this is an image file used to showcase your mod in both the in-game DLC and Mods menu (where you can activate or deactivate mods as you wish) and on the Steam Workshop. It is entirely optional, if skipped the mod will simply lack an image. The other file is cover.str. This file contains the strings that show up on the mod in the in-game DLC and Mods menu (the Steam Workshop title and desc come from elsewhere). It too is also entirely optional, but presents a nice opportunity to describe .str files.

## Adding Text (Strings)

.str files are where we store the text (strings) we display to the user. It is entirely possible to edit them in plain text editors, but they are easier to read using a program called StringWrangler, which you can download here. Once you have StringWrangler running, you will see a list of strings; if you opened StringWrangler straight from the .exe, this will start blank. Let's add some strings! To do this, move to Edit at the top and select "Add String". cover.str will need two strings, a title and a description. It will look for one string named `Mods::BlueHistri::TITLE` and one named `Mods::BlueHistri::DESC`. It will always look for strings following the same basic format, the middle section being the same as the folder name with all spaces removed. If we were to name the mod "Aequi Added", we would instead be adding strings `Mods::AequiAdded::TITLE` and `Mods::AequiAdded::DESC`.

After you add a string, it should be selected, which will mean the right side panel of StringWrangler will show up to allow you to edit the string in all defined languages. Note that if you have no languages defined, nothing will show up; to add a language, go to View->Add New Language. If the language you want to add is English, define it as "en". When you have languages defined and a string selected, the right panel will have three rows, with the top two showing the string in as many languages as you're displaying. The top section(s), the source, will show the source code of the string while the middle section(s) preview what the result will look like, useful if you're using formatting commands in the top (which we won't be). By clicking on the top section after creating `Mods::BlueHistri::TITLE`, we can type in "Blue Histri", and then by going to Edit->Add String again we can create `Mods::BlueHistri::DESC`, which we'll fill with "Makes the Histri blue". Then we need to go to File->Save As, navigate to My Documents/Longbow Digital Arts/Hegemony III/Mods/Blue Histri and save it as cover.str. Now, when we mouse over our mod in the DLC and Mods menu, a tooltip box saying "Blue Histri - Makes the Histri blue" will show up.

## Making the Mod

Now that we have our mod folder, let's put actual mod data in it! Our goal here is to edit the colour of a faction, which will involve creating a .xnt entity file and merging its data into an existing one. It doesn't technically matter where entity files are stored, so we'll just create a .xnt file right in Blue Histri/Resources. The filename also doesn't matter; it can even match files from the original game or from other mods without overwriting them. Still, we'll call it bluehistri.xnt. A .xnt file uses XML formatting (though is not a .xml file itself; make sure it has .xnt as its extension) in a single entity or entitygroup block, and it should look something like this:

```
<entity modtechnique="merge" class="faction" type="Histri">
     <guicolour>#0000FF</guicolour>
     <unitcolour>#0000FF</unitcolour>
</entity>

```

As I said, it's all in one entity. If we wanted to edit two entities in the same file, we could create an `<entitygroup/>` block and put multiple `<entity/>s` in. Those of you new to XML should note how every block defined later has its name repeated, but with a slash before it `<example>this</example>`; this will be the case for every XML block with data in it. If an XML block only uses attributes or has no contents at all, it would not be necessary and the formatting would instead be different (we'll get to that later), but if there needs to be data inside the block it is how to tell the program the data is done and we can stop counting it as part of that block.

So what do all those blocks and attributes do? Well, the attributes for the entity tag are "`modtechnique`", "class" and "type". "modtechnique" is used when you want to mod an existing entity: "`merge`" will leave all other data as-is and simply add the new data in. "`replace`" will clear the old data and expect you to declare everything for the new entity; if we switched modtechnique to replace, the game would crash because a lot of parts for a faction definition are missing. class says what type of entity we want to edit, in our case a faction, while type is the unique name for which faction we're editing. Note that this is case-sensitive: if we entered "histri", "HISTRI" or "hIStRI" that would count as an entirely different faction.

Within, guicolour and unitcolour (note that we use the Canadian spelling) blocks say what the Histri's colour should be for the map or unit tags and on its unit models respectively. As a faction can only have one guicolour and unitcolour defined, "merge" will override the pre-existing values; if it were something factions could have more than one of, for example shields or bonuses, the old bonuses would still be there with the new ones simply added on top. The colours are given in standard hexadecimal format, where #000000 is zero red, green and blue and #FFFFFF is 256 red, green and blue. Purest blue would be #0000FF. I went with #5398d9 instead, to better match the other changes I made to the Histri.

```
<entity modtechnique="merge" class="faction" type="Histri">
     <guicolour>#5398d9</guicolour>
     <unitcolour>#5398d9</unitcolour>
     <flag atlas="FILE:" sprite="Resources/bluehistriflag.png"/>
     <logo atlas="FILE:" sprite="Resources/bluehistrilogo.png"/>
</entity>

```

Neither guicolour nor unitcolour modify the colours on a faction's flag or logo: those colours are baked into the textures themself. Therefore unless we want the Histri logo and flag to stay yellow, we will need to make the entity point at different textures. The original files can be found as part of .dds files in the base game's Resources/Images/Generated folder, in factions.dds or Flags.dds. They use our game's atlas system, which puts multiple textures into one image for performance reasons.

However, we don't want it to keep pointing at the atlas. So, I separated the histri's logo from the .dds and changed its hue. How to do this is a matter of using a tool like Photoshop or GIMP and is beyond the scope of this tutorial. It does not need to follow the same method I did; you can even use Paint to create your own .png logo if you like. After creating bluehistriflag.png and bluehistrilogo.png, I needed to change the entity to point at those files instead of at the atlas.

An atlas texture definition is an XML block with two attributes but usually no data. While `<flag atlas="FILE:" sprite="Resources/bluehistriflag.png"></flag>` is entirely valid, if you wouldn't have anything between the tags you can close the block in the same brackets you define it by ending it with a slash as I did. The two attributes needed in one are "atlas", and "sprite"; however, in almost all modding cases, you won't actually be using an atlas and want to define the atlas as "FILE:" while giving a file path in the sprite attribute.

## Sharing Your Mod

That's everything we need for a faction-recolour mod. So how do we go about uploading it to the workshop? We need to open the console with the `F2` button to do that. Then in the input box provided, type in `workshopupload("Blue Histri", "Blue Histri", "A simple mod to change the Histri from yellow to blue.")`, and hit enter when you want to upload (and only then; pressing it earlier will send the command mid-type). What does each part of that do? The first "Blue Histri" is the name of the folder you created in the Mods folder. Be sure to get it right, if there are any typoes the game will not be able to find your mod to upload. The other two are only needed the first time and can be skipped if you need to upload any updates to your mod. The second part is the title of the mod on the workshop, and the third is a description of the mod. These can both be edited in future uploads or through Steam's workshop interface after completion. It is probably actually better to save the description for editing through Steam's interface, as you have more room to type and will be able to hit enter without uploading the mod.

If you've done everything correctly, you'll have a fully-functional mod on the workshop! Mods that were just uploaded will default to be hidden; you can only set them to be visible to everyone else through Steam's workshop interface. You'll be able to navigate to your mod through your Steam Community profile, and when you're at your mod you will find the visibility settings in the Owner Controls portion at the right of the screen, as well as other tools you can use to add more images or fine-tweak various small parts of your mod.

## Next Week

Anyway, that's our mod for this week, I hope this has mostly been clear and easy to follow, but if you have any questions I'd be happy to answer them! We'll be going into another type of mod next week (likely stances or upgrades, although we'll also take suggestions), but in the meantime there is a lot of raw information on modding at the wiki if you're feeling adventurous.