GRF coding

Revision as of 22:30, 18 June 2009

Writing NFO for smarties. Because you're not as dumb as you think you are.

Okay, welcome to my basic tutorial for coding grf sets.

What you will need

• A recent (ie, nightly) build of TTDPatch or, if you must, OpenTTD.
• GRFCodec
• NFORenum
• A coder's text editor (preferably something more advanced than notepad, since you'll want to be doing some formatting to make your NFO readable. NOT a rich text editor like wordpad).
• A graphics program of your choice that can manipulate .pcx and/or .png files.
• The newgrf spec.
• A computer running Windows, and/or the ability to translate what I say in Windows-speak into the language of your operating system. Creating and testing grfs on non-Windows systems may have additional challenges.

Getting set up

• Install grfcodec into a directory under/near your TTD directory.
• Copy trg1r.grf to this directory (and, if you like, the other default grfs) and decompile them with grfcodec. (grfcodec -d trg1r.grf -p2).
  • Resist the temptation to decode any other grf and have a look at what comes out. It will not be useful to you at this point. Believe me.
• Install NFOrenum into <grfcodec directory>/SPRITES, which should have been created when you decoded trg1r.grf.

And you're ready to go!

Getting started

Every grf file comes from an NFO file; the NFO file is, in essence, the source code of the grf. NFO files contain series of hex digits; however; don't let this put you off, as you can use comments, formatting, escape codes and quoted strings to make your NFO more human-readable.

Let's begin your first NFO file. Open your text editor and create a new file. Save it in <grfcodec directory>/SPRITES as <filename>.nfo

There are three things every NFO file must contain, other than the sprite lines that actually have data for vehicles or other features. They are the header, sprite 0 and the action 8.

The header

The header tells grfcodec how to encode the NFO. It looks like this:

// Automatically generated by GRFCODEC. Do not modify!
// (Info version 7)
// Format: spritenum pcxfile xpos ypos compression ysize xsize xrel yrel

You can copy and paste that, or alternatively you can let NFOrenum put the header in the first time you renum your file.

Sprite 0

This sprite follows after the header, and tells grfcodec the total sprite count. NFOrenum will insert this sprite.

The action 8

Read the wiki page

The action 8 identifies your grf file. It's like the title page of a book.

An action 8 might look like this:

1 * 1	 08 07 "JB01" "My first Newgrf" 00 "By Joe Bloggs" 00

"JB01" is the grfid. It's important that every grf has a different ID: most grf authors use their intials for the first two characters.

Anatomy of an NFO

Asides from the header, sprite 0 and action 8, you need some sprites and psuedosprites that actually do something.

• A vehicle (NFO)
• Example NFO files

Compiling the grf

Hopefully you can work out how to do this yourself. However, here's a few tips:

• Always renum your nfo file before compiling, and check for errors (search the file for !!). I use a batch (.bat) file like this example to renum and compile my NFO in one easy step:

cd sprites
renum mygrf.nfo
cd ..
grfcodec -e -c mygrf.grf

If errors are found, I delete the .grf, fix the errors, and run the .bat again.

• Don't worry about sprite numbers and lengths: NFOrenum will fix them up.
• Don't decompile your own grf files! You'll wreck your NFO, stripping out all formatting and comments.