NMLTutorial/Starting an NML file - Revision history

Planetmaker: NML doesn't work with TTDP anyway

2015-02-04T22:12:53Z

NML doesn't work with TTDP anyway

← Older revision		Revision as of 22:12, 4 February 2015
Line 136:		Line 136:
	Sometimes it happens that you have to break compatibility between different releases of your NewGRF. The NML Documentation has a separate chapter on [http://newgrf-specs.tt-wiki.net/wiki/NML:NewGRF_compatibility NewGRF compatibility] and what actions break compatibility and how to avoid breaking it in the first place.		Sometimes it happens that you have to break compatibility between different releases of your NewGRF. The NML Documentation has a separate chapter on [http://newgrf-specs.tt-wiki.net/wiki/NML:NewGRF_compatibility NewGRF compatibility] and what actions break compatibility and how to avoid breaking it in the first place.

	However, if you must break compatibility, here's how to handle the version information in your NML file.		However, if you must break compatibility, here's how to handle the version information in your NML file:

	=== OpenTTD targeted NewGRFs ===
	* Keep the GRFID you have;		* Keep the GRFID you have;
	* Don't forget to update <code>grf { version }</code>;		* Don't forget to update <code>grf { version }</code>;
Line 144:		Line 143:

	This way, OpenTTD will hide the old release from the NewGRF window while keeping it available for older savegames to use (provided the user doesn't delete the old release). Old releases can still be downloaded from BaNaNaS for old savegames.		This way, OpenTTD will hide the old release from the NewGRF window while keeping it available for older savegames to use (provided the user doesn't delete the old release). Old releases can still be downloaded from BaNaNaS for old savegames.

	=== TTDPatch targeted NewGRFs ===
	TTDPatch doesn't have a concept for <code>grf { min_compatible_version }</code> (or <code>grf { version }</code> for that matter). The only way to indicate broken compatibility in TTDPatch is to bump the GRFID. This means that you increase the last byte of the GRFID by one. So if your initial GRFID is <code>"SF\01\01"</code>, change it to <code>"SF\01\02"</code> for the next release.

	As a consequence, both NewGRFs can be used separate from each other and in OpenTTD both will show up in the NewGRF window.

	In order to avoid loading both the old version and the new version in the same game, you have to add a [[NMLTutorial/Version check\|version check]] to the NewGRF in order to disable itself (or the older version).

	{{NMLTutorialNavbar\|NML Syntax\|Road vehicle}}		{{NMLTutorialNavbar\|NML Syntax\|Road vehicle}}

FooBar: pre class

2011-08-27T22:19:32Z

pre class

← Older revision		Revision as of 22:19, 27 August 2011
Line 22:		Line 22:
	The general syntax of the grf block is:		The general syntax of the grf block is:

	<pre>		<pre class="pseudo">
	grf {		grf {
	grfid: <literal-string>;		grfid: <literal-string>;

Yexo: /* Summarizing */ don't advocate -u, -c is good, but not necesary for a basic tutorial

2011-08-22T22:12:37Z

Summarizing: don't advocate -u, -c is good, but not necesary for a basic tutorial

← Older revision		Revision as of 22:12, 22 August 2011
Line 129:		Line 129:
	You still remember how to use ''nmlc' on the command line, right? If not, check the [[NMLTutorial/Installation\|Installation page]] with the details for your operating system, or maybe the following pointer is enough to get you going:		You still remember how to use ''nmlc' on the command line, right? If not, check the [[NMLTutorial/Installation\|Installation page]] with the details for your operating system, or maybe the following pointer is enough to get you going:

	nmlc -u --grf mygrf.grf mygrf.nml		nmlc --grf mygrf.grf mygrf.nml

	{{NMLTutorialNavbar\|NML Syntax\|Road vehicle}} <!-- this is here a second time because not everybody may need to read the following section -->		{{NMLTutorialNavbar\|NML Syntax\|Road vehicle}} <!-- this is here a second time because not everybody may need to read the following section -->

FooBar: /* Summarizing */ initial version at 0

2011-08-22T21:42:59Z

Summarizing: initial version at 0

← Older revision		Revision as of 21:42, 22 August 2011
Line 120:		Line 120:
	name: string(STR_GRF_NAME);		name: string(STR_GRF_NAME);
	desc: string(STR_GRF_DESCRIPTION);		desc: string(STR_GRF_DESCRIPTION);
	version: 1;		version: 0;
	min_compatible_version: 1;		min_compatible_version: 0;
	}		}
	</pre>		</pre>
Line 132:		Line 132:

	{{NMLTutorialNavbar\|NML Syntax\|Road vehicle}} <!-- this is here a second time because not everybody may need to read the following section -->		{{NMLTutorialNavbar\|NML Syntax\|Road vehicle}} <!-- this is here a second time because not everybody may need to read the following section -->


	== Breaking compatibility ==		== Breaking compatibility ==

Ammler: /* Line 5: version: ; */ first commit is r0

2011-08-22T18:38:36Z

Line 5: version: ;: first commit is r0

← Older revision		Revision as of 18:38, 22 August 2011
Line 75:		Line 75:
	Another version? Yes. If your NewGRF is aimed at (but not limited to) OpenTTD you should use this to indicate the actual version and leave the GRFID constant. If your NewGRF is aimed at (but not limited to) TTDPatch you still should provide this version number, but ''bump the GRFID'' whenever a new release is not compatible with the previous release. More on this at the end of this page.		Another version? Yes. If your NewGRF is aimed at (but not limited to) OpenTTD you should use this to indicate the actual version and leave the GRFID constant. If your NewGRF is aimed at (but not limited to) TTDPatch you still should provide this version number, but ''bump the GRFID'' whenever a new release is not compatible with the previous release. More on this at the end of this page.

	The first release of your NewGRF will start with version 1 and every subsequent release you will increase this value. In case you use a version control system, set this to the revision number.		The first release of your NewGRF will start with version 0 and every subsequent release you will increase this value. In case you use a version control system, set this to the revision number.

	This gives line five:		This gives line five:

	<pre style="color:darkblue">		<pre style="color:darkblue">
	version: 1;		version: 0;
	</pre>		</pre>

Ammler: /* Line 6: min_compatible_version: ; */ 0, not 1 (example)

2011-08-22T18:36:47Z

Line 6: min_compatible_version: ;: 0, not 1 (example)

← Older revision		Revision as of 18:36, 22 August 2011
Line 84:		Line 84:

	=== Line 6: min_compatible_version: <expression>; ===		=== Line 6: min_compatible_version: <expression>; ===
	For the first release, the minimal compatible version is also 1. Leave it at 1 for as long as subsequent releases are compatible with all previous releases. Whenever you need to break compatibility, you set this to the version number (from above) in which you have broken the compatibility.		For the first release, the minimal compatible version is also 0. Leave it at 0 for as long as subsequent releases are compatible with all previous releases. Whenever you need to break compatibility, you set this to the version number (from above) in which you have broken the compatibility.

	Line six:		Line six:

	<pre style="color:darkblue">		<pre style="color:darkblue">
	min_compatible_version: 1;		min_compatible_version: 0;
	</pre>		</pre>

FooBar: What to first put in the NML file

2011-08-22T16:28:31Z

What to first put in the NML file

New page

{{NMLTutorial}}

It's time to create your first NML file! All this reading must have made you hungry by now, so let's continue right quick.

== Where to put the NML file ==

From the [[NMLTutorial/Language files|Language files]] section you may remember this folder structure:

mygrf
|- lang
| |- english.lng
| |- other_language.lng
|- custom_tags.txt
|- mygrf.nml

This is exactly where the NML file should go: one folder above the language files, and in the same folder as custom_tags.txt. You can name the file any way you want, but try to avoid spaces. Create it either from the file explorer or from your text editor.

== The grf block ==
Nearly all NML files will start with a grf block. The grf block takes no parameters and is one of the simplest blocks there is. Your NML file also has no more than one grf block. NML files without a grf block are only useful for ''base graphic'' files such as the grf files from OpenGFX. So chances are that you need a grf block.

The general syntax of the grf block is:

<pre>
grf {
grfid: <literal-string>;
name: <string>;
desc: <string>;
version: <expression>;
min_compatible_version: <expression>;
}
</pre>

We'll be looking at every line of this grf block and give you an example how to fill it in.

=== Line 1: grf { ===
This indicates the start of the grf block and the ''opening curly bracket'' defines the start of it's contents. Just type it in your editor:

<pre style="color:darkblue">
grf {
</pre>

=== Line 2: grfid: <literal-string>; ===
This defines the GRFID of your NewGRF. A GRFID is a four-byte string that should be unique. If two NewGRFs have the same GRFID, only one can be used at a time and in OpenTTD chances are only one shows up in the NewGRF list. It's a convention to use the first two bytes for the creator's initials. The last two bytes should be numbers, typically the first number identifying which of the author's sets this is, and the second number being a version number.

The GRFID must be written as a quoted string, but now comes the complicated part: one character is one byte, but one byte is two hexadecimal characters. The first two bytes are best written as a normal quoted string. The last two are best written as escaped bytes, as this allows for 256 sets/versions rather than just 10.

So if your name is Simon Foster and you're starting the first version of your first set, your GRFID can be <code>"SF\01\01"</code>. This way, your GRFID is exactly four bytes: two normal characters S and F, and two escaped bytes 01. The backslash indicates that the next two characters together make one byte. When using escaped bytes, remember that they are in hex and as such can only consist the numbers 0-9 and letters A-F. See [http://en.wikipedia.org/wiki/Hexadecimal Wikipedia] for more details on the hexadecimal numeral system.

Now your second line of the nml file will be (but then with your own GRFID):

<pre style="color:darkblue">
grfid: "SF\01\01";
</pre>

=== Line 3: name: <string>; ===
This is the name of your NewGRF, as displayed ingame. NML expects a reference to a string in your language file here. Luckily, we [[NMLTutorial/Language files|already]] put a name for our NewGRF in there. Open the language file and check what name you attached to the string. In our example that would be <code>STR_GRF_NAME</code>.

To tell NML to use a string from the language file, you have to use the function <code>string(<string-name>)</code>, replacing <code><string-name></code> with the actual name of the string. This gives us <code>string(STR_GRF_NAME)</code>.

Put this in the third line:

<pre style="color:darkblue">
name: string(STR_GRF_NAME);
</pre>

=== Line 4: desc: <string>; ===
The description is similar to the name of the NewGRF. Again look up the name of the string in the language file and use the <code>string()</code> function to put it in the grf block. Line four:

<pre style="color:darkblue">
desc: string(STR_GRF_DESCRIPTION);
</pre>

=== Line 5: version: <expression>; ===
Another version? Yes. If your NewGRF is aimed at (but not limited to) OpenTTD you should use this to indicate the actual version and leave the GRFID constant. If your NewGRF is aimed at (but not limited to) TTDPatch you still should provide this version number, but ''bump the GRFID'' whenever a new release is not compatible with the previous release. More on this at the end of this page.

The first release of your NewGRF will start with version 1 and every subsequent release you will increase this value. In case you use a version control system, set this to the revision number.

This gives line five:

<pre style="color:darkblue">
version: 1;
</pre>

=== Line 6: min_compatible_version: <expression>; ===
For the first release, the minimal compatible version is also 1. Leave it at 1 for as long as subsequent releases are compatible with all previous releases. Whenever you need to break compatibility, you set this to the version number (from above) in which you have broken the compatibility.

Line six:

<pre style="color:darkblue">
min_compatible_version: 1;
</pre>

=== Line 7: } ===
The ''closing curly bracket'' defines the end of the grf block; it closes it if you will.

Just type a curly bracket on line seven:

<pre style="color:darkblue">
}
</pre>

== Summarizing ==
Already? You haven't told us about the semicolons at the end of each line in the grf block!

I haven't? Well, let's do that now then...

=== Semicolons ===
Like in a lot of other programming languages, a semicolon defines the end of an instruction. You must use these at the end of every instruction inside and outside a block, but not on lines that open or close a block (with a curly bracket).

The usage of semicolons in NML is identical (with the exception of templates) to that in Java or C-family (or PHP) languages. It allows to have multiple instructions on one line, which is useful in some cases.

=== Summarizing ===
This completes our grf block. All lines together, the example looks like this:

<pre style="color:darkblue">
grf {
grfid: "SF\01\01";
name: string(STR_GRF_NAME);
desc: string(STR_GRF_DESCRIPTION);
version: 1;
min_compatible_version: 1;
}
</pre>

If you like, you can encode this into a grf to see if it works. The grf will not do anything, but it should show up in the game if you add it.

You still remember how to use ''nmlc' on the command line, right? If not, check the [[NMLTutorial/Installation|Installation page]] with the details for your operating system, or maybe the following pointer is enough to get you going:

nmlc -u --grf mygrf.grf mygrf.nml

{{NMLTutorialNavbar|NML Syntax|Road vehicle}} 

== Breaking compatibility ==
Sometimes it happens that you have to break compatibility between different releases of your NewGRF. The NML Documentation has a separate chapter on [http://newgrf-specs.tt-wiki.net/wiki/NML:NewGRF_compatibility NewGRF compatibility] and what actions break compatibility and how to avoid breaking it in the first place.

However, if you must break compatibility, here's how to handle the version information in your NML file.

=== OpenTTD targeted NewGRFs ===
* Keep the GRFID you have;
* Don't forget to update <code>grf { version }</code>;
* Set <code>grf { min_compatible_version }</code> to the value of <code>grf { version }</code>.

This way, OpenTTD will hide the old release from the NewGRF window while keeping it available for older savegames to use (provided the user doesn't delete the old release). Old releases can still be downloaded from BaNaNaS for old savegames.

=== TTDPatch targeted NewGRFs ===
TTDPatch doesn't have a concept for <code>grf { min_compatible_version }</code> (or <code>grf { version }</code> for that matter). The only way to indicate broken compatibility in TTDPatch is to bump the GRFID. This means that you increase the last byte of the GRFID by one. So if your initial GRFID is <code>"SF\01\01"</code>, change it to <code>"SF\01\02"</code> for the next release.

As a consequence, both NewGRFs can be used separate from each other and in OpenTTD both will show up in the NewGRF window.

In order to avoid loading both the old version and the new version in the same game, you have to add a [[NMLTutorial/Version check|version check]] to the NewGRF in order to disable itself (or the older version).

{{NMLTutorialNavbar|NML Syntax|Road vehicle}}