GrfLoadingStages

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
1		I		X
2		I		X
3		I		X
4		I		X
5				X
6		X	X	X	X
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
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.