Difference between revisions of "Action14"

From GRFSpecs
Jump to navigationJump to search
m (change palette naming DOS->default and windows->legacy to match OpenTTD's naming of those)
 
(8 intermediate revisions by 4 users not shown)
Line 9: Line 9:
 
Currently this action can be used to define
 
Currently this action can be used to define
 
* {{ottdp|1.1|no|ottdrev=r20250}} translations for the name and description of the GRF. (Those from action 8)
 
* {{ottdp|1.1|no|ottdrev=r20250}} translations for the name and description of the GRF. (Those from action 8)
* {{ottdp|1.1|no|ottdrev=r20254}} the palette (DOS, Windows) the GRF needs, or whether the palette does not matter.
+
* {{ottdp|1.1|no|ottdrev=r20254}} the palette (default (=DOS), legacy (=Windows)) the GRF needs, or whether the palette does not matter.
  +
* {{ottdp|1.2|no|ottdrev=r23001}} the colour depth (8bpp, 32bpp) the GRF needs
 
* {{ottdp|1.1|no|ottdrev=r20255}} the number, format and purpose of GRF parameters. (allowed values, names, descriptions, ...)
 
* {{ottdp|1.1|no|ottdrev=r20255}} the number, format and purpose of GRF parameters. (allowed values, names, descriptions, ...)
 
* {{ottdp|1.1|no|ottdrev=r20960}} version information and compatibility to older versions of the same GRF.
 
* {{ottdp|1.1|no|ottdrev=r20960}} version information and compatibility to older versions of the same GRF.
  +
* {{ottdp|1.2|no|ottdrev=r23494}} website url that can be opened in-game.
   
 
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 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.
Line 52: Line 54:
 
| B
 
| B
 
| Action 14
 
| Action 14
 
|-
 
| <chunks ...>
 
| *
 
| Any number of sub chunks.
 
|-
 
|-
 
| "C"/"B"/"T"
 
| "C"/"B"/"T"
Line 60: Line 66:
 
| 4*B
 
| 4*B
 
| Unique identifier for the chunk (see below)
 
| Unique identifier for the chunk (see below)
|-
 
| <chunks ...>
 
| *
 
| Any number of sub chunks.
 
 
|-
 
|-
 
| <length>
 
| <length>
Line 97: Line 99:
   
 
=== GRF name ("INFO" -> "NAME") and description ("INFO" -> "DESC") ===
 
=== GRF name ("INFO" -> "NAME") and description ("INFO" -> "DESC") ===
  +
{{ottdp|1.1|no|ottdrev=r20250}}
 
 
<pre>-1 * -1 14 "C" "INFO"
 
<pre>-1 * -1 14 "C" "INFO"
 
"T" "NAME" <language-id> "Translatable GRF name" 00
 
"T" "NAME" <language-id> "Translatable GRF name" 00
Line 106: Line 108:
 
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).
 
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") ===
+
=== GRF website ("INFO" -> "URL_") ===
  +
{{ottdp|1.2|no|ottdrev=r23494}}
  +
<pre>-1 * -1 14 "C" "INFO"
  +
"T" "URL_" <language-id> "http://www.example.org" 00
  +
00
  +
00</pre>
   
  +
You can use the "URL_" chunk to provide an url for this grf. You can translate this like the name and description to provide a localized website.
  +
  +
  +
=== GRF palette ("INFO" -> "PALS") ===
  +
{{ottdp|1.1|no|ottdrev=r20254}}
 
<pre>-1 * -1 14 "C" "INFO"
 
<pre>-1 * -1 14 "C" "INFO"
 
"B" "PALS" \w1 <palette>
 
"B" "PALS" \w1 <palette>
Line 121: Line 133:
 
|-
 
|-
 
|"D"
 
|"D"
|DOS palette
+
|Default (DOS) palette
 
|-
 
|-
 
|"W"
 
|"W"
|Windows palette
+
|Legacy (Windows) palette
 
|-
 
|-
 
|"A"
 
|"A"
Line 130: Line 142:
 
|}
 
|}
   
=== GRF version ("INFO" -> "VRSN") ===
+
=== GRF colour depth ("INFO" -> "BLTR") ===
  +
{{ottdp|1.2|no|ottdrev=r23001}}
  +
<pre>-1 * -1 14 "C" "INFO"
  +
"B" "BLTR" \w1 <blitter>
  +
00
  +
00</pre>
   
  +
Specifies the preferred blitter for a NewGRF. If not given, it will default to the 8 bpp blitter.
  +
  +
This is only a hint, OpenTTD may still select another blitter if necessary. Only 8 bpp sprites are guaranteed to work with any blitter.
  +
  +
{| class="wikitable"
  +
|-
  +
!'''<blitter>'''
  +
!'''Meaning'''
  +
|-
  +
|"8"
  +
|8 bpp blitter
  +
|-
  +
|"3"
  +
|32 bpp blitter
  +
|}
  +
  +
=== GRF version ("INFO" -> "VRSN") ===
  +
{{ottdp|1.1|no|ottdrev=r20259}}
 
<pre>-1 * -1 14 "C" "INFO"
 
<pre>-1 * -1 14 "C" "INFO"
 
"B" "VRSN" \w4 \d<version>
 
"B" "VRSN" \w4 \d<version>
Line 137: Line 172:
 
00</pre>
 
00</pre>
   
Specifies the version of the GRF. This version is then used (by OpenTTD) to internally order GRFs with the same GRFID. 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.
+
Specifies the [[Version_numbers#Version_of_a_specific_NewGRF|version of the GRF]]. This version is then used (by OpenTTD) to internally order GRFs with the same GRFID. 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 GRFID) 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 all GRFs (with the same GRFID) 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.
Line 144: Line 179:
   
 
=== Minimal compatible GRF version ("INFO" -> "MINV") ===
 
=== Minimal compatible GRF version ("INFO" -> "MINV") ===
  +
{{ottdp|1.1|no|ottdrev=r20960}}
 
 
<pre>-1 * -1 14 "C" "INFO"
 
<pre>-1 * -1 14 "C" "INFO"
 
"B" "MINV" \w4 \d<version>
 
"B" "MINV" \w4 \d<version>
Line 150: Line 185:
 
00</pre>
 
00</pre>
   
Specifies the minimal version of GRFs with the same GRFID this GRF is still compatible with.
+
Specifies the minimal [[Version_numbers#Version_of_a_specific_NewGRF|version of GRFs]] with the same GRFID this GRF is still compatible with.
   
 
You have to set MINV after VRSN, and MINV has to be smaller or equal to VRSN.
 
You have to set MINV after VRSN, and MINV has to be smaller or equal to VRSN.
Line 165: Line 200:
   
 
==== Number of settings ("INFO" -> "NPAR") ====
 
==== Number of settings ("INFO" -> "NPAR") ====
  +
{{ottdp|1.1|no|ottdrev=r20251}}
 
 
<pre>-1 * -1 14 "C" "INFO"
 
<pre>-1 * -1 14 "C" "INFO"
 
"B" "NPAR" \w1 <number-of-settings>
 
"B" "NPAR" \w1 <number-of-settings>
Line 173: Line 208:
   
 
==== Setting name ("INFO" -> "PARA" -> <setting-number> -> "NAME") and description ("INFO" -> "PARA" -> <setting-number> -> "DESC") ====
 
==== Setting name ("INFO" -> "PARA" -> <setting-number> -> "NAME") and description ("INFO" -> "PARA" -> <setting-number> -> "DESC") ====
  +
{{ottdp|1.1|no|ottdrev=r20255}}
 
 
<pre>-1 * -1 14 "C" "INFO"
 
<pre>-1 * -1 14 "C" "INFO"
 
"C" "PARA"
 
"C" "PARA"
Line 189: Line 224:
   
 
==== Setting to GRF parameter mapping ("INFO" -> "PARA" -> <setting-number> -> "MASK") ====
 
==== Setting to GRF parameter mapping ("INFO" -> "PARA" -> <setting-number> -> "MASK") ====
  +
{{ottdp|1.1|no|ottdrev=r20255}}
 
 
<pre>-1 * -1 14 "C" "INFO"
 
<pre>-1 * -1 14 "C" "INFO"
 
"C" "PARA"
 
"C" "PARA"
Line 223: Line 258:
   
 
==== Setting type ("INFO" -> "PARA" -> <setting-number> -> "TYPE") ====
 
==== Setting type ("INFO" -> "PARA" -> <setting-number> -> "TYPE") ====
  +
{{ottdp|1.1|no|ottdrev=r20255}}
 
 
<pre>-1 * -1 14 "C" "INFO"
 
<pre>-1 * -1 14 "C" "INFO"
 
"C" "PARA"
 
"C" "PARA"
Line 251: Line 286:
   
 
==== Allowed value range ("INFO" -> "PARA" -> <setting-number> -> "LIMI") ====
 
==== Allowed value range ("INFO" -> "PARA" -> <setting-number> -> "LIMI") ====
  +
{{ottdp|1.1|no|ottdrev=r20255}}
 
 
<pre>-1 * -1 14 "C" "INFO"
 
<pre>-1 * -1 14 "C" "INFO"
 
"C" "PARA"
 
"C" "PARA"
Line 266: Line 301:
   
 
==== Enumeration values ("INFO" -> "PARA" -> <setting-number> -> "VALU") ====
 
==== Enumeration values ("INFO" -> "PARA" -> <setting-number> -> "VALU") ====
  +
{{ottdp|1.1|no|ottdrev=r20255}}
 
 
<pre>-1 * -1 14 "C" "INFO"
 
<pre>-1 * -1 14 "C" "INFO"
 
"C" "PARA"
 
"C" "PARA"
Line 280: Line 315:
   
 
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".
 
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".
  +
  +
{{ottdp|1.3|no}} If you specify texts for all allowed values (according to "LIMI"), then a dropdown box is displayed instead of [<][>] buttons.
   
 
==== Default value ("INFO" -> "PARA" -> <setting-number> -> "DFLT") ====
 
==== Default value ("INFO" -> "PARA" -> <setting-number> -> "DFLT") ====
  +
{{ottdp|1.1|no|ottdrev=r20602}}
 
Available since OpenTTD r20602.
 
 
 
<pre>-1 * -1 14 "C" "INFO"
 
<pre>-1 * -1 14 "C" "INFO"
 
"C" "PARA"
 
"C" "PARA"

Latest revision as of 12:42, 18 December 2013

Static GRF Information

Introduction

Static GRF Information

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

  • Supported by OpenTTD 1.1 (r20250)1.1 Not supported by TTDPatch translations for the name and description of the GRF. (Those from action 8)
  • Supported by OpenTTD 1.1 (r20254)1.1 Not supported by TTDPatch the palette (default (=DOS), legacy (=Windows)) the GRF needs, or whether the palette does not matter.
  • Supported by OpenTTD 1.2 (r23001)1.2 Not supported by TTDPatch the colour depth (8bpp, 32bpp) the GRF needs
  • Supported by OpenTTD 1.1 (r20255)1.1 Not supported by TTDPatch the number, format and purpose of GRF parameters. (allowed values, names, descriptions, ...)
  • Supported by OpenTTD 1.1 (r20960)1.1 Not supported by TTDPatch version information and compatibility to older versions of the same GRF.
  • Supported by OpenTTD 1.2 (r23494)1.2 Not supported by TTDPatch website url that can be opened in-game.

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.

Syntax

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 (containers) 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
<chunks ...> * Any number of sub chunks.
"C"/"B"/"T" B chunk type (container/binary/text)
<identifier> 4*B Unique identifier for the chunk (see below)
<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

Descriptions

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

-1 * -1   14 "C" "CSTM"
                 "C" <extension-id>
                     ... whatever suits you ...
                     00
                 00
             00

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")

Supported by OpenTTD 1.1 (r20250)1.1 Not supported by TTDPatch

-1 * -1   14 "C" "INFO"
                 "T" "NAME" <language-id> "Translatable GRF name" 00
                 "T" "DESC" <language-id> "Translatable GRF description" 00
                 00
             00

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 website ("INFO" -> "URL_")

Supported by OpenTTD 1.2 (r23494)1.2 Not supported by TTDPatch

-1 * -1   14 "C" "INFO"
                 "T" "URL_" <language-id> "http://www.example.org" 00
                 00
             00

You can use the "URL_" chunk to provide an url for this grf. You can translate this like the name and description to provide a localized website.


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

Supported by OpenTTD 1.1 (r20254)1.1 Not supported by TTDPatch

-1 * -1   14 "C" "INFO"
                 "B" "PALS" \w1 <palette>
                 00
             00

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

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

GRF colour depth ("INFO" -> "BLTR")

Supported by OpenTTD 1.2 (r23001)1.2 Not supported by TTDPatch

-1 * -1   14 "C" "INFO"
                 "B" "BLTR" \w1 <blitter>
                 00
             00

Specifies the preferred blitter for a NewGRF. If not given, it will default to the 8 bpp blitter.

This is only a hint, OpenTTD may still select another blitter if necessary. Only 8 bpp sprites are guaranteed to work with any blitter.

<blitter> Meaning
"8" 8 bpp blitter
"3" 32 bpp blitter

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

Supported by OpenTTD 1.1 (r20259)1.1 Not supported by TTDPatch

-1 * -1   14 "C" "INFO"
                 "B" "VRSN" \w4 \d<version>
                 00
             00

Specifies the version of the GRF. This version is then used (by OpenTTD) to internally order GRFs with the same GRFID. 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 GRFID) 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")

Supported by OpenTTD 1.1 (r20960)1.1 Not supported by TTDPatch

-1 * -1   14 "C" "INFO"
                 "B" "MINV" \w4 \d<version>
                 00
             00

Specifies the minimal version of GRFs with the same GRFID 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")

Supported by OpenTTD 1.1 (r20251)1.1 Not supported by TTDPatch

-1 * -1   14 "C" "INFO"
                 "B" "NPAR" \w1 <number-of-settings>
                 00
             00

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")

Supported by OpenTTD 1.1 (r20255)1.1 Not supported by TTDPatch

-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

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")

Supported by OpenTTD 1.1 (r20255)1.1 Not supported by TTDPatch

-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

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")

Supported by OpenTTD 1.1 (r20255)1.1 Not supported by TTDPatch

-1 * -1   14 "C" "INFO"
                 "C" "PARA"
                     "C" \d<setting-number>
                         "B" "TYPE" \w1 <setting-type>
                         00
                     00
                 00
             00

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")

Supported by OpenTTD 1.1 (r20255)1.1 Not supported by TTDPatch

-1 * -1   14 "C" "INFO"
                 "C" "PARA"
                     "C" \d<setting-number>
                         "B" "LIMI" \w8 \d<minimum-value> \d<maximum-value>
                         00
                     00
                 00
             00

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

The default values are "0" resp. "2^32 - 1".

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

Supported by OpenTTD 1.1 (r20255)1.1 Not supported by TTDPatch

-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

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".

Supported by OpenTTD 1.31.3 Not supported by TTDPatch If you specify texts for all allowed values (according to "LIMI"), then a dropdown box is displayed instead of [<][>] buttons.

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

Supported by OpenTTD 1.1 (r20602)1.1 Not supported by TTDPatch

-1 * -1   14 "C" "INFO"
                 "C" "PARA"
                     "C" \d<setting-number>
                         "B" "DFLT" \w4 \d<value>
                         00
                     00
                 00
             00

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.