Difference between revisions of "ActionB"

From GRFSpecs
Jump to navigationJump to search
m (12 revisions)
(fix links)
 
(6 intermediate revisions by 3 users not shown)
Line 1: Line 1:
  +
== Introduction ==
   
'''''Generate error messages'''''
 
 
=Action B=
 
   
 
Generate error messages.
 
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.
 
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.
   
  +
== Syntax ==
-=Format=-
 
   
 
The data looks as follows:
 
The data looks as follows:
   
<pre> -+&lt;Sprite-number&gt; * &lt;Length&gt; 0B &lt;severity&gt; &lt;language-id&gt; &lt;message-id&gt; <nowiki><nowiki>[&lt;message&gt;] [&lt;data&gt; [&lt;parnum&gt; [&lt;parnum&gt;]]]</nowiki></nowiki>+-</pre>
+
<Sprite-number> * <Length> 0B <severity> <language-id> <message-id> [<message>] [<data> [<parnum> [<parnum>]]]
   
  +
{|
||'''Element'''|[[GRFActionsDetailed|'''Size''']]|'''Description'''
 
  +
!Element!![[GRFActionsDetailed|Size]]!!Description
   
  +
|-
&lt;Sprite-number&gt;|dec|A sequential sprite number
 
  +
|<Sprite-number>||dec||A sequential sprite number
   
  +
|-
&lt;length&gt;|dec|The total number of bytes used in this action
 
  +
|<length>||dec||The total number of bytes used in this action
   
  +
|-
0B|B|Defines action 0B
 
  +
|0B||B||Defines action 0B
   
  +
|-
&lt;severity&gt;|B|How severe the message is (notice/warning/error/fatal error)
 
  +
|<severity>||B||How severe the message is (notice/warning/error/fatal error)
   
  +
|-
&lt;language-id&gt;|B|What languages to display this message for
 
  +
|<language-id>||B||What languages to display this message for
   
  +
|-
&lt;message-id&gt;|B|What message to show
 
  +
|<message-id>||B||What message to show
   
  +
|-
&lt;message&gt;|S|Text of a custom message, only present if &lt;message-id&gt;==FF
 
  +
|<message>||S||Text of a custom message, only present if <message-id>==FF
   
  +
|-
&lt;data&gt;|S|String to insert in built-in or custom messages
 
  +
|<data>||S||String to insert in built-in or custom messages
   
  +
|-
&lt;parnum&gt;|B|GRF parameter(s) to display in message||
 
  +
|<parnum>||B||GRF parameter(s) to display in message
  +
|}
   
  +
== Description ==
-=Filling in the terms=-
 
   
===Sprite-number===
+
=== Sprite-number ===
   
 
This is just the number you are at.
 
This is just the number you are at.
   
===Length===
+
=== Length ===
   
 
Count the number of bytes in this action.
 
Count the number of bytes in this action.
   
===severity===
+
=== severity ===
   
 
This sets how severe the message is.
 
This sets how severe the message is.
   
  +
{|
||Severity|Meaning|Prefix|Action taken
 
  +
!Severity!!Meaning!!Prefix!!Action taken
   
  +
|-
00|Notice|(none)|continue loading grf file
 
  +
|00||Notice||(none)||continue loading grf file
   
  +
|-
01|Warning|&quot;Warning: &quot;|continue loading grf file
 
  +
|01||Warning||"Warning: "||continue loading grf file
   
  +
|-
02|Error|&quot;Error: &quot;|continue loading grf file
 
  +
|02||Error||"Error: "||continue loading grf file
   
  +
|-
03|Fatal error|&quot;Error: &quot;|abort loading of grf file, and do not attempt again until patch is restarted||
 
  +
|03||Fatal error||"Error: "||abort loading of grf file
  +
|}
   
Normally Action B is ignored during initialization. If the severity has bit 7 set, a fatal action B will be applied even during initialization. &nbsp;This can be useful to prevent errors due to invalid sprites during initialization. &nbsp;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.
+
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 TTDPatch 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 &quot;/!\&quot; sign in the [[GRFStatusWindow|GRF Status window]]. The first fatal message during each activation is shown as a red popup box as well.
+
Messages are shown with a "/!\" sign in the GRF Status window ([[ttwiki:GRFStatusWindow|TTDPatch]], [[ottdwiki:NewGRF|OpenTTD]]). The first fatal message during each activation is shown as a red popup box as well.
   
===language-id===
+
=== language-id ===
   
 
This has the same format as the [[Action4#language-id|language-id in action 4]].
 
This has the same format as the [[Action4#language-id|language-id in action 4]].
Line 70: Line 84:
 
Use 7F (all languages) for built-in messages, because they are automatically using the right language.
 
Use 7F (all languages) for built-in messages, because they are automatically using the right language.
   
===message-id===
+
=== message-id ===
   
 
Set what kind of message to show. You have the following options:
 
Set what kind of message to show. You have the following options:
   
  +
{|
||Message ID|Content
 
  +
!Message ID!!Content
   
  +
|-
00|80 &quot; requires at least TTDPatch version &quot; 80 00
 
  +
|00||80 " requires at least TTDPatch version " 80 00
   
  +
|-
01|80 &quot; is for the &quot; 80 &quot; version of TTD.&quot; 00
 
  +
|01||80 " is for the " 80 " version of TTD." 00
   
  +
|-
|&lt;data&gt; should be &quot;DOS&quot; or &quot;Windows&quot;
 
  +
|||<data> should be "DOS" or "Windows"
   
  +
|-
02|80 &quot; is designed to be used with &quot; 80 00
 
  +
|02||80 " is designed to be used with " 80 00
   
  +
|-
|&lt;data&gt; should be a switchname + value, e.g. &quot;multihead 0&quot;
 
  +
|||<data> should be a switchname + value, e.g. "multihead 0"
   
  +
|-
03|&quot;Invalid parameter for &quot; 80 &quot;: parameter &quot; 80 &quot; (&quot; 7B &quot;)&quot; 00
 
  +
|03||"Invalid parameter for " 80 ": parameter " 80 " (" 7B ")" 00
   
  +
|-
|&lt;data&gt; should be the switch number written out (&quot;5&quot;)
 
  +
|||<data> should be the switch number written out ("5")
   
  +
|-
04|80 &quot; must be loaded before &quot; 80 &quot;.&quot; 00
 
  +
|04||80 " must be loaded before " 80 "." 00
   
  +
|-
05|80 &quot; must be loaded after &quot; 80 &quot;.&quot; 00
 
  +
|05||80 " must be loaded after " 80 "." 00
   
  +
|-
06|80 &quot; requires OpenTTD version &quot; 80 &quot; or better.&quot; 00
 
  +
|06||80 " requires OpenTTD version " 80 " or better." 00
   
  +
|-
FF|Custom message, use text from &lt;message&gt;||
 
  +
|FF||Custom message, use text from <message>
  +
|}
   
 
Message IDs 04 and 05 are available since TTDPatch 2.6 alpha 1 (r858).
 
Message IDs 04 and 05 are available since TTDPatch 2.6 alpha 1 (r858).
Line 102: Line 129:
 
Message ID 06 is available since OpenTTD r11330. This message should only be used when Action 7/9 variable 9D is 1 (OpenTTD).
 
Message ID 06 is available since OpenTTD r11330. This message should only be used when Action 7/9 variable 9D is 1 (OpenTTD).
   
===message===
+
=== message ===
   
 
Custom message text to show.
 
Custom message text to show.
   
===parnum===
+
=== parnum ===
   
 
Parameter numbers (up to two) to display instead of 7B in the message text.
 
Parameter numbers (up to two) to display instead of 7B in the message text.
   
-=Notes=-
+
=== 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 &lt;data&gt;. &nbsp;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 &lt;parnum&gt;. 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:
+
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:
   
<pre>(none)~pp~
+
<pre>(none)
   
 
80
 
80
Line 122: Line 149:
 
80 80 7B
 
80 80 7B
   
80 80 7B 7B~/pp~</pre>
+
80 80 7B 7B</pre>
   
 
Before, after, or in-between the bytes you may have arbitrary characters.
 
Before, after, or in-between the bytes you may have arbitrary characters.
Line 128: Line 155:
 
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.
 
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. &nbsp;All others will however be shown in the GRF Status window.
+
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. &nbsp;In earlier versions, the patch will display the &quot;invalid sprite&quot; error message anyway because the action is unknown.
+
Also note that since this action has only been introduced in TTDPatch 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=-
+
== Example ==
   
 
Below is an example of what a real Action B pseudo-sprite could look like, along with the [[Action7|Action 7]] required to skip it under the appropriate circumstances.
 
Below is an example of what a real Action B pseudo-sprite could look like, along with the [[Action7|Action 7]] required to skip it under the appropriate circumstances.
   
<pre>2 * 6 &nbsp;07 85 01 01 37 01
+
<pre>2 * 6 07 85 01 01 37 01
   
3 * 17 0B 03 7F 02 &quot;newtrains on&quot; 00</pre>
+
3 * 17 0B 03 7F 02 "newtrains on" 00</pre>
   
  +
{|
||'''Byte(s)'''|'''Name'''|'''Meaning'''
 
  +
!Byte(s)!!Name!!Meaning
   
  +
|-
07|&lt;action&gt;|Sets this pseudo-sprite to function as action 7
 
  +
|07||<action>||Sets this pseudo-sprite to function as action 7
   
  +
|-
85|&lt;variable&gt;|Check [[TTDPatchFlags|patch flags]]
 
  +
|85||<variable>||Check [[TTDPatchFlags|patch flags]]
   
  +
|-
01|&lt;size&gt;|variable size; ignored because this is a bit test
 
  +
|01||<size>||variable size; ignored because this is a bit test
   
  +
|-
01|&lt;cond&gt;|skip if bit is set
 
  +
|01||<cond>||skip if bit is set
   
  +
|-
37|&lt;val&gt;|check bit 37 (newtrains)
 
  +
|37||<val>||check bit 37 (newtrains)
   
  +
|-
01|&lt;num-sprites&gt;|skip one sprite
 
  +
|01||<num-sprites>||skip one sprite
   
  +
|-
0B|&lt;action&gt;|Sets this pseudo-sprite to function as action B
 
  +
|0B||<action>||Sets this pseudo-sprite to function as action B
   
  +
|-
03|&lt;severity&gt;|Sets this to a fatal error
 
  +
|03||<severity>||Sets this to a fatal error
   
  +
|-
7F|&lt;language-id&gt;|Execute this sprite for all languages
 
  +
|7F||<language-id>||Execute this sprite for all languages
   
  +
|-
02|&lt;message-id&gt;|Use message 02 (80 &quot; is designed to be used with &quot; 80)
 
  +
|02||<message-id>||Use message 02 (80 " is designed to be used with " 80)
   
  +
|-
&quot;newtrains on&quot; 00|&lt;data&gt;|String to insert in place of the second 80 in the message||
 
  +
|"newtrains on" 00||<data>||String to insert in place of the second 80 in the message
  +
|}

Latest revision as of 13:13, 13 November 2020

Introduction

Generate error messages.


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.

Syntax

The data looks as follows:

<Sprite-number> * <Length> 0B <severity> <language-id> <message-id> [<message>] [ [<parnum> [<parnum>]]]
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
S String to insert in built-in or custom messages
<parnum> B GRF parameter(s) to display in message

Description

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

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 TTDPatch 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 (TTDPatch, OpenTTD). 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
should be "DOS" or "Windows"
02 80 " is designed to be used with " 80 00
should be a switchname + value, e.g. "multihead 0"
03 "Invalid parameter for " 80 ": parameter " 80 " (" 7B ")" 00
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 . 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)

80

80 80

80 80 7B

80 80 7B 7B

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 TTDPatch 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 String to insert in place of the second 80 in the message