GrfLoadingStages

Stages of loading a GRF file

The stages of loading a grf file

Processing of .grf files is done in several passes, most of which happen repeatedly, once per activations, which is whenever a game is started/loaded or the "Apply" button in the GRF Status Window is pressed. Each pass processes all files in the order they appear in the GRF Status Window.

Essentially, initialization is a two-pass system (first resolve jump targets, then initialize everything) that happens only once, activation is a two-pass system (first define cargos and reserve GRM IDs, then activate) that happens multiple times, and testing is a one-pass system run per click on a red/green flag in the GRF Status Window.

||Pass|Description

Post-Load|Run once after loading all files. Initializes the targets of action 7&9 (to resolve goto jumps), ignores all other actions.

Initialization|Run once after the post-load pass. Checks action 0 for validity, records action 1 sprite numbers, resolves action 2 references (to the sprite numbers within the grf file of action 1 sprites and references to variational/random action 2), executes actions 6, 9, B, D and F, initializes action 3, 4, 8 and 11, and ignores the rest of the actions (including in particular action 7).

Reserve|Called just before activation, to reserve GRM IDs. Also applies action 0 for cargos to make cargo labels valid to check in action 7/9 independent of order of .grf files. Ignores all actions except action 0 (for cargos), 6, 7, 8, 9, B, D and E.

Activate|Called during activation. Applies all actions except F and 10.

Test|Called when user clicks to enable/disable file in the GRF Status Window to check which other files react to the change. Ignores all actions except 6, 7, 8, 9, B, D and E.||

A .grf file is activated only if it was active when the game was started. If a game is loaded, only its active .grfs will be reactivated. A .grf file is considered active if its action 8 has been processed, i.e. its action 8 hasn't been skipped using an action 7.

The following table shows exactly which actions are excuted in which passes (X=action executed, I=action initialized, empty=action ignored).

||Action|Load|Init|Res|Act|Test|Notes

0| |

X

|

X*

|

X

| |During reservation stage especially cargo and railtype are reserved, so their existance can be tested by all GRFs in activation stage independent of loading order. 1| |

I

| |

X

| | 2| |

I

| |

X

| | 3| |

I

| |

X

| | 4| |

I

| |

X

| | 5| | | |

X

| | 6| |

X

|

X

|

X*

|

X

|Processed during activation in a51 and later. 7|

I

| |

X

|

X

|

X

| 8| |

I

|

X

|

X

|

X

|When executed for an inactive file, skips remainder of file. 9|

I

|

X

|

X

|

X

|

X

| A| | | |

X

| | B| |

X*

|

X

|

X

|

X

|Processed during initialization only if bit 7 of severity is set.

C| | | | | |

D| |

X

|

X

|

X

|

X

| E| | |

X

|

X

|

X

| F| |

X

| | | | 10|

X

| | | | | 11| |

I

| |

X

| | 12| | | |

X

| | If TTDPatch encounters any Action12 during any stage (including "Load"), Unicode handling is enabled. 13| | | |

X

| |

14| | | | | | Processed by OpenTTD only when scanning for files. Not processed during the normal loading/activation. ||