Action6

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.

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 TTDPatch 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.

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.

Description

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  2.5, this is an extended byte (see GRFActionsDetailed).

Example

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

// 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