The m4nfo User Manual and Report

The m4nfo User Manual and Report

Show full frameset for easy navigation

Introduction

m4nfo, proposed and implemented since 2009, is a high-level language frontend for generating low-level nfo byte-code. nfo byte-code is a machine-oriented language developed by Josef Drexler in 2000 for programming 'new' game ressource files (newGRFs) for the successors of the game Transport Tycoon, namely TTDPatch and OpenTTD.

To provide newGRF developers with a high level of control, flexibility and support, m4nfo pursues a two-fold approach: whilst retaining the efficiency characteristic of plain nfo, with the prior-ranking aim to generate small and fast code, it introduces higher abstraction levels where it makes sense for the developer, considering established newGRF coding habits.

To achieve these goals, m4nfo has been implemented as a set of small modules instead as a large monolithic application. There are separate modules for trains, stations, objects, ..., reflecting the fact that most of the time a newGRF only deals with one of TTD's 'features'.

This approach doesn't only keep m4nfo small and lightweight (M4: 143kB, module 'trains': 50kB), it also allows to use identical identifiers and names for same methods on different features, keeping its name space small, and avoiding redundant labeling.

Taking into account the modular structure of m4nfo, it is also very easy to add extra user-supplied functions or even whole modules. This can be done either 'on-the-fly', by placing new functions directly inside of the user's source files; or it could be done by adding additional include files, containing larger numbers of new functions. It is even possible to pre-compile user-supplied modules, or - rather exotic - include sections of plain nfo code directly into m4nfo source files.

In addition, m4nfo natively includes a powerful macro processor suitable for private customizing or templating applications (indeed, m4nfo is written in M4, a very efficient macro processor itself), so there's no need for any external tools, like CPP for macro usage or artificially crafted extra Python layers, resulting in bloated installations.

There are pre-compiled modules, needing no m4nfo system include files and running even slightly faster, for most of TTD's features, which might be easily used manually or from a makefile script.

In conclusion, m4nfo is best used for large projects because of unrivalled speed and code efficiency, the latter only depending on the experience of the coder, because there is no additional overhead introduced by the compiling process. Last but not least, the ability of m4nfo to handle distributed source files including "linking" of pre-compiled grf part files, is best suited when using a dependency-tracking build utility like 'Make', to constitute an efficient programming environment for the really large projects.

Use cases

DBXL (by mb)

The DB Set XL (v0.9) is a large newGRF providing a huge number of German trains, locomotives, coaches and freight cars, utilising existing newGRF specs to full capacity. Written in m4nfo, the set could be "squeezed" into only 2 MBytes, by using templating, procedure calls and other code compaction methods. Applying m4nfo's features of distributing source files and linking of part newGRF files also helped to reduce developing time.

French NG set (by Snail)

The French Narrow Gauge Set is another train set being coded in m4nfo. In contrast to its name, this is a large set, even larger than the DB Set, because of its sophisticated approach to model usage of real life prototype vehicles to a very high degree of detail. Here, excessive templating achieved in organizing a large and intricate codebase. In addition, it demonstrated applicability of m4nfo under OSX.

German RV Set (by Uwe)

This set includes a large number of trams and buses/coaches which come in historic and real-life liveries from dozens of German towns. Thus, implementation required to handle a very large number of 2cc and custom recolouring maps, which could be easily done in m4nfo.


MariCo (by mb)

Another large set, but this time exclusively dealing with the newobjects feature. The very nature of this set demanded clever handling of all sorts of slopes and foundations, as well as use of complex animations and recolouring tasks. m4nfo's tools for modularization were indispensable prerequisites for a proper implementation.


NewStations (by mb)

NewStations v0.6 is a quite large station set, using tricky newGRF features like recolouring, animation and some of the more 'unexplored' features for stations. m4nfo's implements for handling station layouts as well as being able to template them were essential requirements here.


Content

This documentation consists of three parts. The User Manual is directed to those having previously acquired some familiarity with nfo programming, and who wish to get access to a more user-friendly style of newGRF creation. Hence, the style of the Manual is more or less that of a tutorial, with many examples included to demonstrate the various features of m4nfo.

In addition, the manual includes an Index which offers a listing of all m4nfo constants and functions.

OTOH, the Report is intended to serve as a concise reference for both newGRF programmers and m4nfo re-implementors. It defines a standard as a common base between various additional implementations of m4nfo (e.g. for industries and buildings).

Last, there's a Tutorial, at the moment only about use of callbacks and animation, but will be growing in the future.