NMLTutorial/Parameters

NML Tutorial

Installation

Graphics files

Language files

NML Syntax

Starting an NML file (grf block)

• Creating a road vehicle

Item blocks

• • Item definition

Spriteset & spritegroup blocks

• • Adding the graphics

Template blocks

• • Templating the graphics

Cargotable block

• • Cargo-dependent graphics

Callbacks and switch blocks

• Creating a tram

• • Make it articulated

• • Adding the graphics

• • Fix the purchase menu

• Creating a train

Railtypetable block

• • Single engine

• • Three part articulated

• • Four part refit

GRF Parameters

• • Real life recolour scheme

• Creating an object

Spritelayout blocks

• • Adding the graphics

Version checks

• • Objects on slopes

32 bit sprites

• Adding 32 bit sprites

Base graphics replacement

• 32 bit base graphics

Conclusion

Glossary

NML Documentation

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