Action3

From GRFSpecs
Revision as of 09:30, 7 September 2007 by Pjf (talk)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Associate vehicles with graphics set IDs

Action 3

Associate vehicles/stations with graphics set IDs.

-=Introduction=-

Action 3 tells the patch what graphics set ID (from action 2) to use for a certain vehicle or station.

-=Format=-

The format of the data is feature-dependent.

The data is

 -+<Sprite-number> * <Length> 03 <feature> <n-id> <ids...> <num-cid> (<cargo-type> <cid>)... <def-cid>+-

||Element|Size|Description

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

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

03|B|Defines action 03

<feature>|B|What type of vehicle or stations do the IDs refer to

<n-id>|B|Number of vehicles/stations this action 3 associates graphics with

<ids...>|B|Vehicle or stations IDs of the vehicles this action 3 associates graphics with. There must be as many IDs as <n-vid> specifies

<num-cid>|B|Number of different cargo types to support

<cargo-type>|B|Cargo type for which to use the following cargo ID

<cid>|W|Cargo ID (from action 2) to use for this cargo type

<def-cid>|W|Default cargo ID to use if none of the above matches||

-=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

07 for houses

09 for industry tiles

0A for industries

0B for cargos

n-id

How many vehicles or stations this action 3 defines new graphics for. If this is more than one, all vehicles listed will get the same graphics. If this value has bit 7 set (i.e. 80 added), it is a wagon override. See Action 3 - Livery Override for more info on this feature.

You can make a definition with n-id equal to zero (and thus no ids that follow).  This creates a generic feature-specific definition not associated with any particular vehicle.  At the moment, this is used for generic callbacks, but might be extended to other functions eventually.

ids

Vehicle or stations IDs to use this action 3 for. All vehicle IDs are counted from the first of their class, i.e. the first road vehicle has 00, as does the first plane, the first ship, and the first train vehicle.

For feature 05 canals:

||ID|Description|Number of sprites|

00|Watercliffs|4*

01|Locks|24

02|Dikes|12

03|Icons|1*

04|Flat docks|4

05|River Slope|4*

06|River waterside|12*5 (Last 4 for slopes)

07|River GUI|2||

Note: The Number of sprites for feature 05 canals may change via a graphic flag set in Action0Canals

For town buildings, the IDs are the house IDs, and specifying a house ID that haven't been defined before (by setting its property 08) doesn't do anything, but doesn't cause an error, either. Note that you don't necessarily have to assign a cargo ID to a house ID, the old TTD sprite of the substitute type will be used if you don't do so.  Industry tile IDs work in the same manner.

num-cid

Number of cargo type definitions that follow. Can be zero if only the default follows.

For feature 05 canals, 07 houses, 09 industry tiles, 0A industries, and 0B cargos this must always be zero.

cargo-type and cid

The cargo-type for which the cid applies.  If the vehicle is built to use this type of cargo, or if it is refitted for it, the given cargo ID (from action 2) is used as its graphics.  See column "type A" in the table at CargoTypes for a list of cargo-type values.

If defined, cargo-type FF is used for graphics shown in the purchase or construction window.

For stations, you can additionally define a special cargo-type of FE which prevents the default from being used (which would show the sum of all cargo).  Instead, the given cid is displayed with no cargo at all.

If the grf file has installed a cargo translation table, the cargo type here refers to the cargo with the label in the given slot of the translation table, e.g. if you use cargo-type=08, it refers to the cargo that has the label in the ninth slot (numbered 08) in the translation table.

def-cid

Default cargo ID if no entry from the cargo-type list above matches, or if there are no special cargo-types listed at all.

-=Example=-

Below is an example of what a real Action 3 pseudo-sprite could look like for a train engine.

 13 * 7   03 00 01 02 00 00 00

||Byte|Meaning

13|<sprite-number>

7|<length> of the action in bytes; start counting at 03 (<action>)

03|<action>: sets this pseudo-sprite to function as action 3

00|<feature>: 00 for Trains

01|<n-id>: One ID to change in this case

02|<ids...>: vehicle ID (02 - Ploddyphut Choo-Choo)

00|<num-cid>: This Engine doesn't have cargo-specific graphics

00 00|<def-cid>: Use Action2 ID 00, because it is a word value you add 00||