Action4

Define vehicle (etc) names or change generic texts

Action 4

Define vehicle names or change generic texts

-=Introduction=-

When making new vehicle graphics, you also need to name the new vehicles, or they'll show up with their original name from TTD.

In addition, you can change most of TTD's text strings.

Note that changes of vehicles names can be overridden by using TTD's vehicle.dat custom vehicle names.  There is no way to bypass the custom vehicle names, other than turning them off or deleting vehicle.dat.

-=Format=-

The data looks as follows:

 -+<Sprite-number> * <Length> 04 <feature> <language-id> <num-ent> <offset> <text>+-

||Element|Size|Description

<Sprite-number>|dec|A sequential sprite number

<length>|dec|The total number of bytes used in this action.

04|B|Defines action 04

<feature>|B|For what type of vehicle/station should this definition be used?

<language-id>|B|Which of TTD's languages this name is for

<num-ent>|B|Number of consecutive strings to change

<offset>|B/W|First ID to change

<text>|S|New text strings||

Note that <offset> is a BYTE for feature-specific IDs, but a WORD for generic text strings.

-=Filling in the terms=-

Sprite-number

This is just the number you are at.

Length

Count the number of bytes in this action.

feature

This sets the type of feature that you wish to change. Set it to:

00 for trains

01 for road vehicles

02 for ships

03 for planes

04 for stations

05 for canals

06 for bridges

07 for houses

0A for industries

0B for cargos

48 for generic strings (language-id bit 7 set), unless they should only be changed in conjunction with new vehicles/stations/etc., in which case you use the regular feature number above

language-id

The meaning of this byte depends on the GRF version of the .grf file as set in action 8.

Up to version 6, this is a bit mask of the following bits:

||Bit|Value|Meaning

0|01|American or "other"

1|02|English

2|04|German

3|08|French

4|10|Spanish

7|80|Flag for generic strings||

Add the bits of all languages for which the following strings apply. If bit 7 is set, these strings change generic TTD texts instead of specifically the vehicle names. Since TTDPatch now supports languages other than the standard ones, unknown languages will use the American strings as fallback. Otherwise the string would remain undefined for these languages. To actually define strings for any new language, you must use grf version 7.

For version 7 and higher, it is a simple language ID from the list below. (This has changed with 2.5 beta 4). Bit 7 has the same meaning as in the earlier versions above.

In either scheme, you can use the value 7F or FF, respectively, to define strings shown for languages that you do not provide translation for. First set all strings to a default value using this, and later override the language specific ones if they exist.

Currently, the scheme is to use international phone codes as language IDs, unless they're out of range, in which case pick a number vaguely related in some way. Or something else.

||ID (hex)|Language

00|American

01|English

02|German

03|French

04|Spanish

05|Esperanto

06|Ido

07|Russian

0C|Chinese (Traditional)

0D|Serbian

0E|Norwegian (Nynorsk)

0F|Welsh

14|Arabic (Egypt)

15|Czech

16|Slovak

18|Bulgarian

1B|Afrikaans

1E|Greek

1F|Dutch

22|Catalan

23|Luxembourgish

24|Hungarian

26|Macedonian

27|Italian

28|Romanian

29|Icelandic

2A|Latvian

2B|Lithuanian

2C|Slovenian

2D|Danish

2E|Swedish

2F|Norwegian (Bokmal)

30|Polish

31|Galician

32|Frisian

33|Ukrainian

34|Estonian

35|Finnish

36|Portuguese

37|Brazilian Portuguese

38|Croatian

39|Japanese

3A|Korean

3C|Malay

3E|Turkish

42|Thai

56|Chinese (Simplified)

5A|Indonesian

5C|Urdu

61|Hebrew

62|Persian

80|Flag for generic strings (added to language ID)

7F|any (will be applied no matter what language is active)||

When translating for a new language, please simply edit this document and add the new definition here.

num-ent

How many consecutive entries to change.

offset

The ID of the first string to change.

For vehicle IDs (language-id bit 7 is clear), this is a byte value, except for OpenTTD since r13482, where it is an extended byte value.

For generic text IDs (language-id bit 7 is set), this is a word value in little endian notation, e.g. 8134 becomes 34 81. See TextIDs for a list of TTD's text IDs (town names are changed with Action F instead).

In addition, TTDPatch defines the following generic text IDs for this action:

||ID|Content

C4xx|Set name of station class associated with station ID xx; this is the text above the preview (where otherwise TTD shows "Orientation")

C5xx|New station names, this changes the text "number of platforms" into the given text when the station with this ID from the current set is selected (i.e. xx=station-id from action 3 and 0)

C9xx|Name of the house type of this ID. If both property 12 and this is set, the latest definition is used always. You should prefer setting property 12 instead of this, so executables translated with TTD Translator will show the name in the current language. However, if you can't find any suitable old TTD texts, this can be used to specify your custom name. Don't forget to set the same text for all parts of a multi-tile building.

D0xx|Miscellaneous graphics texts, unique to each .grf file. Used for several callbacks. Some callbacks as well as newobjects support IDs up to D3FF.

DCxx|Set miscellaneous persistent GRF texts. Unlike the D0xx GRF texts, these IDs can be used to set properties. The text ID must be set before any action 0 references it.||

The DCxx IDs are allocated internally when defined, and are persistent in the savegame data. Each .grf file gets its own separate map of these internal IDs and thus may set all 256 of them.  However, only 1024 IDs are available in total, to be shared by all .grf files ever activated in the savegame. This means these IDs should be used as sparingly as possible. But use them when they are useful!

text

This is a list of zero-terminated strings, there must be as many strings as num-ent specifies.

You can use the converter to generate the proper hex values.

Alternatively, use grfcodec version 0.9.6 or later, which accepts literal strings in the .nfo. These are encoded exactly as written, in whatever encoding your text editor uses; if you need a 00, put it immediately after the literal string.

For the supported encodings, format, and restrictions on what characters you may use, please see GRFActionsDetailed and StringCodes.

A large number of generic TTD strings require a colour code in front of the actual string. You can also use these colour codes in most of your custom strings. Use them wisely! In case a generic string requires a colour code, the string will have the code displayed in front of the default text as listed in TextIDs.Typically, a colour coded string starts with the escape character (backslash), followed by hex byte and then the actual text string itself. I.e. string 0001 ("\94Off edge of map") has colour code 0x94 in front of the text string, which will colour it white. You can also put the plain hex byte outside the quoted string without having to escape it. 94 "Off edge of map" would be the same as "\94Off edge of map"

The following 16 colour codes are available for use:

||Code|Colour

88|Blue

89|Light Grey

8A|Yellow

8B|Red

8C|Light Purple

8D|Beige

8E|Light Orange

90|Light Yellow

91|Light Green

92|Light Pink

93|Brown

94|White

95|Light Blue

96|Grey

97|Purple

98|Black||

-=Example=-

Something to go here