NML:GRF

2012-07-08T11:51:11Z

Hyronymus: Added an example of the string for providing an URL

{{NMLNavBlocksyntax}}

== GRF block ==

Syntax:

grf {
grfid: <literal-string>;
name: <string>;
desc: <string>;
[url: <string>;]
[version: <expression>;
[min_compatible_version: <expression>;]]
[param { ... }]
}

Mind: the items enclosed in [...] indicate optional lines: The [] itself are not part of the syntax.

== GRF parameters ==

As part of the grf block you can specify some parameter settings that the user will be able to change as part of the newgrf configuration. These can for example be used to disable parts of your NewGRF or to change between multiple graphics in case that's not possible at runtime. In general the settings (sub-)block looks like

param <num> {
<name> {
type: <type>;
name: <string>;
desc: <string>;
min_value: <expression>;
max_value: <expression>;
def_value: <expression>;
bit: <expression>;
names: {
0: <string>;
1: <string>;
.
.
.
};
}
}

Looking at the single entries:

<num>

Optional, you can specify in which param number this setting should be stored.

type

This defines the parameter type. Possible values are <code style="color:darkgreen">bool</code> for on/off statements or <code style="color:darkgreen">int</code> for positive integer values

name

This gives the parameter name as shown in the parameter configuration dialogue of OpenTTD.

desc

This gives the description which is displayed when the parameter is selected. Here you can explain the meaning and impact it will have

min_value

The minimum acceptable value for the parameter (only valid for type int), default of min_value is 0

max_value

The maximum acceptable value for the parameter (only valid for type int), default of max_value = 0xFFFFFFFF

def_value

This sets the default value for this parameter. If left out, the default value of 0 will be used.

bit

Only valid for settings with type "bool". The value is the bit in which this setting should be stored.

names

If you chose type <code style="color:darkgreen">int</code> and the numbers themselves are only used internally, have no direct numerical meaning and are better explained in words, you can use this to associate the single numbers with a string which describes it and is shown to the user instead of the value.

== A simple example ==

<pre style=example>
grf {
grfid: "AB\03\02";
name: string(STR_GRF_NAME);
desc: string(STR_GRF_DESC);
url: string(STR_GRF_URL);
version: 1;
min_compatible_version: 0;
param {
param_provide {
type: int;
name: string(STR_PARAM_PROVIDE);
desc: string(STR_PARAM_PROVIDE_DESC);
min_value: 0;
max_value: 1;
def_value: 0;
names: {
0: string(STR_PARAM_PROVIDE_ENGINES_AND_WAGONS);
1: string(STR_PARAM_PROVIDE_WAGONS_ONLY);
};
}
}
}</pre>

Action8

2004-01-22T17:24:40Z

Hyronymus:

'''''Action 8'''''

=Action 8=

Giving your .grf file an ID

-=Why does your .grf file need an ID?=-

There are many new graphic sets available to TTD players.  Of course, we need to make sure that we never get sets mixed up.  To make sure this will never happen you can set an ID.  Another useful feature of Action 8 is the ability to include useful information into the final .grf file. Here, we explain how Action 8 works.

-=Format=-

Like all other pseudo-sprites, Action 8 consists of hexadecimal bits. There is no limitation in the total amount of hexadecimal bits you can use in Action 8. One term does have a limit though. Let's give an example of what an Action 8 line looks like:

<pre>-+<Sprite-number> * <Length> <Action> <Version> <Grf-id> <Description> <Moreinfo>+-</pre>

Here is a short overview of what every term means:

||'''Byte'''|'''Description'''

<-+Sprite-number+-> |A sequential sprite number

<-+Length+-> |The total numer of bytes in the action

<-+Action+-> |Action type.  In this case, 08

<-+Version+-> |Graphics version

<-+Grf-id+-> |A unique ID for your .grf file

<-+Description+-> |A comment field, usually for .grf file name

<-+Moreinfo+-> |Another comment field, usually for copyright||

-=Filling in the terms=-

Now that you know what an Action 8 looks like it's time to explain how you should fill in the several terms in Action 8. It seems wise to discuss each term seperatly.

===Sprite-number===

Action 8 '''must be the first pseudosprite after the first line in the .NFO file'''. Remember that in the first line of the .NFO file you tell the computer how many (pseudo-)sprites there are in the .grf file. This first line is numbered 0 and doesn't count in the total amount of (pseudo-)sprites in the .NFO file. According to this, Action 8 will be sprite-number 1.

There is one exception to this rule. You can have several [[Action7|Action 7's]] before your first Action 8. If you have ''n'' Action 7's before Action 8, Action 8 will have spritenumber ''n+1''.

===Length===

The total numer of bytes in Action 8.  Start counting from <-+Action+->, the bit that sets the pseudo-sprite to act as the specified action.

===Action===

The type of action this pseudo-sprites defines. It should be 08 here because we want this pseudo-sprite to act as Action 8.

===Version===

This should be the graphics version that your file will support. Valid values are:

||'''TTDPatch version'''|'''Value'''

2.0r1 Stable TTDPatch + current alpha series|<center>05</center>

2.0    Stable TTDPatch|<center>04</center>

1.9.1 alpha 28 - 2.0 Stable TTDPatch|<center>01</center>

1.9.1 before alpha 28|<center>00</center>||

Entries for 00 and 01 are included only for completeness, and to aid with updating existing graphics.  They '''should not''' be used with new graphics. Using these old values may break future compatibility. Features have been added since these early versions and some early actions refer to other current actions.

===Grf-id===

This is a series of 4 bytes.  It's almost a convention to use the first two bytes for the creator's initials in ASCII code, e.g.  54 57 for "TW" (see below). The last two bytes should be numbers. This can be a version number, but you should take care if you plan on producing multiple sets.

===Description===

This comment field should contain a brief description of the set, converted into hexadecimal bytes, '''null-terminated (ending in 00)'''.  If you miss the final 00 here, this and other sprites may fail.

===Moreinfo===

This is an additional comment field to store even more information about the set, possibly for a brief copyright notice or other attribution. This field is also '''null-terminated'''.  If you miss the final 00 here, this and other sprites may fail.

-=Example=-

Below is an example of what a real Action 8 pseudo-sprite could look like.

<pre>-+1 * 43 08 05 54 57 01 06 20 54 75 74 6F 72 69 61 6C 20 65 78 61 6D 70 6C 65 00 20 43 6F 70 79 72 69 67 68 74 3A 20 53 79 73 74 65 6D 00+-</pre>

Let's clarify it bit by bit. In order to understand what the bits say you could use a hexadecimal editor.

||'''Byte'''|'''Meaning'''

<center>-+1+-</center>|<-+Sprite-number+->

<center>-+43+-</center>|<-+Length+-> of the action in bytes; start counting at 08 (<-+Action+->)

<center>-+08+-</center>|<-+Action+->: sets this pseudo-sprite to function as Action 8

<center>-+05+-</center>|<-+Version+->: this .grf file works with TTDPatch 2.0r1 + alpha series

<center>-+54 57 01 06+-</center>|<-+Grf-id+->: ASCII code for TW, then the numbers 1 and 6

<center>-+20 54 .. 65 00+-</center>|<-+Description+->, '''null-terminated ''': Tutorial example

<center>-+20 43 .. 6D 00+-</center>|<-+Moreinfo+->, '''null-terminated ''': Copyright: sytem||

GRFSpecs - User contributions [en-gb]

NML:GRF

Action8