NML tutorial

[FooBar]

The NML tutorial ia available at the TT-Wiki: http://www.tt-wiki.net/wiki/NMLTutorial

This tutorial helps you install NML, explains different NML concepts and helps you understand those concepts by the means of examples that are interwoven in the more technical explanations of the syntax. It is meant to be read from top to bottom and every concept introduced is clarified by an example of actual NML code. The further you get in the tutorial, some concepts will be repeated by different examples and extended with new concepts.

I hope this tutorial helps anybody wanting to start with NML and not knowing where to start exactly. If you have any question on the tutorial content, please feel free to ask here. Please use a different topic if you just need help with your personal NML project.

[Yexo]

Once again amazing work FooBar

You seem to have switched up the -c and -u flags (-c is for cropping), so I've fixed that.

[FooBar]

ahh, yes. That indeed is a mixup, as I indeed meant -c. Especially as -u isn't a very good idea... Thanks for the fix.

As I couldn't sleep, I made some plans for what's next in the tutorial. I decided to add an example from the dutch trams as a means to illustrate some basic switches and callbacks. Then continue with the train example from the nml source as a more advanced example of swiches and callbacks, as already listed in the tutorial menu.

Now back to sleep

[Terkhen]

Awesome work

[FooBar]

I expanded the tutorial a little bit. Now there's something on templates and the cargotable and the road vehicle example is complete.

Next will be an introduction to callbacks and switches, illustrated by an articulated tram example. But not today

[Hyronymus]

Thank you a lot, FooBar .

[Yexo]

Overall I can only say (again!) that you did an excellent job! I do have some comments:

Combine this with the fact that you can do any mathematical calculation on the values for left_x, upper_y, width and height (though not on the offsets), you can make a template as complex as you want.

NML has no such limitation, you can even do calculations on the offsets if you want to (even though I don't see a good use-case for that).

very NewGRF can have exactly one cargotable (but you may select from several using if/else statements).

Not true, NML limits you to exactly one cargotable, regardless of whether that cargotable is inside an if-block or not.

[FooBar]

Hyronymus, Terkhen and Yexo, thanks for your kind words.

Combine this with the fact that you can do any mathematical calculation on the values for left_x, upper_y, width and height (though not on the offsets), you can make a template as complex as you want.

NML has no such limitation, you can even do calculations on the offsets if you want to (even though I don't see a good use-case for that).

Technically you're right. But because this states that you cannot use parameters for the offsets, I simplified it a bit not to bother users with too much details. I don't see a use for calculations in offsets either for as long as you can't use parameters in them.
I added this as a footnote, just to be complete.

very NewGRF can have exactly one cargotable (but you may select from several using if/else statements).

Not true, NML limits you to exactly one cargotable, regardless of whether that cargotable is inside an if-block or not.

I didn't know that. Duly noted and fixed.

I appreciate your comments and if you (or anybody else) finds something that isn't correct or not clear please let me know. I like to think that I know how to code in NML, but am aware that I don't know every last detail. So keep those comments coming

[Eddi]

... i do have a use case for different offsets

and i haven't seen anything wrong with it.

Edit: i think the word "parameter" in the link above is confusing/misleading. there is a "template parameter" and a "grf parameter", and i think the two meanings collide here. what is probably meant is that grf-parameters may not be used for realsprites, but other calculations and template-parameters are fine.

[FooBar]

You mean you use template parameters in the offsets? As I understood that was the thing that was not possible...
Maybe someone more familiar with the NML source code can clarify this once and for all.


I agree with you that "parameter" is confusing. I decided to rename them to "template parameter" to hopefully reduce/avoid this confusion. The remainder of the tutorial will spreak of "template parameter" and "grf parameter" where applicable, to make explicitly clear what is meant by "parameter".

[planetmaker]

You mean you use template parameters in the offsets? As I understood that was the thing that was not possible...
Maybe someone more familiar with the NML source code can clarify this once and for all.

I know of no limitation to use any template parameter within the template in any fashion or position... why wouldn't one not be able to use a parameter on the sprite x- and y-offsets? (Yes, I use(d) templates which use a parameter for virtually everything )

[FooBar]

why wouldn't one not be able to use a parameter on the sprite x- and y-offsets?

I have no idea and actually find it a bit weird if you couldn't. But as long als the NML Documentation says that you can't, I can't be sure

[Yexo]

Technically you're right. But because this states that you cannot use parameters for the offsets, I simplified it a bit not to bother users with too much details. I don't see a use for calculations in offsets either for as long as you can't use parameters in them.

I've removed that confusing line from the spec as it was confusing and didn't add anything.
In the process I've completely removed the part in the tutorial about not being able to use parameters on any value. Technically you could even use the template parameters for the compression or filename arguments, although it would be even harder to find a use case for that.

[FooBar]

Thanks for clearing this up, Yexo. I do have a use for parameterizing the filename in my tram track grf. Actually, it was me who requested the filename to be parameterizable in templates

Also, there's now an introduction to callbacks and switch blocks in the tutorial

[Yexo]

//return a failure result as default (this is the same as <code>return 0xFF</code>).

Not true, so I've removed it.

[FooBar]

Hmmm, wrong assumption on my part.

I couldn't really find from the source what CB_FAILED does, so I (wrongly) assumed it was that.

[Hyronymus]

You mean you use template parameters in the offsets? As I understood that was the thing that was not possible...
Maybe someone more familiar with the NML source code can clarify this once and for all.


I agree with you that "parameter" is confusing. I decided to rename them to "template parameter" to hopefully reduce/avoid this confusion. The remainder of the tutorial will spreak of "template parameter" and "grf parameter" where applicable, to make explicitly clear what is meant by "parameter".

Will it be a problem to call it template variable i.e.?

[FooBar]

Possibly, but then you get a similar confusion with the variables available to features, basically the variables listed here: http://newgrf-specs.tt-wiki.net/wiki/NM ... _callbacks

In programming, the proper term actually is "parameter", as the template is a user-defined "function" that accepts any number of parameters. I'm completely in favour of an unambiguous replacement, but I don't think variable is that replacement. Still open to suggestions though.

[Yexo]

You could try argument. As far as I know it's not used anywhere else in NML-terminology and imo it's just as good as parameter.

[Eddi]

i'm rather thinking the "grf parameter" part is a bit of a misnomer, because they serve more as "global variables", which can be set by the GUI (-> action 14) or by the GRF (-> action D)