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...> 00] [<data...>] 00 [<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, not present otherwise
<data>|B|Parameter to give to 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||
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 is a bit mask of the following bits:
||Bit|Value|Meaning
0|01|American
1|02|English
2|04|German
3|08|French
4|10|Spanish||
Use 1F (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")
FF|Custom message, use text from <message>||
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 unkown.
-=Example=-
Something to go here
