The newbie guide in modding
August 21, 2008 - 20:09
1. Overview over the different filetypes
2. Changing the inis
3. Adding new stuff, common problems and newbie mistakes
4. Some useful and simple tutorials for beginner

1. Overview over the different filetypes

There are several different filetypes used by the game. Here the most common.

MIX: mix files are like zip files and work as archives for other files.
You can open them with the XCC Mixer which is part of the XCC utilities.
With the Mixer, you can also extract files from them.
To make new mix files, you can use XCC Mixer too (Don't use XCC Mix Editor as this tends to corrupt mix files). For that copy an original mix, rename it to ecache02.mix, open it, delete all the stuff inside and then add your own new files like vxl or shp.
While the game reads vxl,hva and ini files directly from the main TS directory and also in expandXX.mix files (where XX is a number between 02-99), do SHP files work only in ecacheXX.mix files (XX is a number between 02-99)
Note: If you install a mod make sure that your own mod doesn't shares the same numbers on the mix files.

VXL: the voxel file format of the game. This stores a 3d model of a unit as voxels (volume pixel, or easy 3d cubes). You can edit these files with the Voxel Section Editor. Voxel files do normally contain only one section (e.g. the main body of a tank), but they can also have several sections which normally represent different parts of a unit (e.g. the feet,legs and torso of a mech). The animation for those multiple sections is stored in a HVA file.
While voxel mechs use separate sections in the vxl file, do tanks use a separate vxl file for their turret and barrel. The naming convention is this:
unitname.vxl for the main body
unitnametur.vxl for the turret
unitnamebarl.vxl for the barrel
The game automatically places these files ingame together to one unit. The position of them is defined in their hva file.
Every file of them needs its own hva file! (unitname.hva, unitnametur.hva and unitnamebarl.hva)

HVA: every voxel file needs this file which stores the animation of the voxel sections or at least the position of the voxel in the selection box ingame. You can edit these files with the OS HVA Builder.

SHP: the 2d graphic file format used by the game. It can contain a single image (e.g. a cameo) or a whole unit like the titan with a number of frames. You can edit SHP files with the OS SHP Builder.
To create new SHPs you can use SHP Builder too, though i would suggest Image Shaper.
SHP files use a 256 colors palette which is stored in the separate file format PAL.

SHP files used for units follow a certain frame order. The position of the frames for the respective animation is set in art.ini via, either via a Sequence for infantry or for vehicles the several of the following keys
StartStandFrame
StandingFrames
StartWalkFrame
WalkFrames
StartFiringFrame
FiringFrames
StartDeathFrame
DeathFrames
MaxDeathCounter
DeathFrameRate
FiringSyncFrame1
FiringSyncFrame2

In the SHP, Infantry rotate counter clockwise starting with facing North and allow only 8 facings.
Vehicles rotate clockwise. When using 8 facings they start North, when using the exe hack to allow 32 facings, the first frames start at 33,75°.

Turreted SHP units need to have first the walk frames in the SHP, followed directly by the 32 turret frames. After that you are free to add standing and firing frames, though firing frames can be done for the chassis only, not for the turret.

PAL: these files, which store a color palette with 256 colors, are used by SHP files to give them their color. e.g. while units normaly use the unittem.pal or unitsno.pal palette (for the 2 theaters temperat and snow), do civil buildings use isotem.pal or isosno.pal, which don't have the remappable colors. Remappable colors are the 16 red colors in unittem.pal and unitsno.pal in the bottom left of the palette shown in OS SHP Builder. These red colors change to the respective house color in the game.

TMP: these files are used for the terrain of maps. You can edit them with the TMP Studio.

AUD: the sound files used from the game. The game can play aud files only with the format 22050Hz,16Bit,Mono. So if you create them with XCC mixer from a wav file, make sure the wav has this format.

INI: these files are used to define several aspects of the game in form of text. The most common used are art.ini and rules.ini which you can find in TIBSUN.MIX/Local.mix or for Firestorm in expand01.mix as artfs.ini and firestrm.ini.
Other files are sound01.ini for all the sounds in TS and FS and ai.ini for the AI of the computer players.
It's not necessary to put your ini files into a mix file. Indeed it is much more comfortable to simply let them in the main TS directory, so you can easyly edit them and test the modification ingame.


2. Changing the inis

Before you can start changing the inis you have to extract them. Start XCC Mixer and open Tibsun.mix, which you can find in your TS folder (there where your game.exe is placed). In Tibsun.mix you can find several other mix files, where you now open local.mix. In this you can find the rules.ini and art.ini. Right-click on them and extract them in your TS folder. For a more detailed description how to work with mix files you can check out the XCC Mixing 101 tutorial.

Now that rules.ini and art.ini are in your TS folder you can start to edit them.

The first rule is, always use a simple text editor like notepad (better NotePad++). Tools like TibEd or SunEdit2k mess up the inis and don't give you all the possibilities which you get by manual editing.
The second rule is, never make so much changes at once that you can't trace back what you have done, or you get serious problems if you once get an IE (Internal Error) because you made a mistake and the game crashes.

rules.ini, the probably most important file for editing the game. It stores all the information about units, buildings, weapons, superweapons and general game behaviour. Since nearly all keys have a comment about what they do and how they work, i won't explain here in detail how to create a new unit or a new weapon. The easiest way is to simply copy an original unit/building or weapon and then change this copy. But make sure that if you created a new unit or building, you've added it to the respective Types list with a new entry. The most important lists are
[InfantryTypes]
[BuildingTypes]
[AircraftTypes]
[VehicleTypes]
[Warheads]
[Animations]

art.ini is another important file, which stores all the animations and graphical stuff for the game. Here you can find among other things, for all buildings and units a respective entry which tells the game everything it needs to know about the animations it should play, the length of frames for those animations and additional information like the point from where a unit fires its gun (see PrimaryFireFLH or SecondaryFireFLH)


3. Adding new stuff, common problems and newbie mistakes

If you want to add new buildings or units, you have to take care of several aspects.
1. The name of the entries in the ini files (art.ini, rules.ini sound01.ini etc) must match with the filename of the SHP, VXL, AUD file.
2. Use always uppercase for the entries in the inis (e.g. MYUNIT). The game is case sensitive and if you write [MYTank] in art.ini and 51=MyTank in rules.ini in the VehicleTypes list, the game simply can't find this unit and you have an invisible unit ingame.
3. Do not use any special character like space, points etc in the ID fields (e.g. [My New.Tank*Is#awesome] <- that is wrong).
4. SHP units must be in ecacheXX.mix files! (XX = number between 02-99) else the game can't find them and the unit/building is invisible ingame
5. MIX files are sometimes corrupt and cause an IE while loading a game. If this happens, delete all the content of the mix file and add it again.
6. VXL files must have a respective HVA file. Again must their name match with the respective ini entry.
7. If you add new entries to art.ini or rules.ini, add these right after or before the corresponding original stuff. (keep the inis well-ordered as good as possible)
8. If you want to add new animations to the game, you have to make sure that you have added all Firestorm anims to the [Animations] list in your rules.ini before you add your own stuff. Or you get the nasty savegame bug. You can find a tutorial which fixes this problem on tibweb.
9. Never change/edit the original MIX files. Add stuff by using expandXX.mix or ecacheXX.mix files. Only for a real total conversion and when you know what you're doing, you can touch any of the original mix files.
10. Never change the order of any of the original rules.ini lists like
[InfantryTypes]
[BuildingTypes]
[AircraftTypes]
[VehicleTypes]
[Warheads]
[Animations]
Always add your new stuff at the end of these lists.
11. Check out original stuff and look how it is set/used. You'll learn much more this way, than asking here on the forum how every ordinary key works.
12. Use a copy of an existing original object when trying new things, rather than writing a complete code yourself, where you can easyly miss several keys.
13. You can't invent your own keys like MakeMyModAwesome=yes. The game ignores such nonsense. It has a fixed amount of keys, which only work if written exactly as defined by the game. (You can check if a key exists, by opening game.exe in a hex editor and searching for the key.)
14. Buildings use for each theater (snow & temperate) a file with a certain prefix in their name: CA,GA,NA for arctic/snow maps and CT,GT,NT for temperate maps. If the SHPs for a building are only present for one theater, they will be invisible ingame in the other theater. Thus avoid using the prefixes if you don't have theater specific SHPs or create duplicates of the SHPs and give them the other prefix.
15. A good way to avoid problems with the firestorm inis like described in point 7, is to use the UMP. This one moves all FS stuff to TS, which makes ini editing easier and it also fixes already many bugs of vanilla TS/FS.
That's why it's highly recommended to install the UMP before starting a mod.

I hope this tutorial makes an end to the constantly repeated newbie questions

4. Some useful and simple tutorials for beginner
-Creating a new unit
-Making airplanes fly parallel to the ground
-How to add voxels to your mod
-(**) How to add downloaded units,buildings and graphics

P.S. to all those newbies, please use the Forum search before you ask simple questions about modding the game, since after 8 years almost everything has been asked before. Wink