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 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>.

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