NMLTutorial/Callback and switch - Revision history

FooBar: use in switch blocks, as an identifier isn't a ''return value'' (but a reference to a different block)

2011-08-30T09:44:37Z

use <return> in switch blocks, as an identifier isn't a ''return value'' (but a reference to a different block)

← Older revision		Revision as of 09:44, 30 August 2011
Line 47:		Line 47:
	<pre class="pseudo">		<pre class="pseudo">
	switch (<feature>, <relation>, <identifier>, <expression>) {		switch (<feature>, <relation>, <identifier>, <expression>) {
	<range>: <~~return_value~~>;		<range>: <return>;
	<range2>: <~~return_value2~~>;		<range2>: <return2>;
			<default_return>;
	<default_return_value>;
	}		}
	</pre>		</pre>
Line 58:		Line 58:
	* <code><expression></code>: A [http://newgrf-specs.tt-wiki.net/wiki/NML:Properties_and_variables_and_callbacks variable] or GRF parameter you want to base this decision on. You may do mathematical calculations on a variable or parameter before having to make a decision on it's value and you may even list multiple expressions in the form of an array (we'll see examples of this later), but just a single variable or parameter if of course also fine.		* <code><expression></code>: A [http://newgrf-specs.tt-wiki.net/wiki/NML:Properties_and_variables_and_callbacks variable] or GRF parameter you want to base this decision on. You may do mathematical calculations on a variable or parameter before having to make a decision on it's value and you may even list multiple expressions in the form of an array (we'll see examples of this later), but just a single variable or parameter if of course also fine.
	* <code><range></code>: Either a single value or a subrange from the value range this expression can result in. If you want to specify a subrange, use <code><range_start>..<range_end></code>		* <code><range></code>: Either a single value or a subrange from the value range this expression can result in. If you want to specify a subrange, use <code><range_start>..<range_end></code>
	* <code><~~return_value~~></code>: An identifier to a different switch or spritegroup block, or (when switching a callback) the <code>return</code> keyword followed by a number or string reference.		* <code><return></code>: An identifier to a different switch or spritegroup block, or (when switching a callback) the <code>return</code> keyword followed by a number or string reference.
	* <code><~~default_return_value~~></code>: Like a <code><return_value></code>, but this one is only used if none of the ranges specified above matches the value of the variable.		* <code><default_return></code>: Like a <code><return_value></code>, but this one is only used if none of the ranges specified above matches the value of the variable.

	Now this may sound rather complicated and I agree that it may be a bit overwhelming when presented like this. Switches are one of the most complicated blocks in NML and they represent the VarAction2 in NFO. In case you're familiar with that: VarAction2 is one of the most complicated things in NFO as well.		Now this may sound rather complicated and I agree that it may be a bit overwhelming when presented like this. Switches are one of the most complicated blocks in NML and they represent the VarAction2 in NFO. In case you're familiar with that: VarAction2 is one of the most complicated things in NFO as well.

FooBar: use expression argument in switch blocks consistently

2011-08-30T09:36:47Z

use expression argument in switch blocks consistently

← Older revision		Revision as of 09:36, 30 August 2011
Line 39:		Line 39:

	== Switch blocks ==		== Switch blocks ==
	As written in the introduction, switch blocks can be used to make decisions on certain variables. A switch block can be used to decide a callback return value depending on a variable, or to decide what spritegroup to use for the graphics depending on a variable. You need to [http://newgrf-specs.tt-wiki.net/wiki/NML:Properties_and_variables_and_callbacks look up] what variables are available for the feature you're using. Don't forget the [http://newgrf-specs.tt-wiki.net/wiki/NML:General#General_variables general variables] that are available for all features.		As written in the introduction, switch blocks can be used to make decisions on certain variables. A switch block can be used to decide a callback return value depending on a variable, or to decide what spritegroup to use for the graphics depending on a variable. You need to [http://newgrf-specs.tt-wiki.net/wiki/NML:Properties_and_variables_and_callbacks look up] what variables are available for the feature you're using. Don't forget the [http://newgrf-specs.tt-wiki.net/wiki/NML:General#General_variables general variables] that are available for all features. And instead of a variable you may also use a GRF parameter.

	If you think you can make these decisions using if/else statements, you're wrong. Most variables are only available in a switch block of the feature you're working on. So when working with callbacks and graphics, use switches to make decisions based on variables.		If you think you can make these decisions using if/else statements, you're wrong. Most variables are only available in a switch block of the feature you're working on. So when working with callbacks and graphics, use switches to make decisions based on variables.
Line 46:		Line 46:

	<pre class="pseudo">		<pre class="pseudo">
	switch (<feature>, <relation>, <identifier>, <~~variable~~>) {		switch (<feature>, <relation>, <identifier>, <expression>) {
	<range>: <return_value>;		<range>: <return_value>;
	<range2>: <return_value2>;		<range2>: <return_value2>;
Line 56:		Line 56:
	* <code><relation></code>: either <code>SELF</code> or <code>PARENT</code>. This indicates if you want to use the variable of the item itself or that of it's related item. See the NML Documentation on [http://newgrf-specs.tt-wiki.net/wiki/NML:Switch switch blocks] for a table of what these relations are for each feature. Sometimes it will not be entirely clear which one you need, in that case just try <code>SELF</code> and change it to <code>PARENT</code> if it doesn't work like you think it should. <code>PARENT</code> is mostly needed for things that have to do with randomizations; in other cases <code>SELF</code> mostly does the trick.		* <code><relation></code>: either <code>SELF</code> or <code>PARENT</code>. This indicates if you want to use the variable of the item itself or that of it's related item. See the NML Documentation on [http://newgrf-specs.tt-wiki.net/wiki/NML:Switch switch blocks] for a table of what these relations are for each feature. Sometimes it will not be entirely clear which one you need, in that case just try <code>SELF</code> and change it to <code>PARENT</code> if it doesn't work like you think it should. <code>PARENT</code> is mostly needed for things that have to do with randomizations; in other cases <code>SELF</code> mostly does the trick.
	* <code><identifier></code>: a self-chosen identifier (name) for this switch. It's useful to start with ''switch_'' followed by the name of the item this is a switch for. Like with any other identifier, also these identifiers need to be unique throughout the NML file.		* <code><identifier></code>: a self-chosen identifier (name) for this switch. It's useful to start with ''switch_'' followed by the name of the item this is a switch for. Like with any other identifier, also these identifiers need to be unique throughout the NML file.
	* <code><~~variable~~></code>: ~~the~~ [http://newgrf-specs.tt-wiki.net/wiki/NML:Properties_and_variables_and_callbacks variable] you want to base this decision on~~<ref>To~~ ~~make~~ ~~things~~ ~~even~~ ~~more~~ ~~complicated,~~ ~~you~~ ~~can~~ ~~use~~ ~~expressions~~ as a ~~variable~~ or ~~even~~ an ~~array~~ of ~~multiple~~ ~~expressions.~~ ~~The~~ ~~last~~ ~~expression~~ ~~from~~ the ~~array~~ is ~~used~~ to ~~make~~ ~~the~~ ~~decision.~~ To ~~make~~ ~~things~~ ~~not~~ ~~even~~ ~~more~~ ~~complicated~~ ~~than~~ ~~they~~ ~~already~~ ~~are,~~ ~~we'll~~ ~~ignore~~ ~~this~~ ~~possibility for now.</ref>~~.		* <code><expression></code>: A [http://newgrf-specs.tt-wiki.net/wiki/NML:Properties_and_variables_and_callbacks variable] or GRF parameter you want to base this decision on. You may do mathematical calculations on a variable or parameter before having to make a decision on it's value and you may even list multiple expressions in the form of an array (we'll see examples of this later), but just a single variable or parameter if of course also fine.
	* <code><range></code>: Either a single value or a subrange from the value range ~~available~~ to ~~this~~ ~~variable~~. If you want to specify a subrange, use <code><range_start>..<range_end></code>		* <code><range></code>: Either a single value or a subrange from the value range this expression can result in. If you want to specify a subrange, use <code><range_start>..<range_end></code>
	* <code><return_value></code>: An identifier to a different switch or spritegroup block, or (when switching a callback) the <code>return</code> keyword followed by a number or string reference.		* <code><return_value></code>: An identifier to a different switch or spritegroup block, or (when switching a callback) the <code>return</code> keyword followed by a number or string reference.
	* <code><default_return_value></code>: Like a <code><return_value></code>, but this one is only used if none of the ranges specified above matches the value of the variable.		* <code><default_return_value></code>: Like a <code><return_value></code>, but this one is only used if none of the ranges specified above matches the value of the variable.

FooBar at 09:29, 30 August 2011

2011-08-30T09:29:06Z

← Older revision		Revision as of 09:29, 30 August 2011
Line 14:		Line 14:
	item {		item {
	graphics {		graphics {
	callback: <identifier>\|<return_value>;		<callback>: <identifier>\|<return_value>;
	[<callback2>: <identifier2>\|<return_value2>;]		[<callback2>: <identifier2>\|<return_value2>;]
	[...;]		[...;]

FooBar: fix

2011-08-27T22:16:51Z

fix

← Older revision		Revision as of 22:16, 27 August 2011
Line 25:		Line 25:
	So for example (using fictional callback names):		So for example (using fictional callback names):

	<pre class="~~pseudo~~">		<pre class="example">
	graphics {		graphics {
	callback_to_spritegroup: spritegroup_identifier;		callback_to_spritegroup: spritegroup_identifier;

FooBar: pre class

2011-08-27T22:16:34Z

pre class

← Older revision		Revision as of 22:16, 27 August 2011
Line 11:		Line 11:
	Callbacks are defined in the [[NMLTutorial/Item#Graphics block\|graphics block]] of the item block and from there they can either directly return a value or point to a switch or spritegroup. Let's look at the graphics block once more:		Callbacks are defined in the [[NMLTutorial/Item#Graphics block\|graphics block]] of the item block and from there they can either directly return a value or point to a switch or spritegroup. Let's look at the graphics block once more:

	<pre ~~white-space: pre-wrap~~">		<pre class="pseudo">
	item {		item {
	graphics {		graphics {
Line 25:		Line 25:
	So for example (using fictional callback names):		So for example (using fictional callback names):

			<pre class="pseudo">
	<pre style="color:darkblue; white-space: pre-wrap">
	graphics {		graphics {
	callback_to_spritegroup: spritegroup_identifier;		callback_to_spritegroup: spritegroup_identifier;
Line 45:		Line 45:
	The switch block syntax looks like this:		The switch block syntax looks like this:

	<pre ~~white-space: pre-wrap~~">		<pre class="pseudo">
	switch (<feature>, <relation>, <identifier>, <variable>) {		switch (<feature>, <relation>, <identifier>, <variable>) {
	<range>: <return_value>;		<range>: <return_value>;
Line 66:		Line 66:
	Let's look at a little example showing some of the possibilities of a switch. Note that doesn't have an actual meaning other than showing some of the options. In reality it will be very uncommon that a single switch blocks needs to have a string returned for one range, a number for another range, point to an other switch for yet another range.		Let's look at a little example showing some of the possibilities of a switch. Note that doesn't have an actual meaning other than showing some of the options. In reality it will be very uncommon that a single switch blocks needs to have a string returned for one range, a number for another range, point to an other switch for yet another range.

			<pre class="example">
	<pre style="color:darkblue; white-space: pre-wrap">
	switch (FEAT_TRAINS, PARENT, some_vehicle_switch, (position_in_consist) {		switch (FEAT_TRAINS, PARENT, some_vehicle_switch, (position_in_consist) {
	0..2: return string(STRING_FOO_BAR); //return a text message		0..2: return string(STRING_FOO_BAR); //return a text message
Line 79:		Line 79:
	Because this particular example returns numbers and strings, it can only be a switch for a callback. Switches used for graphics will (only) return identifiers to spritegroups, for example (this is an actual realistic example for a change):		Because this particular example returns numbers and strings, it can only be a switch for a callback. Switches used for graphics will (only) return identifiers to spritegroups, for example (this is an actual realistic example for a change):

			<pre class="example">
	<pre style="color:darkblue; white-space: pre-wrap">
	switch (FEAT_TRAINS, PARENT, some_other_vehicle_switch, (position_in_consist) {		switch (FEAT_TRAINS, PARENT, some_other_vehicle_switch, (position_in_consist) {
	1..2: spritegroup_vehicle_1; //use this for second and third part of articulated vehicle		1..2: spritegroup_vehicle_1; //use this for second and third part of articulated vehicle

FooBar: /* Switch blocks */

2011-08-27T14:50:27Z

Switch blocks

← Older revision		Revision as of 14:50, 27 August 2011
Line 54:		Line 54:

	* <code><feature></code>: the [[NMLTutorial/NML Syntax#Features\|feature]] you're working on.		* <code><feature></code>: the [[NMLTutorial/NML Syntax#Features\|feature]] you're working on.
	* <code><relation></code>: either <code>SELF</code> or <code>PARENT</code>. This indicates if you want to use the variable of the item itself or that of it's related item. See the NML Documentation on [http://newgrf-specs.tt-wiki.net/wiki/NML:Switch switch blocks] for a table of what these relations are for each feature.		* <code><relation></code>: either <code>SELF</code> or <code>PARENT</code>. This indicates if you want to use the variable of the item itself or that of it's related item. See the NML Documentation on [http://newgrf-specs.tt-wiki.net/wiki/NML:Switch switch blocks] for a table of what these relations are for each feature. Sometimes it will not be entirely clear which one you need, in that case just try <code>SELF</code> and change it to <code>PARENT</code> if it doesn't work like you think it should. <code>PARENT</code> is mostly needed for things that have to do with randomizations; in other cases <code>SELF</code> mostly does the trick.
	* <code><identifier></code>: a self-chosen identifier (name) for this switch. It's useful to start with ''switch_'' followed by the name of the item this is a switch for. Like with any other identifier, also these identifiers need to be unique throughout the NML file.		* <code><identifier></code>: a self-chosen identifier (name) for this switch. It's useful to start with ''switch_'' followed by the name of the item this is a switch for. Like with any other identifier, also these identifiers need to be unique throughout the NML file.
	* <code><variable></code>: the [http://newgrf-specs.tt-wiki.net/wiki/NML:Properties_and_variables_and_callbacks variable] you want to base this decision on<ref>To make things even more complicated, you can use expressions as a variable or even an array of multiple expressions. The last expression from the array is used to make the decision. To make things not even more complicated than they already are, we'll ignore this possibility for now.</ref>.		* <code><variable></code>: the [http://newgrf-specs.tt-wiki.net/wiki/NML:Properties_and_variables_and_callbacks variable] you want to base this decision on<ref>To make things even more complicated, you can use expressions as a variable or even an array of multiple expressions. The last expression from the array is used to make the decision. To make things not even more complicated than they already are, we'll ignore this possibility for now.</ref>.

FooBar: /* Switch blocks */ unique identifier

2011-08-24T13:10:23Z

Switch blocks: unique identifier

← Older revision		Revision as of 13:10, 24 August 2011
Line 55:		Line 55:
	* <code><feature></code>: the [[NMLTutorial/NML Syntax#Features\|feature]] you're working on.		* <code><feature></code>: the [[NMLTutorial/NML Syntax#Features\|feature]] you're working on.
	* <code><relation></code>: either <code>SELF</code> or <code>PARENT</code>. This indicates if you want to use the variable of the item itself or that of it's related item. See the NML Documentation on [http://newgrf-specs.tt-wiki.net/wiki/NML:Switch switch blocks] for a table of what these relations are for each feature.		* <code><relation></code>: either <code>SELF</code> or <code>PARENT</code>. This indicates if you want to use the variable of the item itself or that of it's related item. See the NML Documentation on [http://newgrf-specs.tt-wiki.net/wiki/NML:Switch switch blocks] for a table of what these relations are for each feature.
	* <code><identifier></code>: a self-chosen identifier (name) for this switch. It's useful to start with ''switch_''.		* <code><identifier></code>: a self-chosen identifier (name) for this switch. It's useful to start with ''switch_'' followed by the name of the item this is a switch for. Like with any other identifier, also these identifiers need to be unique throughout the NML file.
	* <code><variable></code>: the [http://newgrf-specs.tt-wiki.net/wiki/NML:Properties_and_variables_and_callbacks variable] you want to base this decision on<ref>To make things even more complicated, you can use expressions as a variable or even an array of multiple expressions. The last expression from the array is used to make the decision. To make things not even more complicated than they already are, we'll ignore this possibility for now.</ref>.		* <code><variable></code>: the [http://newgrf-specs.tt-wiki.net/wiki/NML:Properties_and_variables_and_callbacks variable] you want to base this decision on<ref>To make things even more complicated, you can use expressions as a variable or even an array of multiple expressions. The last expression from the array is used to make the decision. To make things not even more complicated than they already are, we'll ignore this possibility for now.</ref>.
	* <code><range></code>: Either a single value or a subrange from the value range available to this variable. If you want to specify a subrange, use <code><range_start>..<range_end></code>		* <code><range></code>: Either a single value or a subrange from the value range available to this variable. If you want to specify a subrange, use <code><range_start>..<range_end></code>

Yexo: /* Switch blocks */

2011-08-24T11:37:03Z

Switch blocks

← Older revision		Revision as of 11:37, 24 August 2011
Line 73:		Line 73:
	400: switch_other_identifier; //chain to some other switch block		400: switch_other_identifier; //chain to some other switch block
	401: return num_vehs_in_consist + 1; //return a value with a variable access		401: return num_vehs_in_consist + 1; //return a value with a variable access
	CB_FAILED; //return a failure result as default ~~(this is the same as <code>return 0xFF</code>).~~		CB_FAILED; //return a failure result as default
	}		}
	</pre>		</pre>
Line 89:		Line 89:


	There's ~~probably~~ much more to say about callbacks and switch blocks, but this is probably intimidating enough already. Next we'll make an articulated tram vehicle to show you where these callbacks and switches go in your NML code.		There's much more to say about callbacks and switch blocks, but this is probably intimidating enough already. Next we'll make an articulated tram vehicle to show you where these callbacks and switches go in your NML code.

	{{NMLTutorialNavbar\|Road vehicle cargo graphics\|Tram}}		{{NMLTutorialNavbar\|Road vehicle cargo graphics\|Tram}}

FooBar: about callbacks and switches

2011-08-24T10:43:02Z

about callbacks and switches

New page

{{NMLTutorial}}

Callbacks allow to do some fancy things on the fly. Where properties are defined static, callbacks allow to change (some) properties depending on the game state (for instance the game year or what cargo a vehicle is refitted to). Apart from that, some callbacks allow things that are not possible from the usual item definition (such as graphic animations or articulated vehicles).

Callbacks are often used in combination with switches. Switches are things that allow to make a decision based on variables. These variables depend on the game state (so if you for instance want to change vehicle properties depending on the game year, you need a switch attached to the callback). Furthermore, switches can be used to "switch graphics" based on the same variables (e.g. pointing to different spritegroups/sets for each part of an articulated vehicle).

== Callbacks ==
What callbacks are available depend on the [[NMLTutorial/NML Syntax#Features|feature]] you're working on. Then you can [http://newgrf-specs.tt-wiki.net/wiki/NML:Properties_and_variables_and_callbacks look up] the available callbacks in the NML Documentation. These tables list the names of the callbacks, what they do and what value they want to see returned. Some callbacks need to be pointed to spritegroups, while others want a string or number returned.

Callbacks are defined in the [[NMLTutorial/Item#Graphics block|graphics block]] of the item block and from there they can either directly return a value or point to a switch or spritegroup. Let's look at the graphics block once more:

<pre white-space: pre-wrap">
item {
graphics {
callback: <identifier>|<return_value>;
[<callback2>: <identifier2>|<return_value2>;]
[...;]
}
}
</pre>

If you want to point the callback to a different block (a switch block or a spritegroup block), you just put the identifier of that block behind the name of the callback. If you want the callback to return a value (string or number) directly, you need to first write the keyword <code>return</code> and then the numeric value or <code>string()</code>.

So for example (using fictional callback names):

<pre style="color:darkblue; white-space: pre-wrap">
graphics {
callback_to_spritegroup: spritegroup_identifier;
callback_to_switch: switch_identifier;
callback_return_string: return string(STR_STRINGNAME);
callback_return_number: return 20;
default: spritegroup_default_graphics;
}
</pre>

Please note that all callbacks need to be defined in a '''single''' graphics block.

== Switch blocks ==
As written in the introduction, switch blocks can be used to make decisions on certain variables. A switch block can be used to decide a callback return value depending on a variable, or to decide what spritegroup to use for the graphics depending on a variable. You need to [http://newgrf-specs.tt-wiki.net/wiki/NML:Properties_and_variables_and_callbacks look up] what variables are available for the feature you're using. Don't forget the [http://newgrf-specs.tt-wiki.net/wiki/NML:General#General_variables general variables] that are available for all features.

If you think you can make these decisions using if/else statements, you're wrong. Most variables are only available in a switch block of the feature you're working on. So when working with callbacks and graphics, use switches to make decisions based on variables.

The switch block syntax looks like this:

<pre white-space: pre-wrap">
switch (<feature>, <relation>, <identifier>, <variable>) {
<range>: <return_value>;
<range2>: <return_value2>;
<default_return_value>;
}
</pre>

* <code><feature></code>: the [[NMLTutorial/NML Syntax#Features|feature]] you're working on.
* <code><relation></code>: either <code>SELF</code> or <code>PARENT</code>. This indicates if you want to use the variable of the item itself or that of it's related item. See the NML Documentation on [http://newgrf-specs.tt-wiki.net/wiki/NML:Switch switch blocks] for a table of what these relations are for each feature.
* <code><identifier></code>: a self-chosen identifier (name) for this switch. It's useful to start with ''switch_''.
* <code><variable></code>: the [http://newgrf-specs.tt-wiki.net/wiki/NML:Properties_and_variables_and_callbacks variable] you want to base this decision on<ref>To make things even more complicated, you can use expressions as a variable or even an array of multiple expressions. The last expression from the array is used to make the decision. To make things not even more complicated than they already are, we'll ignore this possibility for now.</ref>.
* <code><range></code>: Either a single value or a subrange from the value range available to this variable. If you want to specify a subrange, use <code><range_start>..<range_end></code>
* <code><return_value></code>: An identifier to a different switch or spritegroup block, or (when switching a callback) the <code>return</code> keyword followed by a number or string reference.
* <code><default_return_value></code>: Like a <code><return_value></code>, but this one is only used if none of the ranges specified above matches the value of the variable.

Now this may sound rather complicated and I agree that it may be a bit overwhelming when presented like this. Switches are one of the most complicated blocks in NML and they represent the VarAction2 in NFO. In case you're familiar with that: VarAction2 is one of the most complicated things in NFO as well.

Let's look at a little example showing some of the possibilities of a switch. Note that doesn't have an actual meaning other than showing some of the options. In reality it will be very uncommon that a single switch blocks needs to have a string returned for one range, a number for another range, point to an other switch for yet another range.

<pre style="color:darkblue; white-space: pre-wrap">
switch (FEAT_TRAINS, PARENT, some_vehicle_switch, (position_in_consist) {
0..2: return string(STRING_FOO_BAR); //return a text message
3..4: return; //returns 3 in case position_in_consist == 3 or 4 in case position_in_consist == 4
5..300: return 42; //42 is always a good answer
400: switch_other_identifier; //chain to some other switch block
401: return num_vehs_in_consist + 1; //return a value with a variable access
CB_FAILED; //return a failure result as default (this is the same as <code>return 0xFF</code>).
}
</pre>

Because this particular example returns numbers and strings, it can only be a switch for a callback. Switches used for graphics will (only) return identifiers to spritegroups, for example (this is an actual realistic example for a change):

<pre style="color:darkblue; white-space: pre-wrap">
switch (FEAT_TRAINS, PARENT, some_other_vehicle_switch, (position_in_consist) {
1..2: spritegroup_vehicle_1; //use this for second and third part of articulated vehicle
3..4: spritegroup_vehicle_2; //use this for fourth and fifth part of articulated vehicle
5: spritegroup_vehicle_3; //use this for sixth part of articulated vehicle
spritegroup_vehicle_0; //use this for first and other parts of articulated vehicle (i.e. default)
}
</pre>

There's probably much more to say about callbacks and switch blocks, but this is probably intimidating enough already. Next we'll make an articulated tram vehicle to show you where these callbacks and switches go in your NML code.

{{NMLTutorialNavbar|Road vehicle cargo graphics|Tram}}

<references />