NMLTutorial/Object

NML Tutorial

Installation

Graphics files

Language files

NML Syntax

Starting an NML file (grf block)

• Creating a road vehicle

Item blocks

• • Item definition

Spriteset & spritegroup blocks

• • Adding the graphics

Template blocks

• • Templating the graphics

Cargotable block

• • Cargo-dependent graphics

Callbacks and switch blocks

• Creating a tram

• • Make it articulated

• • Adding the graphics

• • Fix the purchase menu

• Creating a train

Railtypetable block

• • Single engine

• • Three part articulated

• • Four part refit

GRF Parameters

• • Real life recolour scheme

• Creating an object

Spritelayout blocks

• • Adding the graphics

Version checks

• • Objects on slopes

32 bit sprites

• Adding 32 bit sprites

Base graphics replacement

• 32 bit base graphics

Conclusion

Glossary

NML Documentation

The example used here is from the Dutch Road Furniture. The original graphics for this are by FooBar. The code is by FooBar, based on code for the object example from the NML source by planetmaker and Hirundo. Code and graphics are both licensed according to the GPL v2 or later. The code has been modified for the purpose of this tutorial.

Introduction

Objects, as well as stations, houses, industry tiles and airport tiles are coded slightly differently than vehicles. This difference mainly has to do with how sprites are defined. Item blocks and callbacks with switch blocks are still used as before, so our focus will be mainly on the graphics part. Stations are currently not yet possible in NML.

In this example we will make an object with four views to be used on flat ground tiles. After that we'll also make this object work on slopes, using some advanced features available in OpenTTD.

Folder structure

For this example we'll assume the following folder structure. There will be one language file in the lang folder, one graphics file in the gfx folder. These two folders sit together with the main NML file in one project folder:

object_example
 |- lang
 |   |- english.lng
 |- gfx
 |   |- dutch_fingerpost.png
 |- custom_tags.txt
 |- example_object.nml

NML file

Start the NML file by adding a grf block.

grf {
    grfid:                  "\FB\FB\05\01";
    name:                   string(STR_GRF_NAME);
    desc:                   string(STR_GRF_DESCRIPTION);
    version:                0;
    min_compatible_version: 0;
}

Nothing fancy there, just like we used to do and starting at version 0.

Item definition and property block

The item block for an object looks very similar to that of a vehicle. Of course now you use FEAT_OBJECTS as feature and give it an identifier of your choice. In the item block you add a property block listing the properties for the object and a graphics block:

item (FEAT_OBJECTS, item_fingerpost_3) {
    property {
        class:                  "NLRF";
        classname:              string(STR_NLRF);
        name:                   string(STR_FINGERPOST_3);
        climates_available:     ALL_CLIMATES;
        size:                   [1,1];
        build_cost_multiplier:  2;
        remove_cost_multiplier: 8;
        introduction_date:      date(1961,1,1);
        end_of_life_date:       0xFFFFFFFF;
        object_flags:           bitmask(OBJ_FLAG_REMOVE_IS_INCOME, OBJ_FLAG_NO_FOUNDATIONS, OBJ_FLAG_ALLOW_BRIDGE);
        height:                 2;
        num_views:              4;
    }
    graphics {
        additional_text:    string(STR_FINGERPOST_3_PURCHASE);
    }
}

property block

Some properties may need a little explaining; others should be self-explanatory or check the NML Documentation for details.

class

A four character string using only capital letters and numbers. This defines in what "group" this object is added in the object construction window. If you only have a few objects in your set, try to use a default object class. If you have a comprehensive set with a lot of objects, it might make sense to define a custom class (register it on the page linked).

classname

At least one object in each class needs to define the name of the class as string to be displayed in the object construction window.

size

Define the size in the format [x,y]. Objects are rectangular up to 15x15 tiles.

end_of_life_date

At which date the object becomes unavailable for purchase. Can be a date() or set to 0xFFFFFFFF to use the maximum value possible.

height

In multiples of 16 pixels. Use 0 for flat objects, 1 for objects up to 16 pixels high, 2 for objects up to 32 pixels high etc.

num_views

Each object may have 1, 2 or 4 views. This can be used for rotations of the object or alternatively up to four different variations of the same object.

graphics block

We'll add the graphics later, so for now we only define a callback here to show a description of the object in the purchase menu. The callback used for this is additional_text and can directly return a string from the graphics block.

Language file

Only English as default language with NewGRF name and description. Also the strings from the item block for the object class name, the own name of the object and a purchase menu description are added

##grflangid 0x01

#Main grf title and description
STR_GRF_NAME        :{TITLE}
STR_GRF_DESCRIPTION :Description: {SILVER}Dutch Road Furniture is an eyecandy object NewGRF that features road furniture that can be found alongside Dutch roads. {}(c)2011 FooBar. {}{BLACK}License: {SILVER}GPLv2 or higher.

#object classes
STR_NLRF            :Dutch Road Furniture

#object name and description
STR_FINGERPOST_3            :Dutch Fingerpost three-way
STR_FINGERPOST_3_PURCHASE   :The three-way fingerpost is centered at one side of the tile and facing outward. Intended to be placed directly opposite of the secondary road at a three-way junction.

custom_tags.txt this time contains the {TITLE} of the NewGRF, see the introduction to language files for more details about the usage of custom_tags.txt.

That should have you started nicely. Next we'll look into spritelayout blocks which are used for the graphics of objects.

« Train recolour

NML Tutorial: Object

Spritelayout »