GrfLoadingStages

From GRFSpecs
Jump to: navigation, search

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 Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.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 Not supported by OpenTTD Supported by TTDPatch 2.52.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
X
X[1]
X
1
I
X
2
I
X
3
I
X
4
I
X
5
X
6
X
X
X[2]
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[3]
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.
  1. 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.
  2. Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.5 (2.0.1 alpha 51)2.5 Processed during activation in TTDPatch 2.0.1 alpha 51 and later.
  3. Processed during initialization only if bit 7 of severity is set.