Difference between revisions of "NMLTutorial/Parameters"

From TTWiki
Jump to navigationJump to search
(parameters: boolean parameters explained.)
 
(→‎Enumeration parameter: example was missing type)
 
(3 intermediate revisions by 2 users not shown)
Line 19: Line 19:
 
</pre>
 
</pre>
   
Where <tt>name</tt> is the name the parameter is referenced further within the grf to read this parameter. <num> is the number of this parameter. The meaning of the <num> parameter should should remain constant throughout versions of the same NewGRF or the NewGRF might become incompatible with previous versions of the same NewGRF (thus you'd need to change min_compatible_version if you change the meaning of the parameters at <num>.
+
Where <code>name</code> is the name the parameter is referenced further within the grf to read this parameter. <num> is the number of this parameter. The <num> parameter is optional and not needed when parameters are not re-ordered throughout versions. It can be used to keep the meaning of a specific NewGRF parameter while re-ordering the code. The meaning of a NewGRF parameter should should remain constant throughout versions of the same NewGRF or the NewGRF might become incompatible with previous versions of the same NewGRF (thus you'd need to change min_compatible_version if you change the meaning of the parameters at <num>.
   
 
== Parameter types ==
 
== Parameter types ==
Line 44: Line 44:
   
 
=== Numeric parameter ===
 
=== Numeric parameter ===
  +
  +
The numeric parameter allows to directly input an (integer) number. It needs to have a minimum and maximum value given and optionally - and usually a good idea - a default value for the parameter:
  +
<pre>
  +
param 1 {
  +
param_depot_year {
  +
type: int;
  +
name: string(STR_PARAM_DEPOTYEAR);
  +
desc: string(STR_PARAM_DEPOTYEAR_DESC);
  +
min_value: 0;
  +
max_value: 5000000;
  +
def_value: 1975;
  +
}
  +
}
  +
</pre>
  +
  +
=== Enumeration parameter ===
  +
  +
The enumeration parameter basically is a numeric parameter where the single values have (additionally) a string attached to describe their meaning. Not all values need a string description, but it usually is a good idea to do this consistently
  +
<pre>
  +
param 0 {
  +
economy {
  +
type: int;
  +
name: string(STR_PARAM_NAME_ECONOMIES);
  +
desc: string(STR_PARAM_DESC_ECONOMIES);
  +
min_value: 0;
  +
max_value: 1;
  +
def_value: 0;
  +
names: {
  +
0: string(STR_PARAM_VALUE_ECONOMIES_TEST_ECONOMY);
  +
1: string(STR_PARAM_VALUE_ECONOMIES_HARD_ECONOMY);
  +
};
  +
}
  +
}
  +
</pre>
  +
  +
{{NMLTutorialNavbar|Train four part refit|Train recolour}}

Latest revision as of 19:48, 2 August 2014

Introduction

NewGRF Parameters in NML are part of the grf block

grf {
	grfid: "NML\FF";
	name: string(STR_GRF_NAME);
	desc: string(STR_GRF_DESC);
	version: 1;
	min_compatible_version: 0;
	param <num> {
		<name> {
			name: string(STR_PARAM_NAME_ECONOMIES);
			desc: string(STR_PARAM_DESC_ECONOMIES);
			<specifics>
		}
	}
}

Where name is the name the parameter is referenced further within the grf to read this parameter. <num> is the number of this parameter. The <num> parameter is optional and not needed when parameters are not re-ordered throughout versions. It can be used to keep the meaning of a specific NewGRF parameter while re-ordering the code. The meaning of a NewGRF parameter should should remain constant throughout versions of the same NewGRF or the NewGRF might become incompatible with previous versions of the same NewGRF (thus you'd need to change min_compatible_version if you change the meaning of the parameters at <num>.

Parameter types

NML knows three different types of parameters, boolean, numeric ones and enumerations:

Boolean parameter

The boolean parameter is the easiest as it requires no further definitions besides the name and description. Optionally a single parameter can contain several boolean parameter values, each using a single bit, thus saving in the number of externally visible NewGRF parameters.

param 3 { // 3rd parameter of the NewGRF
	param_bool_1 { // 1st boolean value
		name: string(STR_PARAM_NAME_DEBUG);
		desc: string(STR_PARAM_DESC_DEBUG);
		type: bool;
		bit:  1; // uses 1st bit
	}
	param_bool_2 { // 2nd boolean value
		name: string(STR_PARAM_NAME_DEBUG);
		desc: string(STR_PARAM_DESC_DEBUG);
		type: bool;
		bit:  2; // uses 2nd bit
	}
}

Numeric parameter

The numeric parameter allows to directly input an (integer) number. It needs to have a minimum and maximum value given and optionally - and usually a good idea - a default value for the parameter:

param 1 {
	param_depot_year {
		type: int;
		name: string(STR_PARAM_DEPOTYEAR);
		desc: string(STR_PARAM_DEPOTYEAR_DESC);
		min_value: 0;
		max_value: 5000000;
		def_value: 1975;
	}
}

Enumeration parameter

The enumeration parameter basically is a numeric parameter where the single values have (additionally) a string attached to describe their meaning. Not all values need a string description, but it usually is a good idea to do this consistently

param 0 {
	economy {
		type: int;
		name: string(STR_PARAM_NAME_ECONOMIES);
		desc: string(STR_PARAM_DESC_ECONOMIES);
		min_value: 0;
		max_value: 1;
		def_value: 0;
		names: {
			0: string(STR_PARAM_VALUE_ECONOMIES_TEST_ECONOMY);
			1: string(STR_PARAM_VALUE_ECONOMIES_HARD_ECONOMY);
		};
	}
}


NML Tutorial: Parameters