Tutorial: Adding a new faction symbol

[alpaca]

It is recommended to use the files strategy.sd.xml, shared.sd.xml and battle.sd.xml that can be found in the Retrofit Mod for Kingdoms (but they also work in M2TW). To use them, simply place them alongside a copy of the sd files in your data/ui folder, then edit them to your liking and the game will inject the information into the sd.
Their structure is somewhat similar to that of the sd converter descriptor files so you can probably still gather some valid information from this tutorial.

This tutorial will teach you how to add a new faction icon to the game. It's designed to go together with my .sd converter, and you'll need that to follow this tutorial.

Prerequisites

- Download the .sd converter and follow the instructions under "Installation" in the readme:
https://forums.totalwar.org/vb/showthread.php?t=81320
- A basic grasp about editing image files (including transparency information in the alpha layer)


1. Creating the Icons

Well the first step is obviously to create your new icons. So, search for a nice image on the internet or create one yourself.
When you did that, open up modpage.tga in your .sd converter folder. It should look like this:

This shows the Yorkshire Rose in large and small that I'll use as an example in this tutorial.

Now, clear up the modpage (don't forget the alpha channel) by filling it with black, and copy your image to the top left corner, and a smaller version next to that.
Now we still need to supply alpha information, because with a black alpha channel the image won't show. So select the alpha channel (make the RGB channels invisible) and edit it so that it is white where your icon is and black everywhere else.

You can also add shadows, like I did in the lower-left portion of the Rose:

Well that's all we need to do here. Save the image - and make sure to uncheck "Compress (RLE)" when you save the .tga, like this (and of course save the alpha channel, so 32bit):

2. The Descriptors

What we do now is to create the input files to tell the converter what we want to go into the .sd files.
I included two files, called modpage_strat.txt and modpage_shared.txt in the sd converter release. These are basically all you need to start off with your first icon and I'll explain them now:

modpage_strat.txt

strategy.sd

tga=modpage.tga

entry=FACTION_LOGO_YORKSHIRE
top=0
left=0
bottom=114
right=119

Each descriptor file has exactly one associated .sd file. You'll have to specify the name of that file in the first line of the descriptor (in this case strategy.sd).
Then follow entries for a number of pages (in this case only 1, our modpage) - they simply consist of a tga=name statement

Each page has a number of UI entries associated with it. These consist of an initial entry=UI_TAG statement, followed by the coordinates of your image (x values of top and left, and y values of bottom and right edges, as shown in Photoshop)

Please edit FACTION_LOGO_YORKSHIRE to whichever name you want for your faction logo (such as FISHPANTS for example)


modpage_shared.txt

shared.sd

tga=modpage.tga

entry=SMALL_FACTION_LOGO_YORKSHIRE
left=120
top=0
bottom=+38
right=+40

This looks very much like the above, but contains an interesting additional option: If you use right=+x, this is treated as relative to the left border, so +38 in this case doesn't mean that the right edge is at the coordinate 38, but that our image is 38 pixels wide. The same goes for bottom=+y and height.
Also note that this specifies shared.sd as the associated .sd file

Well, we're already finished here, so let's move on to the actual generation of the .sd files.


3. Compiling the .sd files

To generate strategy.sd and shared.sd, simply run modpage.bat which automates that process for the modpage files.
It looks like this:

sd_converter_1_0.py -c strategy_sd_desc.txt modpage_strat.txt shared_sd_desc.txt modpage_shared.txt
PAUSE

So, only really one command in there. The "-c" option simply tells the converter that it should compile, followed by a list of descriptor files separated by spaces.
It's important to note that, in addition to our modpage descriptor files, the converter will also have to use the vanilla descriptors, or all the buttons the game uses will be lost (I created the vanilla descriptor files with the decompile option explained below).


4. Updating descr_sm_factions.txt

To marvel at your symbol in the game, you'll have to edit descr_sm_factions.txt. Link your new symbols like this:

logo_index					FACTION_LOGO_YORKSHIRE
small_logo_index			SMALL_FACTION_LOGO_YORKSHIRE

Well that's it. Copy strategy.sd and shared.sd to your data/ui directory, modpage.tga to your data/ui/southern_european/interface directory and descr_sm_factions.txt to your data directory.
If you want to work in a mod folder, you will also have to copy a version of strategy.sd and shared.sd into the vanilla data directory (M2/data/ui) - this can also be the unpacked vanilla version, or probably even an empty file.
Then start a campaign and you should be able to see your new faction icon in all its glory:

5. Advanced options

Well I wouldn't be me if I hadn't included a few more options in the .sd converter than just the above.
First of all, have a look at the files I supplied for the vanilla .sd information (strategy_sd_desc.txt, etc.)
These contain full information about the original sd files, so be careful when editing them.
Anyways, you will see that these files use more commands than just those mentioned above. Click on "Show" to see a list of available descriptor commands.

tga=stratpage_01.tga
As mentioned above, this tells the converter which page it should open. You will notice that strategy_sd_desc.txt for example contains 5 files (the 4 stratpages and editor_strat01.tga).

width=512, height=512
If you want you can override the width and height information which is normally read from the mouse-over image. However I wouldn't recommend this and these options are more of an artifact from a previous version when they weren't automatically read.

mouseover=stratpage_01.tga_mouseover.tga
Now this command is one of the most interesting. It allows you to specify a different mouse-over image for this page (although it still has to be a tga and mouse-over info will still have to be stored in the alpha layer). This can be useful if you use a lot of shadows, or don't want some parts of your image to be clickable, or want transparent parts clickable. I included the original mouse-over information from the .sd files because automatically generating it yielded fairly bad results.
An example usage of this would be a complex image where you have a lot of transparent holes that you want nonetheless to be clickable.

entry=BUTTON_OUTER_RING_SMALL
As above, this is the name of a UI entry. A lot of these aren't actually used, but be careful when playing around with this.

topleft=432,323, bottomright=468,362
You can use these instead of the left, top, right and bottom keywords but they are mainly artifacts from an earlier program version.

page=stratpage_01.tga
As each UI entry explicitly has an associated page in the .sd file, you can also set this inside the descriptor if you want.
This can be useful if you want a specific ordering for your descriptor file.

alpha=1
This enables transparency for this entry. If you use 0, you can switch it off.

mystery=0 and coord=0,0
These are some bytes we couldn't yet really fathom the use for, but I presume they are dead weight and not used.

The converter also comes with a decompile option that allows you to dump the information stored in a .sd file into a descriptor (and optionally generate a mouse-over tga image). You can use it with the command-line option "-d":

sd_converter_1_0.py -d sourceSD target [True/False]

This tells the converter to use sourceSD as a source, generate Target as the target descriptor and if you set the last argument to True, you will get sourceSD_mouseover.tga which stores mouse-over information.