Difference between revisions of "Action14"
(No difference)
| |
Revision as of 13:33, 31 July 2010
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 20255)
The action itself is available since OpenTTD r20250. For TTDPatch you should currently skip it using action 9.
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. (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 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" \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".
