Difference between revisions of "NMLTutorial/Parameters"
Planetmaker (talk | contribs) (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 < |
+ | 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