NML:Random switch

NewGRF Meta Language

Preface

Getting started

Graphics files

Blocks

Units

Expressions

Elementary values

Builtin functions

Language files

Lists of props, vars and CBs

Warnings

Additional references

NewGRF compatibility

Deprecated syntax

Changes from NML 0.2 to 0.3

Changes from NML 0.3 to 0.4

Changes from NML 0.4 to 0.5

Vehicles, Stations, Canals, Bridges, Towns, Houses, Industries (Tiles), Cargos, Airports+Tiles, Objects, Railtypes, Roadtypes, Tramtypes, Terrain

NML Tutorial

Block Syntax

GRF

• GRF parameters

Item

• Property
• Graphics
• Livery override

Realsprites

Recolour sprites

Template

Spriteset

Spritegroup

Spritelayout

Tilelayout

Switch

Produce

Random switch

Cargotable

Railtypetable / Roadtypetable / Tramtypetable

If/else

While

Error

Disable items

Deactivate other NewGRFs

Testing for other NewGRFs

Overriding vehicles in other NewGRFs

Sprite replacement

• Replace TTD sprites
• Replace new sprites
• Add font glyphs

Alternative (32bpp) sprites

Town names

• Town names parts

Snow line

Parameter assignment

Setting base costs

Sorting vehicles in the purchase list

Syntax

While a switch-block allows making a predictable decision, a random_switch allows a randomised choice between several options.

random_switch (<feature>, <type>, <ID>[, <triggers>]) {
	(independent: <other_random>;)*
	(dependent: <other_random>;)*
	(<probability>: <return_value>;)+
}

Feature and Type

The first parameter <feature> specifies the feature to use. <type>, the second parameter, is used to define what random data is used. The supported combinations are listed in the following table. The amount of random data is given in the third column. The maximum number of possible combinations is equal to 2^x, with x being the number of random bits. Not all combinations support re-randomizing via triggers, this is indicated in the fourth column. The last column specifies the object of which the random data is used.

Feature	Type	# of random bits	Triggers possible?	Random data used
Vehicles	SELF	8 14.0  16	Yes	Vehicle itself
Vehicles	PARENT	8 14.0  16	No	Leading engine
Vehicles	BACKWARD_SELF(x)	8 14.0  16	No	Count x vehicles backward (away from the engine), starting at the vehicle itself
Vehicles	FORWARD_SELF(x)	8 14.0  16	No	Count x vehicles forward (towards the engine), starting at the vehicle itself
Vehicles	BACKWARD_ENGINE(x)	8 14.0  16	No	Count x vehicles backward, starting at the leading engine
Vehicles	BACKWARD_SAMEID(x)	8 14.0  16	No	Count x vehicles backward, starting at the first vehicle in the chain with the same ID
Stations / airport tiles	SELF	16	Stations only	Station
Stations / airport tiles	TILE	4	Stations only	Specific station tile
Canals	SELF	8	No	Canal tile
Houses	SELF	8	Yes	House tile
Industry tiles	SELF	8	Yes	Industry tile
Industry tiles	PARENT	16	Yes	Industry as a whole
Industries	SELF	16	No	Industry (same as above)
Objects	SELF	8	No	Object tile (different per tile)
Railtypes	SELF	2	No	Rail tile (pseudo-random, based on location)
Roadtypes	SELF	2	No	Road tile (pseudo-random, based on location)
Tramtypes	SELF	2	No	Road tile (pseudo-random, based on location)

ID

The third parameter <ID> can be used to refer to this block from other (random-)switch-blocks.

Triggers

The last parameter <triggers> is optional and allows re-randomizing when certain conditions occur. The events and accompanying trigger names are given in the following tables. To re-randomize graphics when any of a set of events occurs, use bitmask(TRIGGER_A, TRIGGER_B, .. , TRIGGER_Z) To re-randomize only when all of the events have occured, add TRIGGER_ALL_NEEDED to the list of used triggers, e.g. use bitmask(TRIGGER_ALL_NEEDED, TRIGGER_A, ...)

Vehicles

Vehicle triggers

Trigger	Event
TRIGGER_VEHICLE_NEW_LOAD	Vehicle gets new load of cargo (only after it was empty)
TRIGGER_VEHICLE_SERVICE	Vehicle enters a depot and is serviced
TRIGGER_VEHICLE_UNLOAD_ALL	The consist has unloaded all cargo (use with type 'SELF')
TRIGGER_VEHICLE_ANY_LOAD	Any vehicle of the consist receives cargo (use with type 'SELF')
TRIGGER_VEHICLE_32_CALLBACK	32-day callback returned 1

To re-randomize when the consist has been emptied and then receives new cargo, use bitmask(TRIGGER_VEHICLE_UNLOAD_ALL, TRIGGER_VEHICLE_ANY_LOAD, TRIGGER_ALL_NEEDED)

Stations

Station triggers

Trigger	Event	Triggered on
TRIGGER_STATION_NEW_CARGO	New cargo waiting	Entire station
TRIGGER_STATION_NO_MORE_CARGO	No more cargo waiting	Entire station
TRIGGER_STATION_TRAIN_ARRIVES	Train arrives (starts loading/unloading)	Platform the train is on
TRIGGER_STATION_TRAIN_LEAVES	Train leaves (done loading/unloading)	Platform the train is on
TRIGGER_STATION_TRAIN_LOADS_UNLOADS	Train loads/unloads cargo	Platform the train is on
TRIGGER_STATION_TRAIN_RESERVES	Train reserves platform using PBS	Platform the train is on

All triggering events involve a cargo-type (which arrives, is loaded, or unloaded). The triggers only apply to a station section, if the cargo-type is listed in the property cargo_random_triggers.

The last four triggers in the table only trigger on the platform on which they occur.

Note that triggers are only saved per-station, not per-tile, so using TRIGGER_ALL_NEEDED doesn't make a lot of sense for per-platform triggers; or in general, if a station is composed of sections from different NewGRF.

Houses

House triggers

Trigger	Event
TRIGGER_HOUSE_TILELOOP	The house tile is processed in the periodic tile-processing loop
TRIGGER_HOUSE_TOP_TILELOOP	The top tile of the house is processed in the periodic tile-processing loop

Using TRIGGER_HOUSE_TOP_TILELOOP, it is possible to re-randomize the whole building as one unit. All tiles of a multi-tile house will get the same new random data.

Industry tiles

Industry tile triggers

Trigger	Event
TRIGGER_INDUSTRYTILE_TILELOOP	The industry tile is processed in the periodic tile-processing loop
TRIGGER_INDUSTRYTILE_256_TICKS	Triggers simultaneously for all tiles of the industry every 256 ticks. If the industry is a primary one, output cargo is generated at the same time.
TRIGGER_INDUSTRYTILE_CARGO_DELIVERY	Cargo is delivered to the industry. If the industry is a processing one, output cargo is generated at the same time.

Industry tiles can rerandomise both their own random bits as well as the random bits of the industry (via type PARENT). The triggers for rerandomisation are in both cases shared per tile (when using TRIGGER_ALL_NEEDED), i.e. the triggers are in all cases independent for different tiles. Industries have random bits. However, they can only be rerandomised by their tiles.

independent and dependent

<independent>: <other_random>; makes sure that this random_switch block and <other_random> use different (non-intersecting) random data. This allows making multiple randomized decisions that are independent of each other.

<dependent>: <other_random>;, on the other hand, lets this random_switch block and <other_random> use the same random data. To make this possible, it should not require more random data (i.e. have a higher sum of probabilities) than the block it is dependent on.

Both of these options require enough random data to be available. Also, the combination must make sense. For example, if A is dependent on B and B is dependent on C, then A cannot be independent of C.

Choices

Following this, there is a list of options, one of which will be chosen randomly. The syntax is <probability>: <return_value>;. The relative probability that this option will be chosen is given by <probability>. The chance is equal to the probability divided by the sum of all probabilities. If this sum is not equal to a power of two (2, 4, 8, 16, ...), then rounding is done and the probabilities may be inexact. For information about <return_value>, see the switch-block. Note that accessed variables in the return value are always in the scope of the item itself (i.e. SELF)

Usage in graphics and callbacks

Note that re-randomizing is done only during a special callback, random_trigger. This callback is called whenever a trigger event occurs. As a consequence, it's absolutely necessary for the random_switch block to be executed during this callback, or trigger-based re-randomizing won't take place. Also, the callback may not fail (end with CB_FAILED), so return an arbitrary value or even a sprite set instead. This return value is not used anywhere.

Example

Let's conclude with an example:

 random_switch (FEAT_TRAINS, SELF, random_42, bitmask(TRIGGER_VEHICLE_UNLOAD_ALL, TRIGGER_VEHICLE_ANY_LOAD, TRIGGER_ALL_NEEDED)) {
 	/* re-randomize when vehicle has been emptied and then received new cargo */
 	independent: random_43; // decision should be independent from random_43, which is defined elsewhere
 	6: group_open;          // 6/11 chance to display open wagon
 	3: group_closed;        // 3/11 chance to display closed wagon (with cover)
 	2: group_halfopen;      // 2/11 chance to display a half-covered wagon
 }