Difference between revisions of "ActionE"

From GRFSpecs
Jump to navigationJump to search
 
m (→‎Notes: Iconize also information that force-activation is not supported by OpenTTD)
 
(10 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
== Introduction ==
   
'''''Deactivate other graphics files or force activation of current file'''''
 
 
=Action E=
 
   
 
Deactivate other graphics files or force activation of current file.
 
Deactivate other graphics files or force activation of current file.
   
-=Introduction=-
 
   
 
Normally, graphics files should use [[Action7]] to deactivate themselves, if they find that other incompatible graphics have been loaded.
 
Normally, graphics files should use [[Action7]] to deactivate themselves, if they find that other incompatible graphics have been loaded.
Line 12: Line 9:
 
However, when new sets come out, it is often not feasible to change all existing sets so that they can detect the new set. This action therefore allows the new graphics set to deactivate older sets with which it is incompatible.
 
However, when new sets come out, it is often not feasible to change all existing sets so that they can detect the new set. This action therefore allows the new graphics set to deactivate older sets with which it is incompatible.
   
  +
== Syntax ==
-=Format=-
 
   
 
The data looks as follows:
 
The data looks as follows:
   
<pre> -+&lt;Sprite-number&gt; * &lt;Length&gt; 0E &lt;num&gt; &lt;grfids...&gt;+-</pre>
+
<Sprite-number> * <Length> 0E <num> <GRFIDs...>
   
  +
{|
||'''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.
   
  +
|-
0E|B|Defines action 0E
+
|0E||B||Defines action 0E
   
  +
|-
&lt;num&gt;|B|Number of sets which should be deactivated
+
|<num>||B||Number of sets which should be deactivated
   
  +
|-
&lt;grfids...&gt;|4*B|GRF IDs of the sets to deactivate||
+
|<GRFIDs...>||4*B||GRFIDs of the sets to deactivate
  +
|}
   
  +
== 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.
   
===num===
+
=== num ===
   
 
This is the number of sets you want to deactivate.
 
This is the number of sets you want to deactivate.
   
===grfids===
+
=== GRFIDs ===
   
Here you give the list of GRF IDs, in the same format as in [[Action8]], which should be deactivated.
+
Here you give the list of GRFIDs, in the same format as in [[Action8]], which should be deactivated.
   
-=Notes=-
+
=== Notes ===
   
Note that it is invalid to attempt the deactivation of already active graphics files. &nbsp;You can only prevent files lower down the newgrf(w).cfg from becoming active later. &nbsp;Therefore, you must check that none of the GRF IDs in this list are active already using the appropriate action 7. &nbsp;If the deactivation of an already active set is attempted, the current set is considered invalid and will be disabled.
+
Note that it is invalid to attempt the deactivation of already active graphics files. You can only prevent files lower down the newgrf(w).cfg from becoming active later. Therefore, you must check that none of the GRFIDs in this list are active already using the appropriate action 7. If the deactivation of an already active set is attempted, the current set is considered invalid and will be disabled.
   
 
If you attempt to deactivate a set that isn't loaded, nothing happens.
 
If you attempt to deactivate a set that isn't loaded, nothing happens.
Line 56: Line 60:
 
To handle the cases of incompatible sets being loaded and activated earlier, you can either attempt to overwrite all their settings and graphics, or simply deactivate this set in turn.
 
To handle the cases of incompatible sets being loaded and activated earlier, you can either attempt to overwrite all their settings and graphics, or simply deactivate this set in turn.
   
If the given GRFID is identical to the GRFID of the file currently being processed, the current file is force-activated. &nbsp;This is most useful for making changes to the title screen menu, which would otherwise not be possible. &nbsp;It is strongly recommended not to use this feature in any way other than in combination with an action 7 that checks variable 92 (game mode) so that the activation only happens in the title screen. &nbsp;Otherwise the GRF Status Windows (de)activation is bypassed entirely.
+
{{ottdp|no| }} If the given GRFID is identical to the GRFID of the file currently being processed, the current file is force-activated. This is most useful for making changes to the title screen menu, which would otherwise not be possible. It is strongly recommended not to use this feature in any way other than in combination with an action 7 that checks variable 92 (game mode) so that the activation only happens in the title screen. Otherwise the GRF Status Windows (de)activation is bypassed entirely. It is best to limit this forced activation to as few actions as possible for maximum compatibility. Forced activation is not supported by OpenTTD.
 
It is best to limit this forced activation to as few actions as possible for maximum compatibility.
 
   
 
In principle, there can be four cases and your .grf file must be able to handle all of them properly:
 
In principle, there can be four cases and your .grf file must be able to handle all of them properly:
 
* The .grf file is active and can not be deactivated.
 
* The .grf file is active and can not be deactivated.
 
: You cannot use action E in this case.
 
+ You cannot use action E in this case.
 
 
* The .grf file is inactive but will be activated.
 
* The .grf file is inactive but will be activated.
 
: This is the only case in which action E is useful, the .grf file coming below the current one in newgrf(w).cfg but being set to be activated. Action E will set it to not be activated when it is processed.
 
+ This is the only case in which action E is useful, the .grf file coming below the current one in newgrf(w).cfg but being set to be activated. Action E will set it to not be activated when it is processed.
 
 
* The .grf file is inactive and will not be activated.
 
* The .grf file is inactive and will not be activated.
 
: This can happen because it has been processed already (it comes earlier in newgrf(w).cfg) and was deactivated, either by default or manually.
   
 
== Example ==
+ This can happen because it has been processed already (it comes earlier in newgrf(w).cfg) and was deactivated, either by default or manually. Another possibility is that the file is disabled either by default or manually.
 
 
-=Example=-
 
   
 
The following is an example to deactivate GRFID 54570105 if possible, and deactivate the current file instead if not.
 
The following is an example to deactivate GRFID 54570105 if possible, and deactivate the current file instead if not.
   
<pre>-+ 47 * 9 07 88 04 06 54 57 01 05 02+-
+
47 * 9 07 88 04 06 54 57 01 05 02
 
48 * 9 07 88 04 08 54 57 01 05 03
 
-+ 48 * 9 07 88 04 08 54 57 01 05 03+-
+
49 * 6 07 83 01 03 7F 04
 
50 * x 0B 01 1F FF ... (e.g. "This file is deactivated because incompatible graphics are active.")
 
-+ 49 * 6 07 83 01 03 7F 04+-
+
51 * 6 07 83 01 03 7F 00
 
52 * x 0B 01 1F FF ... (e.g. "Deactivating GRFID 54570105.")
 
  +
53 * 6 0E 01 54 57 01 05
-+ 50 * x 0B 01 1F FF +-... (e.g. &quot;This file is deactivated because incompatible graphics are active.&quot;)
 
 
-+ 51 * 6 07 83 01 03 7F 00+-
 
 
-+ 52 * x 0B 01 1F FF +-... (e.g. &quot;Deactivating GRFID 54570105.&quot;)
 
 
-+ 53 * 6 0E 01 54 57 01 05+-</pre>
 
   
 
This carries out the following instructions:
 
This carries out the following instructions:
Line 97: Line 90:
 
49: goto 54
 
49: goto 54
   
50: showmessage(&quot;This file is deactivated because incompatible graphics are active.&quot;)
+
50: showmessage("This file is deactivated because incompatible graphics are active.")
   
 
51: deactivate_current_file
 
51: deactivate_current_file
   
52: showmessage(&quot;Deactivating GRFID 54570105.&quot;)
+
52: showmessage("Deactivating GRFID 54570105.")
   
 
53: deactivate(54570105);
 
53: deactivate(54570105);
Line 107: Line 100:
 
continue_with_current_file;</pre>
 
continue_with_current_file;</pre>
   
The reason for this particular order of pseudo-sprites is that action 7 will not take a branch if the queried GRFID is not present at all. &nbsp;In that case, both sprites 47 and 48 fall through, which means the jump in 49 is carried out and the file resumes processing. &nbsp;The unconditional gotos in 49 and 51 are actually conditional on the climate not being 7F, which it never can be.
+
The reason for this particular order of pseudo-sprites is that action 7 will not take a branch if the queried GRFID is not present at all. In that case, both sprites 47 and 48 fall through, which means the jump in 49 is carried out and the file resumes processing. The unconditional gotos in 49 and 51 are actually conditional on the climate not being 7F, which it never can be.
   
 
Conceptually, without goto-logic, the code could be described by
 
Conceptually, without goto-logic, the code could be described by
Line 113: Line 106:
 
<pre>if (GRFID 54570105 is active) {
 
<pre>if (GRFID 54570105 is active) {
   
&nbsp; &nbsp;showerror(&quot;This file is deactivated because incompatible graphics are active.&quot;)
+
showerror("This file is deactivated because incompatible graphics are active.")
   
 
deactivate_current_file
 
deactivate_current_file
Line 119: Line 112:
 
} else if (GRFID 54570105 is inactive but will be activated) {
 
} else if (GRFID 54570105 is inactive but will be activated) {
   
showmessage(&quot;Deactivating GRFID 54570105.&quot;)
+
showmessage("Deactivating GRFID 54570105.")
   
 
deactivate(54570105);
 
deactivate(54570105);

Latest revision as of 05:11, 8 October 2011

Introduction

Deactivate other graphics files or force activation of current file.


Normally, graphics files should use Action7 to deactivate themselves, if they find that other incompatible graphics have been loaded.

However, when new sets come out, it is often not feasible to change all existing sets so that they can detect the new set. This action therefore allows the new graphics set to deactivate older sets with which it is incompatible.

Syntax

The data looks as follows:

<Sprite-number> * <Length> 0E <num> <GRFIDs...>
Element Size Description
<Sprite-number> dec A sequential sprite number
<length> dec The total number of bytes used in this action.
0E B Defines action 0E
<num> B Number of sets which should be deactivated
<GRFIDs...> 4*B GRFIDs of the sets to deactivate

Description

Sprite-number

This is just the number you are at.

Length

Count the number of bytes in this action.

num

This is the number of sets you want to deactivate.

GRFIDs

Here you give the list of GRFIDs, in the same format as in Action8, which should be deactivated.

Notes

Note that it is invalid to attempt the deactivation of already active graphics files. You can only prevent files lower down the newgrf(w).cfg from becoming active later. Therefore, you must check that none of the GRFIDs in this list are active already using the appropriate action 7. If the deactivation of an already active set is attempted, the current set is considered invalid and will be disabled.

If you attempt to deactivate a set that isn't loaded, nothing happens.

To handle the cases of incompatible sets being loaded and activated earlier, you can either attempt to overwrite all their settings and graphics, or simply deactivate this set in turn.

Not supported by OpenTTD Supported by TTDPatch If the given GRFID is identical to the GRFID of the file currently being processed, the current file is force-activated. This is most useful for making changes to the title screen menu, which would otherwise not be possible. It is strongly recommended not to use this feature in any way other than in combination with an action 7 that checks variable 92 (game mode) so that the activation only happens in the title screen. Otherwise the GRF Status Windows (de)activation is bypassed entirely. It is best to limit this forced activation to as few actions as possible for maximum compatibility. Forced activation is not supported by OpenTTD.

In principle, there can be four cases and your .grf file must be able to handle all of them properly:

  • The .grf file is active and can not be deactivated.
You cannot use action E in this case.
  • The .grf file is inactive but will be activated.
This is the only case in which action E is useful, the .grf file coming below the current one in newgrf(w).cfg but being set to be activated. Action E will set it to not be activated when it is processed.
  • The .grf file is inactive and will not be activated.
This can happen because it has been processed already (it comes earlier in newgrf(w).cfg) and was deactivated, either by default or manually.

Example

The following is an example to deactivate GRFID 54570105 if possible, and deactivate the current file instead if not.

47 * 9 07 88 04 06 54 57 01 05 02
48 * 9 07 88 04 08 54 57 01 05 03
49 * 6 07 83 01 03 7F 04
50 * x 0B 01 1F FF ... (e.g. "This file is deactivated because incompatible graphics are active.")
51 * 6 07 83 01 03 7F 00
52 * x 0B 01 1F FF ... (e.g. "Deactivating GRFID 54570105.")
53 * 6 0E 01 54 57 01 05

This carries out the following instructions:

47: if (GRFID 54570105 is active) goto 50

48: if (GRFID 54570105 is inactive but will be activated) goto 52

49: goto 54

50: showmessage("This file is deactivated because incompatible graphics are active.")

51: deactivate_current_file

52: showmessage("Deactivating GRFID 54570105.")

53: deactivate(54570105);

continue_with_current_file;

The reason for this particular order of pseudo-sprites is that action 7 will not take a branch if the queried GRFID is not present at all. In that case, both sprites 47 and 48 fall through, which means the jump in 49 is carried out and the file resumes processing. The unconditional gotos in 49 and 51 are actually conditional on the climate not being 7F, which it never can be.

Conceptually, without goto-logic, the code could be described by

if (GRFID 54570105 is active) {

 showerror("This file is deactivated because incompatible graphics are active.")

deactivate_current_file

} else if (GRFID 54570105 is inactive but will be activated) {

showmessage("Deactivating GRFID 54570105.")

deactivate(54570105);

}