ActionB

Generate error messages

Action B

Generate error messages.

-=Introduction=-

With this action, you can alert the user to problems in the way the grf file is loaded, e.g. not in the right order, not the right patch version, or wrong parameters.

-=Format=-

The data looks as follows:

 -+<Sprite-number> * <Length> 0B <severity> <language-id> <message-id> <nowiki>[<message>] [<data> [<parnum> [<parnum>]]]</nowiki>+-

||Element|Size|Description

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

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

0B|B|Defines action 0B

<severity>|B|How severe the message is (notice/warning/error/fatal error)

<language-id>|B|What languages to display this message for

<message-id>|B|What message to show

<message>|S|Text of a custom message, only present if <message-id>==FF

<data>|S|String to insert in built-in or custom messages

<parnum>|B|GRF parameter(s) to display in message||

-=Filling in the terms=-

Sprite-number

This is just the number you are at.

Length

Count the number of bytes in this action.

severity

This sets how severe the message is.

||Severity|Meaning|Prefix|Action taken

00|Notice|(none)|continue loading grf file

01|Warning|"Warning: "|continue loading grf file

02|Error|"Error: "|continue loading grf file

03|Fatal error|"Error: "|abort loading of grf file, and do not attempt again until patch is restarted||

Normally Action B is ignored during initialization. If the severity has bit 7 set, a fatal action B will be applied even during initialization.  This can be useful to prevent errors due to invalid sprites during initialization.  Note that this only works properly since 2.0.1 alpha 66, for earlier versions the error popup that is shown is corrupted if bit 7 is set.

Messages are shown with a "/!\" sign in the GRF Status window. The first fatal message during each activation is shown as a red popup box as well.

language-id

This has the same format as the language-id in action 4.

Use 7F (all languages) for built-in messages, because they are automatically using the right language.

message-id

Set what kind of message to show. You have the following options:

||Message ID|Content

00|80 " requires at least TTDPatch version " 80 00

01|80 " is for the " 80 " version of TTD." 00

|<data> should be "DOS" or "Windows"

02|80 " is designed to be used with " 80 00

|<data> should be a switchname + value, e.g. "multihead 0"

03|"Invalid parameter for " 80 ": parameter " 80 " (" 7B ")" 00

|<data> should be the switch number written out ("5")

04|80 " must be loaded before " 80 "." 00

05|80 " must be loaded after " 80 "." 00

06|80 " requires OpenTTD version " 80 " or better." 00

FF|Custom message, use text from <message>||

Message IDs 04 and 05 are available since TTDPatch 2.6 alpha 1 (r858).

Message ID 06 is available since OpenTTD r11330. This message should only be used when Action 7/9 variable 9D is 1 (OpenTTD).

message

Custom message text to show.

parnum

Parameter numbers (up to two) to display instead of 7B in the message text.

-=Notes=-

In all messages (built-in and custom), the first 80 is replaced by the filename of the grf file, the second 80 is replaced by the content of <data>.  After the two 80 bytes, you may have one or two 7B bytes that are replaced by the value of the parameter(s) specified by <parnum>. Note that it is invalid to have a 7B before exactly two 80 bytes were encountered. This means the following combinations of special bytes are allowed:

(none)~pp~

80

80 80

80 80 7B

80 80 7B 7B~/pp~

Before, after, or in-between the bytes you may have arbitrary characters.

The advantage of the built-in messages is that they can be translated using the mkpttxt mechanism, whereas custom messages will only be available in the languages that come with the grf file.

Note that if several grf files attempt to show fatal error messages, only the first message is actually shown at the moment since TTD does not have a queue for the red error popups.  All others will however be shown in the GRF Status window.

Also note that since this action has only been introduced in 2.0.1 alpha 13, it makes no sense to check whether the version is at least alpha 13 if you want to use the error message 00.  In earlier versions, the patch will display the "invalid sprite" error message anyway because the action is unknown.

-=Example=-

Below is an example of what a real Action B pseudo-sprite could look like, along with the Action 7 required to skip it under the appropriate circumstances.

2 * 6  07 85 01 01 37 01

3 * 17 0B 03 7F 02 "newtrains on" 00

||Byte(s)|Name|Meaning

07|<action>|Sets this pseudo-sprite to function as action 7

85|<variable>|Check patch flags

01|<size>|variable size; ignored because this is a bit test

01|<cond>|skip if bit is set

37|<val>|check bit 37 (newtrains)

01|<num-sprites>|skip one sprite

0B|<action>|Sets this pseudo-sprite to function as action B

03|<severity>|Sets this to a fatal error

7F|<language-id>|Execute this sprite for all languages

02|<message-id>|Use message 02 (80 " is designed to be used with " 80)

"newtrains on" 00|<data>|String to insert in place of the second 80 in the message||