Difference between revisions of "NMLTutorial"

From TTWiki
(note on how to read the tutorial and navbar)
(slightly update language comparison)
Line 11: Line 11:
   
 
===Language support===
 
===Language support===
NML provides easy support for different languages in one GRF. This is achieved by creating language files (LNG). These language files follow the convention used for OpenTTD translation files. When compiling NML files a search for language files will automatically be performed. Even without providing additional translations at least one language file must be specified, called default.lng.
+
NML provides easy support for different languages in one GRF. This is achieved by creating language files (lng). These language files follow the convention used for OpenTTD translation files. When compiling NML files a search for language files will automatically be performed. Even without providing additional translations at least one language file must be specified, called default.lng.
   
 
===Image format support===
 
===Image format support===
One of the conveniences of NML is the possibility to read other image formats, most notably [http://en.wikipedia.org/wiki/Portable_Network_Graphics PNG]. Remember though that those images still need to supply the proper 8bpp palette and are supported by the python image library.
+
One of the conveniences of NML is the possibility to read various image formats. Remember though that those images still need to supply the proper 8bpp palette and are supported by the python image library.
   
 
===Example===
 
===Example===
Line 25: Line 25:
 
<font size="3">'''NFO code snippet'''</font>
 
<font size="3">'''NFO code snippet'''</font>
 
:// Automatically generated by GRFCODEC. Do not modify!
 
:// Automatically generated by GRFCODEC. Do not modify!
:// (Info version 7)
 
:// Escapes: 2+ = 71 = D= = DR 2- = 70 = D+ = DF 2< = 7= = D- = DC 2> = 7! = Du* = DM 2u< = 7< = D* = DnF 2u> = 7> = Du<< = DnC
 
:2/ = 7G = D<< = DO 2% = 7g = D& 2u/ = 7gG = D| 2u% = 7GG = Du/ 2* = 7gg = D/ 2& = 7c = Du% 2| = 7C = D% 2^ 2sto = 2s 2rst = 2r 2+ 2ror = 2rot
 
:// Format: spritenum pcxfile xpos ypos compression ysize xsize xrel yrel
 
   
 
:0 * 4 \d416
 
:0 * 4 \d416

Revision as of 19:18, 22 August 2011

Introduction

Since june 2010 a new coding language for creating TTDpatch/OpenTTD GRF's exists: Newgrf Meta Language or NML. It differs significantly from the old way of GRF editing and although documentation is available it may still be a challenge for people interested in using NML code. After all NML is still a form of programming language and not a GUI-based editor.

There will be detailed examples of how coding in NML works on this new TT-wiki. Make sure to check the progress of this NML tutorial regularly.

NML vs. NFO

Background

NML is a high-level NewGRF language compiler which compiles NML and LNG files into newgrf files (and NFO files, if asked to do so). Coding a NewGRF in NML is similar to writing in any other programming language except that there are no real sub-routines; you can use the usual definition and condition statements.

Language support

NML provides easy support for different languages in one GRF. This is achieved by creating language files (lng). These language files follow the convention used for OpenTTD translation files. When compiling NML files a search for language files will automatically be performed. Even without providing additional translations at least one language file must be specified, called default.lng.

Image format support

One of the conveniences of NML is the possibility to read various image formats. Remember though that those images still need to supply the proper 8bpp palette and are supported by the python image library.

Example

Does the above sound impressive, maybe even threatening to you? One illustration often says more than a thousand words so let's show the difference with two illustrations:

NFO code snippet

// Automatically generated by GRFCODEC. Do not modify!
0 * 4 \d416
1 * 92 08 07 "SER0" "ÞSwedish Rails nightly-r52M" 00 "ÞSwedish rails are a replacement for the default rails" 00

NML code snippet

grf {
grfid : "SER0";
name : string(STR_GRF_NAME);
desc : string(STR_GRF_DESCRIPTION);
}

NML language file snippet

##grflangid 0x01
STR_GRF_NAME  :Swedish Rails {VERSION}
STR_GRF_DESCRIPTION  :Swedish rails are a replacement for the default rails


How to read the NML tutorial

The NML Tutorial starts with the installation of NML and continues from there as single "story" if you like. The bottom of each tutorial page has a link to the next page (and the previous in case you missed something) and all pages from the tutorial are also listed in navigation box at the top right of each page.

Example NML code is displayed in a code box and a blue font colour (much like the NML documentation itself). Code syntax definitions and other code and command (snippets) are displayed in black, either in a code box or in line with the text.

//example NML code
block {
    //block definition
    item: value;
}

If you have any questions about the text and examples within the NML tutorial, you are welcome to post those in the [link_to_be_added NML Tutorial topic] at TT-Forums. If you see bugs in the tutorial, you of course fix them or discuss them in the topic linked above first. Expanding or changing the tutorial should only be done by people who actually know NML and don't need this tutorial to code their NML files.


NML Tutorial: NMLTutorial