Action14

Static GRF Information

Action 14

Static GRF Information

{maketoc}

-=Description=-

This action allows to specify additional information about the GRF. Every piece of information is considered optional and non-essential, thus OpenTTD/TTDPatch will ignore unknown parts and not display any error. The action is also meant to allow interfacing non-official extensions/patches for OpenTTD.

Currently this action can be used to define

• translations for the name and description of the GRF. (Those from action 8) (since OpenTTD r20250)
• the palette (DOS, Windows) the GRF needs, or whether the palette does not matter. (since OpenTTD r20254)
• the number, format and purpose of GRF parameters. (allowed values, names, descriptions, ...) (since OpenTTD r20255)
• version information and compatibility to older versions of the same GRF. (since OpenTTD r20960)

The action itself is available since OpenTTD r20250. TTDPatch ignores the action since r2334, so no skipping is needed. The action is only allowed for GRF version 7 or above.

The action is processed while scanning for GRFs and their action 8 descriptions. This scanning stops when encountering an action 8, thus action 14 needs to appear earlier in the GRF.

-=Format=-

The data is provided using nestable chunks, and looks as follows:

-+<sprite-number> * <length> 14 <chunks ...> 00+-

Where <chunks ...> is one or a sequence of

-+"C" <identifier> <chunks ...> 00+-

-+"B" <identifier> <length> <binary-data>+-

-+"T" <identifier> <language-id> <text> 00+-

These three types of chunks define branch nodes (choices) and binary and textual leafs in a tree-like information structure. A piece of information is identified by the path in the information tree. E.g. the text leaf node at "INFO" -> "DESC" provides translatable descriptions for the GRF. It does not matter how many action 14 appear in a GRF, and which information is defined in which. Information with different identifier paths or same identifier paths (but e.g. different language-ids) can be set in the same action 14 or in multiple. If information is assigned to the same identifier-path multiple times, the information adds up resp. the last set information wins.

Chunks with unknown identifiers are just skipped including their subchunks. Following chunks are processed nevertheless.

Element	Size	Description
<sprite-number>	dec	A sequential sprite number
<length>	dec	The total number of bytes in the action
14	B	Action 14
<identifier>	4*B	Unique identifier for the chunk (see below)
<chunks ...>	*	Any number of sub chunks.
<length>	W	Number of bytes of binary data following.
<binary-data>	length*B	Binary data
<language-id>	B	Which of TTD's languages the text is used for, see action4. (only GRF version >= 7 language codes allowed)
<text>	S	Text data

Custom information for non-official extensions/patches ("CSTM" -> <extension-id> -> ...)

~pp~ -1 * -1   14 "C" "CSTM"

                 "C" <extension-id>

                     ... whatever suits you ...

                     00

                 00

             00~/pp~

Due to the purely-optional character of action 14 it is especially meant for non-official extensions/patches. However, to avoid conflicts custom additions should go into the "CSTM" chunk. Every extension may define its own subchunk with its own custom 4 byte <extension-id> below the "CSTM" chunk. The format of the subchunks below the <extension-id> chunk is freely defineable.

The information there could be used e.g. to notify an extension that the GRF knows about it. Consecutively the extension might then enable custom GRF features and notify the GRF about their existance e.g. via variable 8D. Versions of OpenTTD without the extension will then just skip the "CSTM" chunk and return the usual value in variable 8D.

GRF name ("INFO" -> "NAME") and description ("INFO" -> "DESC")

~pp~ -1 * -1   14 "C" "INFO"

                 "T" "NAME" <language-id> "Translatable GRF name" 00

                 "T" "DESC" <language-id> "Translatable GRF description" 00

                 00

             00~/pp~

Below the top-level chunk "INFO" you can use the leaf-chunks "NAME" and "DESC" to define name and description for additional languages. The information provided in action 8 is used for "other" languages (id 7F).

GRF palette ("INFO" -> "PALS")

~pp~ -1 * -1   14 "C" "INFO"

                 "B" "PALS" \w1 <palette>

                 00

             00~/pp~

Specifies the palette the sprites in the GRF are meant for.

<palette>	Meaning
"D"	DOS palette
"W"	Windows palette
"A"	Any palette. (e.g. when the GRF does not contain any sprites)

GRF version ("INFO" -> "VRSN")

~pp~ -1 * -1   14 "C" "INFO"

                 "B" "VRSN" \w4 \d<version>

                 00

             00~/pp~

Specifies the version of the GRF. This version is then used (by OpenTTD) to internally order GRFs with the same GRF ID. That order will determine which GRF is loading as "compatible" GRF and which GRFs to show in the list of GRFs. By default a GRF has version 0.

If all GRFs (with the same GRF ID) have version 0 all will be shown in the list of GRFs. If the highest version is shared by multiple GRFs one is randomly chosen as "compatible" GRF. As such it is important to prevent releasing multiple GRFs with the same version number.

If you set a version for the GRF, you should also set the 'minimal compatible version' MINV! Else it will default to the value of VRSN, which results in the GRF only being considered compatible to itself (resp. same version).

Minimal compatible GRF version ("INFO" -> "MINV")

~pp~ -1 * -1   14 "C" "INFO"

                 "B" "MINV" \w4 \d<version>

                 00

             00~/pp~

Specifies the minimal version of GRFs with the same GRF ID this GRF is still compatible with.

You have to set MINV after VRSN, and MINV has to be smaller or equal to VRSN.

When loading a game which used an older version of your GRF which is no longer installed, the newest installed version of your GRF will be picked which is still compatible to the version used before. Older GRFs are never considered compatible to GRFs with newer versions though.

If you do not set MINV, but set VRSN, then the GRF is only considered compatible to GRFs with the same version.

If you set MINV to 0, the GRF is also considered compatible to old GRFs without any version information (VRSN).

GRF parameters

This section describes how to specify information about GRF parameters, and what settings are stored in them. By default a GRF comes with 128 settings, that is a dword setting for every of the 128 GRF parameters.

Number of settings ("INFO" -> "NPAR")

~pp~ -1 * -1   14 "C" "INFO"

                 "B" "NPAR" \w1 <number-of-settings>

                 00

             00~/pp~

Defines the number of settings a GRF provides. This is independant from the number of allowed GRF parameters, as multiple settings might go into the same GRF parameter (e.g. bitmasks).

Setting name ("INFO" -> "PARA" -> <setting-number> -> "NAME") and description ("INFO" -> "PARA" -> <setting-number> -> "DESC")

~pp~ -1 * -1   14 "C" "INFO"

                 "C" "PARA"

                     "C" \d<setting-number>

                         "T" "NAME" <language-id> "Name of setting" 00

                         "T" "DESC" <language-id> "Setting description" 00

                         00

                     00

                 00

             00~/pp~

Defines a name for a setting.

The settings are numbered and identified using <setting-number>. Valid values are 0 up to ("INFO" -> "NPAR") - 1.

Setting to GRF parameter mapping ("INFO" -> "PARA" -> <setting-number> -> "MASK")

~pp~ -1 * -1   14 "C" "INFO"

                 "C" "PARA"

                     "C" \d<setting-number>

                         "B" "MASK" \w<length> \b <grf-parameter> [ \b <first-bit> [ \b <num-bit> ] ]

                         00

                     00

                 00

             00~/pp~

Specifies which GRF parameter is used to store a setting in.

<length>	A chunk length of 1 to 3 is allowed.
<grf-parameter>	GRF parameter (0 to 127) to store the setting in. Default value is the same as <setting-number>.
<first-bit>	First bit in the GRF parameter to use for the setting. Default value is "0".
<num-bit>	Number of bits to use for the setting in the GRF parameter. Default value is "32".

If you do not specify <first-bit> and <num-bit> the setting uses the whole GRF parameter by default. If you do not specify any "MASK" chunk at all, the setting will use the GRF parameter with the same number as <setting-number>.

So if you do not need to store multiple settings in one parameter, you do not need "MASK" chunks.

Note: You cannot store a setting across/using multiple GRF parameters.

Setting type ("INFO" -> "PARA" -> <setting-number> -> "TYPE")

~pp~ -1 * -1   14 "C" "INFO"

                 "C" "PARA"

                     "C" \d<setting-number>

                         "B" "TYPE" \w1 <setting-type>

                         00

                     00

                 00

             00~/pp~

Specifies the type of a setting.

<setting-type>	Meaning
0	Integer (unsigned) or enumeration. The GUI displays "<" and ">" buttons to change the setting resp. allows entering a value from a query window.
1	Boolean. The GUI displays a toggle button to switch the setting on or off.

The defaut value is "0".

Allowed value range ("INFO" -> "PARA" -> <setting-number> -> "LIMI")

~pp~ -1 * -1   14 "C" "INFO"

                 "C" "PARA"

                     "C" \d<setting-number>

                         "B" "LIMI" \w8 \d<minimum-value> \d<maximum-value>

                         00

                     00

                 00

             00~/pp~

Sets minimal and maximal allowed value for integer/enumeration settings.

The default values are "0" resp. "<nowiki>2 <pre> 32 - 1</nowiki>".

Enumeration values ("INFO" -> "PARA" -> <setting-number> -> "VALU")

~pp~ -1 * -1   14 "C" "INFO"

                 "C" "PARA"

                     "C" \d<setting-number>

                         "C" "VALU"

                             "T" \d<setting-value> <language-id> "Enumeration value" 00

                             ...

                             00

                         00

                     00

                 00

             00~/pp~

This chunk allows you to specify texts to display instead of the raw value for integer/enumeration. You can also specify texts only for some of the valid values. So if a setting e.g. allows values betweeen 0 to 42 you can instruct the GUI to show "none" instead of "0".

Default value ("INFO" -> "PARA" -> <setting-number> -> "DFLT")

Available since OpenTTD r20602.

~pp~ -1 * -1   14 "C" "INFO"

                 "C" "PARA"

                     "C" \d<setting-number>

                         "B" "DFLT" \w4 \d<value>

                         00

                     00

                 00

             00~/pp~

Sets the default value for a setting.

If you set "DFLT" for any setting the behavior of the "reset" functionality changes. Normally it would unset all parameters. If you have any "DFLT" field in your NewGRF then all parameters are unset after which all settings are set to their default value or to 0 if no default is provided. This means that using ActionD with opcode+80 doesn't work for any user-changeable parameter when you use a "DFLT" field.

This "reset" functionality happens when adding a NewGRF to a configuration or when the user presses the reset button in the parameter window.