NMLTutorial/Item
An item block is a block that defines a (new) vehicle, station, industry, object, etc. This is one of those blocks that come with multiple arguments and need a feature defined (remember the NML Syntax page?).
Item block syntax
The general syntax for the item block is as follows:
item (<feature> [, <identifier> [, <ID>]]) {
[<property-block>]
[<graphics-block>]
[<livery_override-block>]
}
In words this means you start with item followed by an opening bracket, then the identifier for the feature you want to define the item for, then an (optional, but recommended) identifier for this item block and finally an (optional, not recommended) numerical ID for the item. Followed by a closing bracket and an opening curly bracket.
The feature needs to be selected from a list of features. The identifier is a self-chosen name for this feature. It's useful to start the identifier with item_ followed by the name of the vehicle/station/industry/object/etc.. This prevents duplication with future identifier for other blocks for this item and is somewhat a guarantee that this identifier is unique.
ID is something you only need if you want to define an item for a specific NFO ID. If you want that, write a number here, otherwise just omit it. New NewGRFs need normally not to have specific NFO IDs defined, as NML will automatically assign the first available ID if you don't override it with this.
Item block contents
In the item block you define at least one property block, one graphics block and/or one livery_override block. Multiple of these blocks can go into the item block at the same time (even multiple property blocks, although that doesn't make much sense). If you want nothing too fancy, you'll only have one property block and one graphics block in the item block.
Property block
The property block, as the name suggests, defines the properties for the item you're defining. In case of a vehicle, you can think of such properties as speed, weight, capacity etc. But there are much more properties available, so you need to look them up in the NML Documentation for the feature you are defining.
The general syntax of the property block is:
property {
<property>: <value>;
[<property2>: <value2>;]
[...;]
}
So you define multiple properties in one property block. Property and value are separated by a colon and property/value pairs are each separated by a semicolon.
Graphics block
The graphics block allows to link the item to a graphics definition or to callbacks. You can have the graphics definition also depend on several variables via an intermediate (random_)switch block. More about switch blocks and callbacks later.
The general syntax of the property block is:
graphics {
<callback>: <identifier>|<return_value>;
[<callback2>: <identifier2>|<return_value2>;]
[...;]
}
For the purpose of this syntax, the links to graphic definitions are also called "callbacks" and can only be combined with an identifier. Real callbacks can also return values directy from the graphics definition or link to (random_)switch block.
For graphics alone, the two "callbacks" default and purchase are of most interest. The default links to the graphics definition for the item itself. The purchase links to a graphics definition specifically for the purchase menu of the feature.
What <callback>s are available for each feature must be looked up in the NML Documentation for the feature you are defining. Callback and identifier/return_value are separated by a colon and these pairs are each separated by a semicolon.
Livery_override block
The livery_override block is (only) available for train engines and allows to change the appearance of wagons attached to a train engine. As this is an advanced feature of NewGRFs and this is a tutorial, we'll not be elaborating on livery_override blocks here. Once you understand how to define normal graphics, you can easily figure this out yourself.
This concludes the theory you need to know about item blocks. Let's continue our road vehicle and add an item block for that.
NML Tutorial: Item
