GrfLoadingStages
Introduction
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 |  0.6  2.5 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 |  2.5 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 | ||||||
| 1 | ||||||
| 2 | ||||||
| 3 | ||||||
| 4 | ||||||
| 5 | ||||||
| 6 | ||||||
| 7 | ||||||
| 8 | When executed for an inactive file, skips remainder of file. | |||||
| 9 | ||||||
| A | ||||||
| B | ||||||
| C | ||||||
| D | ||||||
| E | ||||||
| F | ||||||
| 10 | ||||||
| 11 | ||||||
| 12 | If TTDPatch encounters any Action12 during any stage (including "Load"), Unicode handling is enabled. | |||||
| 13 | ||||||
| 14 | Processed by OpenTTD only when scanning for files. Not processed during the normal loading/activation. |
- ↑ During reservation stage especially cargo- and railtypes are reserved, so their existence can be tested by all GRFs in activation stage independent of loading order.
- ↑
0.6 
2.5 Processed during activation in TTDPatch 2.0.1 alpha 51 and later.
- ↑ Processed during initialization only if bit 7 of severity is set.
