The First Vehicle
Getting your first vehicle into the game
The First Vehicle
This section of the tutorial takes the rudimentary mytrain.grf file you made in the previous step, and turns it into a .grf file usable by TTDPatch.
Here's what you have to do:
- Figure out "pseudosprites"
- Add the special first pseudosprite
- Give your file an GRFID
- Add an "action 1" to introduce your vehicle graphics
- Use actions 2 and 3 to link your graphics to a vehicle in TTD
- Adjust the first pseudosprite again, and renumber all sprites
- Encode and add to newgrf(w).cfg
Now let's look at this in more detail.
1) Figure out pseudosprites
If you've looked through trg1r.nfo, you may have noticed that some entries look different to the usual ones.
Usual entry:
-+ 24 C:\TTD\SPRITES\trg1r.pcx 450 8 01 9 7 0 0+-
This one is different:
-+ 771 * 17 10 00 F0 F0 F0 F0 F0 F0 F0 F0 F0 F0 F0 F0 EF EF EF+-
The first one refers to an image in the PCX file. The second one is some additional data that's not an image. These types of entries are called "pseudosprites", and in TTDPatch .grf files they are used to give TTDPatch information what it should do with the graphics in the file.
Here's what you have to know:
- The first number is the well-known sprite number, simply counting entries from the beginning of the file
- Then follows an asterisk "*", where you would normally have the PCX filename
- Then there's another number, which is the length of the following data
- And finally the actual data, as a bunch of hex codes
So, that's what you have to know about pseudosprites for now. Let's get started...
2) Add the special first pseudosprite
For TTDPatch graphics files, the first entry in the .nfo is special, and tells TTDPatch how many lines the file has. Since we don't yet know how big it will be, we add it but don't put any useful data in.
Here's what you do: in your mytrain.nfo file, after the comment lines (those that begin with "//"), but before the first entry, insert the following line:
-+0 * 4 00 00 00 00+-
3) Give your file an GRFID
Apart from the first line which we've added in the previous step, TTDPatch .nfo files are organized by "actions". These actions tell TTDPatch what to do with the graphics in your file. In our specific case, we need to tell TTDPatch to use those graphics for a train engine.
Before you go any further, just let me make clear what the different ID's mean that we will refer to. Here's a table:
||ID Type|Purpose
Vehicle ID|A generic vehicle/station/building slot whose properties can be defined using an Action 0. A Cargo ID can be associated with this using Action 3.
set ID (called cargo ID for vehicles)|A ID asociated with one or more Spritesets using an Action 2. Can be asociated with a Vehicle ID using Action 3.
Spriteset|A value unique to each Action 1. Defines a set of 8/4 views i.e. a set of sprites. Is in an action 2
GRFID|A word value used to differentiate between different grf files. This should be globally unique!||
Just keep that in mind and refer to it later on.
Now, lets continue.
The first step to do that is by using an Action 8, which gives your file an GRFID, and allows people to turn it on or off in the GRF Status Window.
You have to choose the GRFID yourself. To find a good GRFID to use, for example use the initials of your first and last name, plus two numbers.
For example, for this tutorial, we'll use the initials "TW". In addition, we need two numbers to identify the file. These you can pick however you like, you'll use them to distinguish different graphics files made by you. Those will have the same initials, but must get different GRFIDs, so you pick different numbers. For example, here we pick 3 and 5.
This means we get the following GRFID:
You may also write the initials as hex codes. If you aren't familiar with hex codes, you can use the Converter to help you. Simply enter your initials and click convert, and then write down the hex codes. This is more complicated, so very few people do it, but the result would be the following equivalent GRFID:
This form is the official form for a GRFID, and should be used in all non-.nfo contexts. In .nfos, you may use whichever form you prefer.
The 54 57 are the hex codes for "TW". In both cases, 03 and 05 are the numbers we've picked, written in hex.
Therefore, you insert the following line immediately after the line which you've added in the previous step:
-+ 1 * 8 08 06 "TW" 03 05 00 00+-
This gives your graphics file the GRFID. This action 8 must always be present in your files, and it must be one of the first lines. If you don't have an action 8, TTDPatch will complain about "invalid sprites" or an "incorrect version", and refuse to load your file.
You can optionally give your file also a name and a description or copyright info, but that's beyond the scope of this tutorial. Check the docs for action 8 for more details.
4) Add an action 1
Right, so now the file has an GRFID. In the next step, we need to tell TTDPatch that there will be a bunch of graphics in this file. You might think that that's obvious, but nothing is obvious to computers, so we have to tell it.
This happens through an Action 1 entry, that tells TTDPatch there will be one or more sets of graphics in the file. In our case it looks like this:
-+ 2 * 4 01 00 01 08+-
Add this line right after the above action 8. It's worth decoding what this line means. you can just read it from the left to the right. We have the following:
||Code|Meaning
01|Action 1
00|Feature 0, meaning trains
01|One set of graphics
08|Each set has eight views||
For more details on these, in particular to see what "features" there are, check the Action 1 docs.
After this follow the eight lines with the actual graphics that we already have in the .nfo file. So at this point your file should look something like this:
// Automatically generated by GRFCODEC. Do not modify! // (Info version 6) // Format: spritenum pcxfile xpos ypos compression ysize xsize xrel yrel 0 * 4 00 00 00 00 1 * 8 08 06 "TW" 03 05 00 00 2 * 4 01 00 01 08 0 C:\TTD\SPRITES\mytrain.pcx 66 8 01 18 8 -3 -10 1 C:\TTD\SPRITES\mytrain.pcx 82 8 09 15 20 -14 -6 2 C:\TTD\SPRITES\mytrain.pcx 114 8 01 12 28 -14 -6 3 C:\TTD\SPRITES\mytrain.pcx 162 8 09 16 20 -4 -8 4 C:\TTD\SPRITES\mytrain.pcx 194 8 01 18 8 -3 -10 5 C:\TTD\SPRITES\mytrain.pcx 210 8 09 16 20 -14 -7 6 C:\TTD\SPRITES\mytrain.pcx 242 8 01 12 28 -14 -6 7 C:\TTD\SPRITES\mytrain.pcx 290 8 09 15 20 -4 -7
However, if you're doing this for one of your files, you have to choose your own GRFID of course because 54 57 03 05 is reserved for the file we're making in this tutorial.
5) Using actions 2 and 3
At this point, TTDPatch knows the GRFID of your file, and it has loaded the graphics for it. The only thing that remains to be done is linking these graphics to one of TTD's vehicles. Note that you can't add new vehicles as such, you can only replace existing ones. This means that you also have to decide which one to replace, so you have to find out the vehicle ID of that vehicle. Since we've based the graphics on the SH 125 here, we might as well replace that one, although you're free to use whichever vehicle you want. There's a list of vehicle IDs here. You can pick any train number from the list, don't forget to convert the number to hex.
Warning: You can only replace trains with trains and ships with ships and so on.
To associate graphics with a vehicle, we use Action 2 and Action 3. Action 2 is called a "cargo ID", because it contains various states of animation of one particular cargo. This isn't really important for the train engine we're making, but for example wagons may be able to carry different cargos that should also look differently.
For our train engine, we define one cargo ID like this:
-+11 * 9 02 00 00 01 01 00 00 00 00+-
This is already getting a bit complicated, so let's look at it in detail:
||Codes|Meaning
02|Action 2
00|Feature 00, meaning trains
00|We define Cargo ID 0 (the first number available)
01|There is only one set of graphics we have while in motion
01|And also only one set while loading
00 00|Use the first set while in motion
00 00|And also while loading/unloading||
Instead of cargo ID 0, we could have defined any other number, but it makes sense to start with the first number.
Regarding the number of sets, it's possible to show various states of animation depending on how full the vehicle is, and whether it's in motion or whether it's loading or unloading. However, for train engines that's unimportant, so we'll forget about it for now.
The last sets of two 00 codes tells TTDPatch which sprite-sets to use, referring to the most recent action 1. Since we've only had one set there, and sets are numbered starting from 0, that means we have set 0. We put down the set number 00, followed by another 00 because TTDPatch needs that. If we were using set 1, it would be 01 00.
This is our cargo ID definition. Now we attach this cargo ID to the vehicle using action 3. The SH 125 has vehicle ID 22, or 16 in hex, so we use the following:
-+12 * 7 03 00 01 16 00 00 00+-
Again in more detail:
||Codes|Meaning
03|Action 3
00|Feature 00, meaning trains
01|We attach these graphics to one vehicle
16|The vehicle has vehicle ID 16 (in hex)
00|We have zero special cargo type graphics
00 00|We use cargo ID 0 in all case||
We could give the same graphics to several vehicles, but that's usually not useful. For wagons, we could also define various cargo IDs and attach them depending on what cargo the wagon carries, but for engines that doesn't matter and so we just use cargo ID 0. Again the first 00 refers to cargo ID 0, and the second 00 is required because TTDPatch needs it.
At this point, we only need one more action: we need to tell TTDPatch to actually use these new graphics. Action 3 only says if the vehicle uses new graphics, then these are what it should use. To actually make it use new graphics we use Action 0, like this:
-+13 * 7 00 00 01 01 16 12 FD+-
In more detail:
||Code|Meaning
00|Action 0
00|Feature 0, meaning trains
01|We set one property
01|For one vehicle
16|Starting at vehicle 16
12|We set property 12 (sprite type)
FD|And we set it to FD||
We could set more than one property to give the vehicle for example different power and speed, but for now we only want to see the new graphics, and for trains that means we need to set property 12 to FD, which tells TTDPatch to use new graphics for this vehicle ID. For the other property, check the action 0 docs.
6) Adjust and renumber
Now we're basically done, we told TTDPatch what graphics to use for what vehicle. We only need to renumber the file and adjust the first pseudosprite. So you go through all the entries, make sure they start at zero and that the following number increases by one. In this case, the last number ends up being 13.
Now we have to adjust the first entry, because it needs to tell TTDPatch how many lines to expect for the rest of the file. Since the last line is 13, we set it to 13, but we have to write it in hex in little endian format. 13 in hex is D, which has to have zeroes added from the left to make eight digits, or 0000000D. Now you cut these into groups of two (00 00 00 0D) and write them in the opposite order (0D 00 00 00). That's what you put in the first entry.
Now your mytrain.nfo file is done, and it should look like this:
// Automatically generated by GRFCODEC. Do not modify! // (Info version 6) // Format: spritenum pcxfile xpos ypos compression ysize xsize xrel yrel 0 * 4 0D 00 00 00 1 * 8 08 06 "TW" 03 05 00 00 2 * 4 01 00 01 08 3 C:\TTD\SPRITES\mytrain.pcx 66 8 01 18 8 -3 -10 4 C:\TTD\SPRITES\mytrain.pcx 82 8 09 15 20 -14 -6 5 C:\TTD\SPRITES\mytrain.pcx 114 8 01 12 28 -14 -6 6 C:\TTD\SPRITES\mytrain.pcx 162 8 09 16 20 -4 -8 7 C:\TTD\SPRITES\mytrain.pcx 194 8 01 18 8 -3 -10 8 C:\TTD\SPRITES\mytrain.pcx 210 8 09 16 20 -14 -7 9 C:\TTD\SPRITES\mytrain.pcx 242 8 01 12 28 -14 -6 10 C:\TTD\SPRITES\mytrain.pcx 290 8 09 15 20 -4 -7 11 * 9 02 00 00 01 01 00 00 00 00 12 * 7 03 00 01 16 00 00 00 13 * 7 00 00 01 01 16 12 FD
7) Encode and add
Now all we have to do is encode the file:
-+grfcodec -e mytrain.grf+-
and then add it to newgrf(w).cfg to test it!
Make sure to check the GRF Status Window to see that your file is enabled. If not, click on its red flag and then click "apply". If you get any error messages, write down the sprite number that's incorrect, and then fix the mistake in the corresponding line in the mytrain.nfo file.
Further reading
Basically, now you know most of what's needed to make your own graphics. Further details can be found in the GRFActionsDetailed page, which tells you everything about all the actions there are.
The next few sections will cover in some more detail the most common tasks for making new graphics, but other than that you're on your own now!
