'''''Action 0 properties for new objects'''''

=Action 0 - Properties for new objects=

Defining properties of new objects.

{maketoc}

Unlike vehicles or new stations, most new objects have no real equivalent in TTD.

The IDs are therefore free to be chosen and will in fact be allocated automatically by the patch. In action 0, you only specify IDs relative to the set, i.e. the ID of the first object type is 00, the second object type is 01 and so on. In total, each game can only have 255 object IDs for all active grf files.

The property you '''must''' set for each object ID is 08 (in addition to defining an action 3 for it). Also, all object IDs must get their classes in the right order, starting from ID 00 onwards.

-=Properties=-

||Number|Version|Size|Description

08|a|D|Class ID, see below

09|a|W|Text ID for class

0A|a|W|Text ID for this object

0B|a|B|[[Action0General#Climate_availability|Climate availability]]

0C|a|B|Byte representing size, see below

0D|a|B|Object build cost factor (sets object removal cost factor as well)

0E|a|D|Introduction date, see below

0F|a|D|End of life date, see below

10|a|W|Object flags, see below

11|b|W|Animation information

12|b|B|Animation speed

13|b|W|Animation triggers

14|b|B|Object removal cost factor (set after object build cost factor)

15|b|W|Callback flags, see below

16|b|B|Height of the building||

Check [http://pics.lakie.net/newObject-ActionStructure.png|Lakie's Graphical Representation of the newObject Specifications|nocache]

The specifications of NewObjects are available since OpenTTD r20670 in TTDPatch since r2340

-=Comments=-

==Object class (08)==

Unlike station classes, there is currently no default yet, planned are TRNS for transmitters and LTHS for lighthouses. '''You have to set the class ID before any other property.''' Characters allowed in the IDs are A-Z, 0-9.

1. The following is a '''Recommendation''' for Object Class Labels.

2. It is possible to have a label for each object. This would make for a very ungainly menu.

3. A labeling system allows a coder/author to make their works much more user friendly.

4. To keep the numbers more manageable, the classes are as generic as possible.

5. While being generic, assigning objects to a label should be intuitive.

6. Assuming that there will be special circumstances where a coder/author needs to deviate from the norm, '''the Recommendation is not mandatory'''.

||<center>RECOMMENDATIONS</center>

Label|<center>Action4 Text</center>|<center>Description</center>

TTDX|<center>Default*TTDX</center>|Transport Tycoon's copywritten objects - lighthouse, communication tower, rocks, etc.

OTTD|<center>Default*OpenTTD</center>|OpenGFX objects - lighthouse, communication tower, rocks, etc.

STRU|<center>Structures</center>|Multitile engineered objects that don't quite fit in as industries, houses or stations - dams etc.

INFR|<center>Infrastructure</center>| - lightpoles, communication towers, transmission towers, road signs, etc.

BLDG|<center>Buildings</center>|Normally accomodated by industries, houses or stations but the author feels there are limiting circumstances.

NATR|<center>Natural objects</center>| - caves, coral reefs, swamps, etc.

PARK|<center>Public areas</center>|Normally accomodated by towns or industries (tourist stuff ...) but the author feels there are limiting circumstances - Parks, statues, etc.

ARTF|<center>Artifacts</center>|They really don't fit under any of the above - shipwrecks, etc.

MISC|<center>Miscellaneous</center>|For the author who is unable to accommodate his/her object under any of the previous labels.||

==Object class text ID (09)==

The text ID for this class (word value). This textid should be either a TTD textid or a D4xx textid (set via D0xx in action4).

When specifying an object, you don't need to set a class name again if you already did for another one with the same class.

==Object text ID (0A)==

The text ID for the object for query and selection (word value). Same requirements as for property09.

==Object size (0C)==

The object size up to 15x15 tiles.

This byte value is divided into two nibbles. The first defines the size in y direction and the second defines the size in x (i.e., stored as YX).

Note that any value lower than 0x11 will be rejected.

==Build Cost (0D)==

The build cost multiplier. This is multiplied by the number of tiles for evaluation of construction and removal costs of an object.

==Introduction date (0E)==

Introduction date of an object, in days since the year 0. This takes account of leap years; divisible by 4, but not 100 unless 400. A start date of 1920-01-01 is obtained with a value of 701265 (51 B3 0A 00). In TTDPatch anything before 1920 is considered to be always available, and it should allow for objects to work past 2044, the date is also the very first date you can build the object.

==End of life date (0F)==

Last year an object can be build, in days since the year 0. Same requirements as above. Also note that it must be a minimum of a year (365 days) after the introduction date or TTDPatch will ignore it.

==Object flags (10)==

The following flags control object behaviour and are cached for built objects, so changing these flags will have no effect on already constructed objects.

||Bit|Value|Version|Meaning

0|1|a|Only Available in the scenario editor (1)

1|2|a|Irremovable (2)

2|4|a|Anything Can Remove (owned land behaviour)

3|8|a|Allow construction of the object on water

4|16|a|Removal cost is actually income (owned land behaviour)

5|32|a|Do not display foundations if on a slope

6|64|a|Object has animation (3)

7|128|a|Only available during game play (1)

8|256|b|Allows 2cc mapping for objects instead of the default 1cc

9|512|c|Disallows construction on land (also has bit 3 behaviour)

10|1024|c|Draws the water under the object (4)

11|2048|d|Allow bridge over the object taking the building height into account (5)

12|4096|d|Random bits in the "next animation frame" callback||

c - TTDPatch r2331

(1) - Note that bits 0 and 7 are incompatible and setting both will make an object completely unavailable.

(2) - Object cannot be removed through normal dynamite, control must be held and the removal cost will be multiplied by 25 (this is the usual behaviour for most class A objects in TTDPatch).

(3) - Setting this flag will allow the object's animation counter to be increased, must be set if you plan to make use of animations. Like stations you must enable animation on a per tile basis by means of the "built tile" trigger and callback 159.

(4) - Only applies when built on top of a water tile, also replaces the ground tile of the object completely. (Does not work when object built on sloped water tiles).

(5) - Only applies to OpenTTD. TTDPatch does not support bridges over objects yet.

==Animation information (11)==

The low byte specifies the number of animation frames minus one, so 00 means 1 frame, 01 means 2 frames etc. The maximum number of frames is 256, although you can have some problems if your animation exceeds FD (253) frames. The high byte must be 0 for non-looping animations and 01 for looping animations. Every other value is reserved for future use. In addition, if the whole word contains FFFF, animation is turned off for this object (this is the default value).

Since you can't have properties for individual object tiles, this property applies for every tile of the object. If you don't want to animate some tiles, you should check the current position during [[Callbacks#Animation_control_1B_25_140_|callback 159]] and return FD if the current tile doesn't need to be animated. If you also need animations of different length per tile, you'll have to use [[Callbacks#Next_animation_frame_1A_26_141_|callback 158]] for that.

==Animation speed (12)==

The meaning is the same as for [[Action0Houses#Animation_Speed_1B_|house property 1B]], but the lower limit is 0 instead of 2, so the fastest possible animation changes frames every game tick (27ms). The default value is 0.

==Animation triggers (13)==

This is a bit mask of events that should trigger [[Callbacks#Animation_control_1B_25_140_|callback 159]], allowing to change the animation state

||Bit|Value|Meaning|Happens on

0|1|Object is built|all tiles

1|2|Periodic tile loop|single tile

2|4|Synchronised periodic tile loop|all tiles||

The synchronised periodic tile loop is called directly after the (unsynchronised) periodic tile loop of the northern tile.

==Object removal cost factor (14)==

Cost factor for the removal of an object. This must be set after property 0D (object build cost factor) as that overwrites this value.

==Callback flags (15)==

For objects, the following [[Callbacks|callbacks]] can be defined by setting the corresponding bit in property 15:

||Bit|Value|Variable 0C value|Callback

0|1|157|Custom slope check

1|2|158|Decide next animation frame

2|4|15A|Decide animation speed

3|8|15B|Decide colour of building

4|16|15C|Show additional text in the build object window

5|32|15D|Allow/disallow autosloping||

==Building height (16)==

Set the height of the building in heightlevels (8 pixels). For example if the structure is 16 pixels high you set this property to 2.

In OpenTTD this property is used to determine the height of the build object window; the height for the object preview is set to 32 + "value of property 16" * 8. The property is also uses to determine how high a bridge must be if it is allowed by the bit in property 10.

2010-04-17T11:26:24Z

Rubidium:

'''''Define vehicle names or other texts'''''

=Action 4=

Define vehicle names or other 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:

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

||'''Element'''|[[GRFActionsDetailed|'''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||

Whether <offset> is a '''BYTE''' or a '''WORD''' is decided by bit 7 of <language-id>, see below.

-=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 original strings; see [[TextIDs]] for a list of TTD's text IDs.

===language-id===

The meaning of this byte depends on the GRF version of the .grf file as set in [[Action8#version|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 16 bit string IDs||

Add the bits of all languages for which the following strings apply. Bit 7 controls, whether the following string ID consists of 16 or 8 bit. 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

08|Irish

09|Maltese

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

21|Basque

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

54|Vietnamese

56|Chinese (Simplified)

5A|Indonesian

5C|Urdu

61|Hebrew

62|Persian

80|Flag 16 bit string IDs (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.

When language-id bit 7 is clear, this is a byte value; except for OpenTTD since r13482, where it is an extended byte value for vehicles.

When language-id bit 7 is set, this is a word value in little endian notation, e.g. 8134 becomes 34 81.

The 8 bit version is only allowed for vehicles to set their name, in which case the text ID is just the vehicle ID.

To replace original texts, or to define texts for usage in callbacks or properties of vehicles, stations, houses or industries you have to use the 16 bit version. However, town names are changed with [[ActionF|Action F]].

For the usable 16 bit text IDs see the table below, resp. for feature 48 see [[TextIDs]].

Though these ranges are shared across all features, you should still set the proper feature you are using them for.

||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 [http://www.ttdpatch.net/cgi-bin/str2hex.pl|str2hex 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#Strings|GRFActionsDetailed]] and StringCodes.

A large number of original 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 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