Format:NewGRF
| Versions | container version 1 and 2 |
|---|---|
| Magic | 00 00 47 52 46 82 0D 0A 1A 0A (container version 2 only) |
| Extensions | .grf |
| Endianness | little |
| Website | https://www.openttd.org |
| On this wiki | Facts · Code · Notes · Topics |
The .grf graphics and game-data extension files of Transport Tycoon Deluxe, OpenTTD and TTDPatch: a container (version 1 without header, version 2 with the signature 'GRF' 82 0D 0A 1A 0A) holding real sprites and 'pseudo-sprites' (type 0xFF) whose first byte is one of the actions 0x00-0x14.
Overview
A NewGRF is a sequence of records. Each record is a length, a type byte and data. Records of type 0xFF are pseudo-sprites: a byte string whose first byte is the action number and which the game interprets (properties, sprite layouts, conditions, strings). All other types are real sprites (pixel data). OpenTTD loads a file in several stages (file scan, safety scan, label scan, init, reserve, activation) and calls the handler of each action in each stage.
Container versions
OpenTTD reads the start of the file: a u16 equal to 0 followed by the 8 bytes 'G' 'R' 'F' 0x82 0x0D 0x0A 0x1A 0x0A means container version 2; any other first u16 means container version 1, which has no header and starts with the first record. A version 2 file continues with a u32 offset (to the sprite section, relative to the position after this field), a compression byte (only 0 is supported; anything else is rejected with 'Unsupported compression format'), and then the records. Version 1 uses a u16 length per record, version 2 a u32 length.
Records
The first record is an info record: length 4, type 0xFF, then a u32 (the number of sprites, ignored by OpenTTD). Records follow until a length of 0 ends the list:
- type 0xFF: pseudo-sprite,
lengthbytes of data (OpenTTD limits them to 1 MiB); the first byte is the action number. Action byte 0xFF inside is a data block and 0xFE an import block, not actions. - type 0xFD (container version 2 only): a reference to the data section; length must be 4 and the data is the u32 sprite id looked up in the sprite section.
- any other type: a real sprite. In container version 1 the 7 bytes after the type byte are the sprite header (Unverified: zoom/type, height, width and the x and y offsets) and the pixel data follows, compressed in chunks if bit 1 (value 2) of the type byte is clear and stored raw if it is set. Container version 2 does not allow inline sprites: they live in the sprite section, whose entries are a u32 sprite id, a u32 length, a colour-component byte and a zoom byte.
Chunked sprite compression
When bit 1 of the type byte is clear, the data is a sequence of chunks: a signed byte i >= 0 gives a literal run of i bytes (0 means 128) that follows; i < 0 is a back reference whose length is -(i >> 3) and which is followed by one more byte (Unverified: the low bits of the back-reference offset). OpenTTD uses this only to skip over such data in SkipSpriteData.
Actions 0x00 to 0x14
OpenTTD dispatches pseudo-sprites to handlers numbered 0x00 to 0x14 (newgrf/newgrf_act0.cpp ... newgrf_act14.cpp; any other number is skipped with 'Skipping unknown action'). Unverified (names from the community NewGRF specification, not read in the source): 00 vehicle/station/house/etc. property changes (per feature), 01 define sprite sets, 02 sprite groups / random and variational selection, 03 feature id to group map, 04 names and strings, 05 new sprites for a standard sprite block, 06 modify a following action's bytes, 07 conditional skip, 08 GRF id and name/description, 09 conditional skip with stop, 0A replace sprites, 0B error message, 0C comment, 0D parameter arithmetic, 0E deactivate other GRFs, 0F town names, 10 label for jumps, 11 sound import, 12 sprite font definition, 13 translate GRF strings, 14 static info (the INFO node: name, description, version, min compatible version, parameters).
Pitfalls
- Real vs pseudo: the type byte, not the length, tells them apart.
- Unverified: action 0x06 patches the bytes of a later pseudo-sprite before it is decoded (OpenTTD keeps preloaded replacement data per GRF id and line number); a parser that reads records statically sees unpatched values.
Code & repositories
See Software:OpenTTD (GPL-2.0).
- https://github.com/OpenTTD/OpenTTD @
364d9b12b082b424de46423219188a52baf4e529· license: GPL-2.0-only (declared by the contributor; GitHub's detector did not recognize a license file)
OpenTTD source: NewGRF container, sprite loading, action handlers 0x00-0x14
Tested on: source read, not run: NewGRF files (not run) · checked 2026-10-18