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:
http://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.

[Lusted]

Just what i was looking for alpaca, this will be a great help.

[Lusted]

Just got everything ingame and it worked like a charm, though it looks like the 2 .sd files might need to be in the main ui folder and not a mod switch ui folder. Hopefully this will be fixed with the fix of file paths in 1.2.

[wilddog]

Alpaca
Excellent and well done. I'll try and give this a go at the weekend.

[alpaca]

Just got everything ingame and it worked like a charm, though it looks like the 2 .sd files might need to be in the main ui folder and not a mod switch ui folder. Hopefully this will be fixed with the fix of file paths in 1.2.

A mod folder works fine for me. I made the screen with a mod-folder version.
It might be that you need a version of these files in the normal data folder, too, though - you could try copying the vanilla files into it and then try it with a mod folder. That's pretty much my setup (I have the unpacked files in the vanilla data folder)

[Lusted]

Yeah it appears you do need a version of these files in the vanilla folder as well as the mod folder, just in the mod folder doesn't work.

[Lord Condormanius]

Whenever I try to convert the file, I get this error:

"struct.error: unpack requires a string argument of length 1"

any ideas?

LC

[alpaca]

Whenever I try to convert the file, I get this error:

"struct.error: unpack requires a string argument of length 1"

any ideas?

LC

Please quote the full program output (including the Reading ... and Writing ... statements), otherwise I can't really look into it. Sounds like a file ended preliminary.

@Lusted: Ok, I'll put it into the tutorial.

[Lord Condormanius]

Please quote the full program output (including the Reading ... and Writing ... statements), otherwise I can't really look into it. Sounds like a file ended preliminary.

Ok... here is the full output

Reading strategy_sd_desc.txt
Reading modpage_strat.txt
Traceback <most recent call last>:
  File "C:\Documents and  Settings\Administrator\Desktop\.sd_Converter\sd_converter_1_0.py", line 752, in <module>
    sdf.compile<sdtopaths[sdf]>
  File "C:\Documents and  Settings\Administrator\Desktop\.sd_Converter\sd_converter_1_0.py", line 685, in compile
    if not page.isComplete<> or not ent.isComplete <>:
  File "C:\Documents and  Settings\Administrator\Desktop\.sd_Converter\sd_converter_1_0.py", line 216, in isComplete
    self.readMouseoverTGA<self.file>
  File "C:\Documents and  Settings\Administrator\Desktop\.sd_Converter\sd_converter_1_0.py", line 203, in readMouseoverTGA
    a = readByte<f>
File "C:\Documents and  Settings\Administrator\Desktop\.sd_Converter\sd_converter_1_0.py", line 13, in readByte
    return struct.unpack<'B', fhandle.read<1>>[0]
File "C\Python25\lib\struct.py", line 87, in unpack
    return o.unpack<s>
struct.error: unpack requires a string argument of length 1

Any help would be great!

LC

[alpaca]

Ok... here is the full output

Any help would be great!

LC

Hmm strange, could you upload your modpage.tga and modpage_strat.txt somewhere (or attach them here) so that I can try to reproduce this?

[Lord Condormanius]

Hmm strange, could you upload your modpage.tga and modpage_strat.txt somewhere (or attach them here) so that I can try to reproduce this?

I posted them at the original thread at TW Center http://www.twcenter.net/forums/showp...12&postcount=3.

For some reason, they won't let me post attachments at the Guild.

LC

[alpaca]

I posted them at the original thread at TW Center http://www.twcenter.net/forums/showp...12&postcount=3.

For some reason, they won't let me post attachments at the Guild.

LC

Ah. Make sure that when saving the tga you uncheck "Compress (RLE)" in the dialog where you set the bit-rate.

[Lord Condormanius]

Ah. Make sure that when saving the tga you uncheck "Compress (RLE)" in the dialog where you set the bit-rate.

Thanks, I'll try it out.

LC

[Lord Condormanius]

Ah. Make sure that when saving the tga you uncheck "Compress (RLE)" in the dialog where you set the bit-rate.

Ok...I got the symbols onto the map. However, only half of the large symbol shows up on the campaign map.



Any thoughts?

LC

By the way, should I be copying over the original shared.sd adn strategy.sd files in the ui folder? I think so.

[alpaca]

Ok...I got the symbols onto the map. However, only half of the large symbol shows up on the campaign map.

Any thoughts?

LC

By the way, should I be copying over the original shared.sd adn strategy.sd files in the ui folder? I think so.

You need to set the width of your image in the descriptor file. And you don't need the original files, those generated by the tool should be fine.

[wilddog]

Alpaca
Tool works great so well done. I've only tried with the larger faction logo so far.
Now need to edit the button effect for selecting the logo when in the campaign.

Curious do you recommend adding the new selection button shape to the new TGA files and the new txt files and removing the entries from the decompiled text files..... or just amending the shape in the original TGA's? The first option would preserve the original TGA's leaving only the 2 SD files to be replaced and the new TGA

[Lord Condormanius]

You need to set the width of your image in the descriptor file. And you don't need the original files, those generated by the tool should be fine.

Perfect. Thanks.

LC

[alpaca]

Alpaca
Tool works great so well done. I've only tried with the larger faction logo so far.
Now need to edit the button effect for selecting the logo when in the campaign.

Curious do you recommend adding the new selection button shape to the new TGA files and the new txt files and removing the entries from the decompiled text files..... or just amending the shape in the original TGA's? The first option would preserve the original TGA's leaving only the 2 SD files to be replaced and the new TGA

Well, since it works fine, I would recommend not messing with the original files and adding your own stuff in a new TGA (or multiple if you want). If you want to change stuff like the original buttons, I'd probably do that in the original files unless it's something that doesn't fit in there, in which case I'd just use one of the new files.

[repman]

Even with the leaked patch 1.2 the 2 .sd files need to be in the main ui folder and not in the mod switch ui folder as some other files....grrr... so much for mod isolation

repman

[wilddog]

Even with the leaked patch 1.2 the 2 .sd files need to be in the main ui folder and not in the mod switch ui folder as some other files....grrr... so much for mod isolation

At least its in line with the other symbols etc which are in models_strat as they aren't isolated either.

[alpaca]

Even with the leaked patch 1.2 the 2 .sd files need to be in the main ui folder and not in the mod switch ui folder as some other files....grrr... so much for mod isolation

repman

Actually you only have to have SOME version of that file in there. I have the vanilla one in the main folder and my edited one in the mod folder and it works fine.
I think the game reads the UI links from the main folder one (i.e. CA forgot to change that link to relative paths)

[zxiang1983]

What if I need to put in 2 factions' icons?
first I deal with 1st faction's icon and create the .sd files. But then what to do? If I just deal with 2nd faction's icon in the same way, will that over write the 1st faction's icon in .sd file?

Hope I express myself clearly. Anyway I just want to know the procedure of putting in 2 factions' icons. Thanks in advance.

[alpaca]

Well you add it to the page next to the one you added first, then add a description in modpage_strat.txt and modpage_shared.txt similar to the first one but with updated coordinates and rebuild the .sd files

[zxiang1983]

Hi, alpaca. Thanks for your reply.

Please forgive me but I'm still a little confused :P

ok, let me summarize my understanding
1, I put my 1st faction symbol in 1.tga, and by using your converter I get strategy.sd(a) & shared.sd(a)

2, I leave the strategy.sd(a) & shared.sd(a) in your converter's folder(instead of moving them to ui folder)

3, I put 2nd faction symbol in 1.tga, too, just different place with the 1st one

4, I re-write coordinates in modpage_strat.txt and modpage_shared.txt to point them to the 2nd faction symbol's location.

5, Then I run your converter again and get strategy.sd(b) & shared.sd(b)

6, strategy.sd(b) & shared.sd(b) is what I wanted.

Am I right?

[wilddog]

That's basically it but you don't need to do steps 1 and 2 as you're overwriting them anyway in the later steps.

[zxiang1983]

I don't understand.
I thought the converter will read information from strategy.sd(a) & shared.sd(a).

If I don't do step 1&2, how will the converter know anything about the 1st faction symbol?

Oh, I know you mean I just have to write 2 entries in modpage_strat.txt and modpage_shared.txt. And then the converter will read the 2 factions' symbols together. Thanks a lot!

[wilddog]

Yes you just add whatever you want to the new TGA file you are using and add in as many corresponding entries into the two modpage files. Create the new *.sd files and then use them.

You don't need to add and compile one symbol at a time.

If you see any strange results its normally just because you got your coordinates wrong.

[alpaca]

Yeah the converter doesn't use the .sd files at all when compiling them, you add two icons to the tga and the description file you want to use and compile. That's it

[tornnight]

You've got a bug with entry name lengths.

I've reproduced

SMALL_FACTION_LOGO_KHW
SMALL_FACTION_LOGO_ABA

works

SMALL_FACTION_LOGO_KHWAREZM
SMALL_FACTION_LOGO_ABBASSID

does not.


Other conditions during this occurance:

I have two seperate tgas 1 for strat 1 for shared.
Each has 12 seperate entries for a total of 24 entries.

I know your example has a long entry name, but under some condition the entry names lengths start to matter.

[Lord Condormanius]

You've got a bug with entry name lengths.

I've reproduced

SMALL_FACTION_LOGO_KHW
SMALL_FACTION_LOGO_ABA

works

SMALL_FACTION_LOGO_KHWAREZM
SMALL_FACTION_LOGO_ABBASSID

does not.


Other conditions during this occurance:

I have two seperate tgas 1 for strat 1 for shared.
Each has 12 seperate entries for a total of 24 entries.

I know your example has a long entry name, but under some condition the entry names lengths start to matter.

SMALL_FACTION_LOGO_TOULOUSE
SMALL_FACTION_LOGO_BURGUNDY
SMALL_FACTION_LOGO_ARMENIA
SMALL_FACTION_LOGO_IRELAND
SMALL_FACTION_LOGO_WALES

all work for me...