Difference between revisions of "NML:GRF"

From GRFSpecs
Jump to navigationJump to search
m (one common example is better)
m (→‎GRF block: must be first block. Actions before that are invalid.)
 
(6 intermediate revisions by 4 users not shown)
Line 11: Line 11:
 
version: <expression>;
 
version: <expression>;
 
min_compatible_version: <expression>;
 
min_compatible_version: <expression>;
<param { ... }>
+
[url: <string>;]
  +
[param { ... }]
 
}
 
}
  +
  +
Mind: the items enclosed in [...] indicate optional lines: The [] itself are not part of the syntax.
  +
The grf block must be the first block within a NewGRF.
  +
  +
Concerning the choice of the <code style="color:darkgreen">grfid</code>, see [[Action8#GRFID|these]] guidelines
   
 
== GRF parameters ==
 
== GRF parameters ==
Line 18: Line 24:
 
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
 
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 {
+
param &lt;num&gt; {
 
&lt;name&gt; {
 
&lt;name&gt; {
 
type: &lt;type&gt;;
 
type: &lt;type&gt;;
Line 26: Line 32:
 
max_value: &lt;expression&gt;;
 
max_value: &lt;expression&gt;;
 
def_value: &lt;expression&gt;;
 
def_value: &lt;expression&gt;;
  +
bit: &lt;expression&gt;;
 
names: {
 
names: {
 
0: &lt;string&gt;;
 
0: &lt;string&gt;;
Line 37: Line 44:
   
 
Looking at the single entries:
 
Looking at the single entries:
  +
  +
&lt;num&gt;
  +
  +
Optional, you can specify in which param number this setting should be stored.
   
 
type
 
type
Line 52: Line 63:
 
min_value
 
min_value
   
The minimum acceptable value for the parameter (makes only sense for type int)
+
The minimum acceptable value for the parameter (only valid for type int), default of min_value is 0
   
 
max_value
 
max_value
   
The maximum acceptable value for the parameter (makes only sense for type int)
+
The maximum acceptable value for the parameter (only valid for type int), default of max_value = 0xFFFFFFFF
   
 
def_value
 
def_value
   
 
This sets the default value for this parameter. If left out, the default value of 0 will be used.
 
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
 
names
Line 73: Line 88:
 
name: string(STR_GRF_NAME);
 
name: string(STR_GRF_NAME);
 
desc: string(STR_GRF_DESC);
 
desc: string(STR_GRF_DESC);
  +
url: string(STR_GRF_URL);
 
version: 1;
 
version: 1;
 
min_compatible_version: 0;
 
min_compatible_version: 0;

Latest revision as of 07:18, 11 April 2015

Block Syntax

GRF block

Syntax:

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

Mind: the items enclosed in [...] indicate optional lines: The [] itself are not part of the syntax. The grf block must be the first block within a NewGRF.

Concerning the choice of the grfid, see these guidelines

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 bool for on/off statements or int 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 int 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

 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);
 			};
 		}
	}
}