Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:NewGRF

From ReverseEngineering.wiki
Format
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, length bytes 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