Action6

Modify the contents of the following sprite

Action 6

Modify the contents of the following sprite

-=Introduction=-

Action 6 allows modifying the contents of the following sprite. It uses the values of the grf parameters and writes them into the data of the following sprite.

-=Format=-

The data looks as follows:

 -+<Sprite-number> * <Length> 06 (<param-num> <param-size> <offset>){n}  FF+-

||Element|Size|Description

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

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

06|B|Defines action 06

<param-num>|B|Which grf parameter to apply

<param-size>|B|How many bytes to overwrite

<offset>|B*|Which byte to overwrite

<FF>|B|Marks the end of the list||

The triplet of <param-num> <param-size> <offset> can be repeated as often as desired.

-=Filling in the terms=-

Sprite-number

This is just the number you are at.

Length

Count the number of bytes in this action.

param-num

This is the parameter number from the newgrf(w).cfg parameters to apply to the following sprite data. It can of course be the result of an ActionD calculation as well. The first parameter has number 00.

The modification is not carried out if the parameter has not been defined yet.

param-size

How many bytes of the parameter to use. If this is larger than 4 (the size of a parameter), the bytes of the following parameter are used. In that case, all required parameters must be defined or no modification will be done.

If this value has bit 7 set, the parameter is added to the destination value, instead of simply stored. This is useful especially when allocating sprites using the GRF Resource Management, because one typically allocates more than one sprite, but the parameter can only hold a single number, the first sprite allocated.  Thus, to apply several sprite numbers properly (such that it works for several activations, not just the first one), use an algorithm like the following:

• Suppose you have a sprite number <s> to which you want to add <i> (where <i> is returned by the GRF Resource Management)
• To make this work several times (whenever the grf is activated), you cannot simply add <i> to <s> directly
• Instead, use ActionD to define a new, otherwise unused parameter <j>, and store in it the value of <i> before it is set by Action D, i.e. <j> holds the previous value of <i>
• Next, after setting <i> with the GRF Resource Management, calculate <j> = <i> - <j> (i.e. subtract the previous value of i from the new value of i and store in j).
• Use Action 6 to add the value of <j> to <s>, instead of adding the value of <i> directly.
• This way, the new value <s> is the current value of <s> plus the new <i> minus the old <i>, which is the initial value of <s> plus the new <i>, just what we wanted.
• Skip the action D's as well as both action 6 and the action it modifies during the "test" stage by skipping these actions if action 7 var 84 has bit 10 set.
• Make sure that when using action 7/9, that either both or none of the above two operations are skipped. if only one but not the other is skipped, the values will go out of synch.

See below for an example.

offset

Number of byte in the following sprite to modify. The counting starts with 0 at the action byte and can go up to the length of the sprite. It is not possible to add data at the end of the sprite.

Since TTDPatch 2.0.1 alpha 51, this is an extended byte (see GRFActionsDetailed).

-=Notes=-

This action is processed only once during the initialization of a .grf file and is ignored during the following activations every time a game is started or loaded.  Therefore, to conditionally skip this action, you must use action 9 and not action 7.

Since 2.0.1 alpha 51, this is no longer true, Action 6 will be applied both at initialization as well as activation. You can therefore use either action 7 or 9 to skip it, whichever is appropriate.

-=Example=-

This is an example on how to apply the sprite numbers returned by the GRF Resource Management to an action 0:

~pp~// First, set param 1 (<j>) to the old value of param 0 (<i>)

  -1 * 5        0D 01 00 00 00

// Then, use the GRF Resource Management to reserve 3 sprites

  -1 * 9        0D 00 00 00 FE FF 08 03 00

// Now calculate <j> = <i> - <j>

  -1 * 5        0D 01 02 00 01

// So <j> = new <i> - old <i>

// Use Action 6 to add <j> to the sprite numbers in the sample sprite layout

  -1 * 11       06 01 84 07 01 84 11 01 84 1B FF

  -1 * 32       00 04 01 01 00 09

                       01

                       00 00 00 00     // first allocated sprite

                       00 00 00  10 05 02  01 00 00 00 // second allocated sprite

                       00 0B 00  10 05 02  02 00 00 00 // third

                       80

~/pp~