Difference between revisions of "NMLTutorial/NML Syntax"

From TTWiki
Jump to navigationJump to search
(some notes on how to read the block syntax)
m (write style)
Line 1: Line 1:
 
{{NMLTutorial}}
 
{{NMLTutorial}}
   
This page will be a theoretical introduction to the NML syntax. It is very well possible that you don't understand anything of what is written here. If that is the case, please read the page carefully ''once'' and then just continue with the next page which will take you on an example journey through the world of coding in NML.
+
This page will be a theoretical introduction to the NML syntax. It is very well possible that you do not understand anything of what is written here. If that is the case, please read the page carefully ''once'' and then just continue with the next page which will take you on an example journey through the world of coding in NML.
   
If you do understand this page completely, then it's very likely that you don't need the rest of this NML tutorial and just can look up what you need in the [http://newgrf-specs.tt-wiki.net/wiki/NML:Main NML Documentation]. At your option you can browse through the tutorial quickly or just start making your NewGRF and figure things out as you go.
+
If you do understand this page completely, then it is very likely that you do not need the rest of this NML tutorial and just can look up what you need in the [http://newgrf-specs.tt-wiki.net/wiki/NML:Main NML Documentation]. At your option, you can browse through the tutorial quickly or just start making your NewGRF and figure things out as you go.
   
   
 
== NML is a programming language ==
 
== NML is a programming language ==
NFO is not a programming language: it's hex editing. NML on the other hand is a human-readable programming language and contains things like if/else statements, operators such as &&, ||, !=, >= etc. and curly brackets to enclose groups of statements.
+
NFO is not a programming language: it is hex editing. NML on the other hand is a human-readable programming language and contains things like if/else statements, operators such as <code>&&</code>, <code>||</code>, <code>!=</code>, <code>&gt;=</code> etc. and curly brackets to enclose groups of statements.
   
If you already know a programming language such as C++ or PHP, it's probably very easy to understand and adapt to the NML syntax. If you're new to programming, you should understand a few concepts:
+
If you already know a programming language such as C++ or PHP, it is probably very easy to understand and adapt to the NML syntax. If you are new to programming, you should understand a few concepts:
   
=== If you're new to programming ===
+
=== If you are new to programming ===
 
; Name things the way you want
 
; Name things the way you want
: If you define something, it's you who gives it a name. There's no set of rules how things should be called. If you want to name everything foo0001 through foo9999 that's up to you. That doesn't make it very easy to remember which is which, but it isn't wrong per se. However, don't use any fancy symbols in names: you may use (capital) letters a through z, numbers 0 through 9 and an underscore (_). Numbers furthermore cannot be at the beginning of the name of an identifier.
+
: If you define something, it is you who gives it a name. There is no set of rules how things should be called. If you want to name everything foo0001 through foo9999, that is up to you. That does not make it very easy to remember what is what, but it is not wrong per se. However, do not use any fancy symbols in names: you may use (capital) letters a through z, numbers 0 through 9 and an underscore (_). Numbers furthermore cannot be at the beginning of the name of an identifier.
   
 
; When referencing something, it needs to exist
 
; When referencing something, it needs to exist
 
: If you want to use a string, the string needs to exists. That probably makes as much sense to you as that a circle is round, right? But it goes further than that: if you define a vehicle and want it to use this and that graphics, the graphics need to be defined ''before'' you define the vehicle that uses it. This applies to everything; if your reference something somewhere, that something needs to exists and essentially needs to be before the reference.
 
: If you want to use a string, the string needs to exists. That probably makes as much sense to you as that a circle is round, right? But it goes further than that: if you define a vehicle and want it to use this and that graphics, the graphics need to be defined ''before'' you define the vehicle that uses it. This applies to everything; if your reference something somewhere, that something needs to exists and essentially needs to be before the reference.
   
; Compilers don't understand typos
+
; Compilers do not understand typos
: If you make a typo, the compiler (in this case nmlc) doesn't understand what you mean. This especially applies to the names of things we discussed earlier. If you name your vehicle definition KirbyPaulTank, then you must use the exact capitalization everywhere. For a compiler, Kirbypaultank, kirbypaultank, kirbypaulTank etc. are all completely different things. You need to pay special attention to this if you come from Windows. In Windows there's no difference if you write a file or directory with or without captials; in a programming language with or without capitals is a completely different thing and essentially a typo when not used consistently.
+
: If you make a typo, the compiler (in this case nmlc) will not understand what you mean. This especially applies to the names of things we discussed earlier. If you name your vehicle definition KirbyPaulTank, then you must use the exact capitalization everywhere. For a compiler, Kirbypaultank, kirbypaultank, kirbypaulTank etc. are all completely different things. You need to pay special attention to this if you come from Windows. In Windows, there is no difference if you give a file or directory a name with or without captials; in a programming language, with or without capitals is a completely different thing and essentially a typo when not used consistently.
   
 
; Add more comments than you think is necessary
 
; Add more comments than you think is necessary
: When working on a piece of code, you easily remember what does what and why you made it the way you did. However, if you don't look at a piece of code for a couple of months, chances are you have no clue what it does if you haven't commented it. Using decent names for definitions helps a great deal towards reducing the amount of comments, but ideally every code block should have a line stating what it's for and more complicated things also get comments as you go. If you do certain things differently for a reason, state why you did that. If you work with more people on one project, comments are vital in helping fellow developers understand what you did.
+
: When working on a piece of code, you easily remember what does what and why you made it the way you did. However, if you do not, look at a piece of code for a couple of months, chances are you have no clue what it does if you have not commented it. Using decent names for definitions helps a great deal towards reducing the amount of comments, but ideally every code block should have a line stating what it is for and more complicated things also get comments as you go. If you do certain things differently for a reason, state ''why'' you did that. If you work with more people on one project, comments are vital in helping fellow developers understand why you did what.
   
   
Line 45: Line 45:
 
}
 
}
 
</pre>
 
</pre>
''Note: the identifier isn't necessarily the first argument of a block in case of multiple arguments.''
+
''Note: the identifier is not necessarily the first argument of a block in case of multiple arguments.''
   
When a block syntax is explained in the tutorial, some arguments may be optional. These are written between [ straight brackets ]. These brackets indicate that something is optional; the brackets are not part of the actual NML code. <code>[,...]</code> means that you can have any number of arguments of the same type as the previous argument. Things between < pointy brackets > must be replaced with actual content. What this content must be is explained directly after the introduction of the block's syntax. Also pointy brackets are not part of actual NML code. Round and curly brackets are part of the NML code and must be written as indicated. Words or text not between pointy brackets is also part of the NML code and must appear as indicated.
+
When a block syntax is explained in the tutorial, some arguments may be optional. These are written between [ straight/square brackets ]. These brackets indicate that something is optional; the brackets are not part of the actual NML code. <code>[,...]</code> means that you can have any number of arguments of the same type as the previous argument. Things between < pointy/angular brackets > must be replaced with actual content. What this content must be is explained directly after the introduction of the block's syntax. Also, pointy brackets are not part of actual NML code. Round and curly brackets are part of the NML code and must be written as indicated. Words or text not between pointy brackets is also part of the NML code and must appear as indicated.
   
   
Line 80: Line 80:
 
</div><div style="clear:left"></div>
 
</div><div style="clear:left"></div>
   
Some special "blocks", which aren't really blocks but language constructs, exist as well:
+
Some special "blocks", which are not really blocks, but language constructs, exist as well:
 
* if
 
* if
 
* else
 
* else
   
Furthermore, there are too many [http://newgrf-specs.tt-wiki.net/wiki/NML:Builtin_functions functions] to list here. For now you can forget these if you want, but it's good to have seen their names.
+
Furthermore, there are too many [http://newgrf-specs.tt-wiki.net/wiki/NML:Builtin_functions functions] to list here. For now, you can forget these if you want, but it is good to have seen their names.
   
 
The blocks define things that can be referenced or make new things available in the game. Some blocks can contain sub-blocks. The <code>grf</code> block can contain a <code>param</code> subblock to add parameter settings. The <code>item</code> block can contain <code>property</code>, <code>graphics</code> and <code>livery_override</code> subblocks.
 
The blocks define things that can be referenced or make new things available in the game. Some blocks can contain sub-blocks. The <code>grf</code> block can contain a <code>param</code> subblock to add parameter settings. The <code>item</code> block can contain <code>property</code>, <code>graphics</code> and <code>livery_override</code> subblocks.
   
If you need to do some calculations you do those outside the blocks, or in some special cases in a block's ''expression'' argument, but never inside a block. <code>if</code>s and <code>else</code>s also have no place inside blocks and can only be used outside them.
+
If you need to do some calculations, you do those outside the blocks, or in some special cases, in a block's ''expression'' argument, but never inside a block. <code>if</code>s and <code>else</code>s also have no place inside blocks and can only be used outside them.
   
 
=== Identifiers ===
 
=== Identifiers ===
As you've read earlier, some blocks need to have an ''identifier''. You can see this identifier as a name for the block and you choose this identifier yourself.
+
As you have read earlier, some blocks need to have an ''identifier''. You can see this identifier as a name for the block and you choose this identifier yourself.
   
'''All identifiers need to be unique throughout you NML file!''' This even applies for identifiers of totally different blocks. An easy method to avoid duplicate identifiers is to precede the identifier name with the name of the block type. While this isn't foolproof, it simply reduces the chances for duplicates. It is also a good idea to add the name of the item (vehicle, object, etc.) an identifier belongs to to the name of the identifier.
+
'''All identifiers need to be unique throughout you NML file!''' This even applies for identifiers of totally different blocks. An easy method to avoid duplicate identifiers is to precede the identifier name with the name of the block type. While this is not foolproof, it simply reduces the chances for duplicates. It is also a good idea to add the name of the item (vehicle, object, etc.) an identifier belongs to to the name of the identifier.
   
 
With both the block name and item name in the identifier, you can also see quickly from the identifier what this is for, without having to write that down somewhere seperately.
 
With both the block name and item name in the identifier, you can also see quickly from the identifier what this is for, without having to write that down somewhere seperately.
Line 162: Line 162:
   
 
== Comments ==
 
== Comments ==
As said before, it's useful to add comments to your NML code to indicate what things are for.
+
As said before, it is useful to add comments to your NML code to indicate what things are for.
   
 
Comments can be written as comment block or as inline comment. Comment blocks go between different lines of NML code, while inline comments can also go there as well as at the end of each line.
 
Comments can be written as comment block or as inline comment. Comment blocks go between different lines of NML code, while inline comments can also go there as well as at the end of each line.
Line 179: Line 179:
   
 
<pre style="color:darkblue">
 
<pre style="color:darkblue">
//An inline comment is preceded by two slashes
+
// An inline comment is preceded by two slashes
//If you need multiple lines, each line gets two slashes in front
+
// If you need multiple lines, each line gets two slashes in front
   
 
grf {
 
grf {
name: string(STR_GRF_NAME); //it can also go at the end of a line
+
name: string(STR_GRF_NAME); // it can also go at the end of a line
 
 
 
}
 
}
Line 190: Line 190:
   
 
== Conclusion ==
 
== Conclusion ==
Yes, that's a bunch of stuff with little hands-on examples, but I warned you about that. You'll find (most of) these different blocks explained in the remainder of this tutorial. And, of course, how every block should be written is clearly documented in the [http://newgrf-specs.tt-wiki.net/wiki/NML:Block_syntax block syntax] chapter of the NML Documentation.
+
Yes, that is a bunch of stuff with little hands-on examples, but I warned you about that. You will find (most of) these different blocks explained in the remainder of this tutorial. And, of course, how every block should be written is clearly documented in the [http://newgrf-specs.tt-wiki.net/wiki/NML:Block_syntax block syntax] chapter of the NML Documentation.
   
 
{{NMLTutorialNavbar|Language files|Starting an NML file}}
 
{{NMLTutorialNavbar|Language files|Starting an NML file}}

Revision as of 17:51, 13 October 2012

This page will be a theoretical introduction to the NML syntax. It is very well possible that you do not understand anything of what is written here. If that is the case, please read the page carefully once and then just continue with the next page which will take you on an example journey through the world of coding in NML.

If you do understand this page completely, then it is very likely that you do not need the rest of this NML tutorial and just can look up what you need in the NML Documentation. At your option, you can browse through the tutorial quickly or just start making your NewGRF and figure things out as you go.


NML is a programming language

NFO is not a programming language: it is hex editing. NML on the other hand is a human-readable programming language and contains things like if/else statements, operators such as &&, ||, !=, >= etc. and curly brackets to enclose groups of statements.

If you already know a programming language such as C++ or PHP, it is probably very easy to understand and adapt to the NML syntax. If you are new to programming, you should understand a few concepts:

If you are new to programming

Name things the way you want
If you define something, it is you who gives it a name. There is no set of rules how things should be called. If you want to name everything foo0001 through foo9999, that is up to you. That does not make it very easy to remember what is what, but it is not wrong per se. However, do not use any fancy symbols in names: you may use (capital) letters a through z, numbers 0 through 9 and an underscore (_). Numbers furthermore cannot be at the beginning of the name of an identifier.
When referencing something, it needs to exist
If you want to use a string, the string needs to exists. That probably makes as much sense to you as that a circle is round, right? But it goes further than that: if you define a vehicle and want it to use this and that graphics, the graphics need to be defined before you define the vehicle that uses it. This applies to everything; if your reference something somewhere, that something needs to exists and essentially needs to be before the reference.
Compilers do not understand typos
If you make a typo, the compiler (in this case nmlc) will not understand what you mean. This especially applies to the names of things we discussed earlier. If you name your vehicle definition KirbyPaulTank, then you must use the exact capitalization everywhere. For a compiler, Kirbypaultank, kirbypaultank, kirbypaulTank etc. are all completely different things. You need to pay special attention to this if you come from Windows. In Windows, there is no difference if you give a file or directory a name with or without captials; in a programming language, with or without capitals is a completely different thing and essentially a typo when not used consistently.
Add more comments than you think is necessary
When working on a piece of code, you easily remember what does what and why you made it the way you did. However, if you do not, look at a piece of code for a couple of months, chances are you have no clue what it does if you have not commented it. Using decent names for definitions helps a great deal towards reducing the amount of comments, but ideally every code block should have a line stating what it is for and more complicated things also get comments as you go. If you do certain things differently for a reason, state why you did that. If you work with more people on one project, comments are vital in helping fellow developers understand why you did what.


NML structure: blocks

NML files are mainly composed from blocks. A block starts with the type of the block, optional arguments and then the contents enclosed by curly braces. Some blocks are supplied with an identifier (a name) as argument, some with even more arguments and some are only referenced by their type. The basic block syntax is as follows:

type {
    <block_contents>
}

or

type <identifier> {
    <block_contents>
}

or

type (<identifier>, <argument1>, [<argument2> [,...]] {
    <block_contents>
}

Note: the identifier is not necessarily the first argument of a block in case of multiple arguments.

When a block syntax is explained in the tutorial, some arguments may be optional. These are written between [ straight/square brackets ]. These brackets indicate that something is optional; the brackets are not part of the actual NML code. [,...] means that you can have any number of arguments of the same type as the previous argument. Things between < pointy/angular brackets > must be replaced with actual content. What this content must be is explained directly after the introduction of the block's syntax. Also, pointy brackets are not part of actual NML code. Round and curly brackets are part of the NML code and must be written as indicated. Words or text not between pointy brackets is also part of the NML code and must appear as indicated.


Currently, the following block types exist:

  • grf
  • item
  • recolour_sprite
  • template
  • spriteset
  • spritegroup
  • spritelayout
  • tilelayout
  • switch
  • produce
  • random_switch
  • cargotable
  • railtypetable
  • error
  • disable_item
  • deactivate
  • engine_override
  • replace
  • replacenew
  • font_glpyh
  • alt_sprites
  • town_names
  • snowline
  • basecost

Some special "blocks", which are not really blocks, but language constructs, exist as well:

  • if
  • else

Furthermore, there are too many functions to list here. For now, you can forget these if you want, but it is good to have seen their names.

The blocks define things that can be referenced or make new things available in the game. Some blocks can contain sub-blocks. The grf block can contain a param subblock to add parameter settings. The item block can contain property, graphics and livery_override subblocks.

If you need to do some calculations, you do those outside the blocks, or in some special cases, in a block's expression argument, but never inside a block. ifs and elses also have no place inside blocks and can only be used outside them.

Identifiers

As you have read earlier, some blocks need to have an identifier. You can see this identifier as a name for the block and you choose this identifier yourself.

All identifiers need to be unique throughout you NML file! This even applies for identifiers of totally different blocks. An easy method to avoid duplicate identifiers is to precede the identifier name with the name of the block type. While this is not foolproof, it simply reduces the chances for duplicates. It is also a good idea to add the name of the item (vehicle, object, etc.) an identifier belongs to to the name of the identifier.

With both the block name and item name in the identifier, you can also see quickly from the identifier what this is for, without having to write that down somewhere seperately.


Features

Some blocks can do multiple things. For example, the item can define a train, but also a road vehicle, ship, or aircraft. In case of such a block, you need to set which feature the block is for and supply this to the block as an argument. Below is a table of available features:

Name Description
FEAT_TRAINS Trains
FEAT_ROADVEHS Road vehicles
FEAT_SHIPS Ships
FEAT_AIRCRAFT Aircraft
FEAT_STATIONS Train stations
FEAT_CANALS Canals
FEAT_BRIDGES Bridges
FEAT_HOUSES Town houses
FEAT_GLOBALVARS Various global variables
FEAT_INDUSTRYTILES Industry tiles (visible part of industries)
FEAT_INDUSTRIES Industries
FEAT_CARGOS Cargo types
FEAT_SOUNDEFFECTS Sound effects
FEAT_AIRPORTS Airports
FEAT_SIGNALS Train signals
FEAT_OBJECTS Non-interactive objects (example: lighthouse)
FEAT_RAILTYPES Rail types
FEAT_AIRPORTTILES Airport tiles (visible part of airports)


Comments

As said before, it is useful to add comments to your NML code to indicate what things are for.

Comments can be written as comment block or as inline comment. Comment blocks go between different lines of NML code, while inline comments can also go there as well as at the end of each line.

Comment block example:

/*
This is a comment block, it starts with a slash and an asterisk.
It can span multiple lines
Before it ends with an asterisk and a slash
*/

Inline comment example:

// An inline comment is preceded by two slashes
// If you need multiple lines, each line gets two slashes in front

grf {
    name: string(STR_GRF_NAME); // it can also go at the end of a line
    
}


Conclusion

Yes, that is a bunch of stuff with little hands-on examples, but I warned you about that. You will find (most of) these different blocks explained in the remainder of this tutorial. And, of course, how every block should be written is clearly documented in the block syntax chapter of the NML Documentation.


NML Tutorial: NML Syntax