NewGRF Recommended Standards

From OpenTTD
Jump to: navigation, search

This is a draft for discussion. Draft mostly be andythenorth, with some contributions from others.

This page needs grouping into logical sections.



  • It's recommended that a grf only provides a limited range of things at once. E.g. only one of the following: Trains, Road vehicles (trams + road), Aircraft, Ships, Stations, Houses, Industries + Cargos, New objects, Airports, Railtypes, BaseCosts, Landscape, TownNames etc.
    • A specific exception is industries and cargos. An industry newgrf should also provide cargos. No other type of newgrf set should modify cargos, this causes numerous problems for players and other set authors.
    • Mixing trams and normal road vehicles is often acceptable, but consider if players would prefer separate tram and road vehicle sets.
  • If you do mix things in a set, provide parameters that allow players to turn groups of things on or off.
  • If your set is large and provides many vehicles or objects, consider identifying 'core' and 'extra' items, with parameters to turn them on or off. Consider defaulting to 'off' for the extra items - this is useful to admins of multiplayer servers.
  • If your set provides a complete replacement for all vehicles of a certain type (e.g. trains), consider disabling the default vehicles. If your set is just an add-on with a few vehicles, leave the default vehicles alone.

You're not alone...

  • Use a compatibility check to identify incompatible grfs and display an informative message so that it is easy for the end user to find out what is wrong and where.
  • A set is more compatible if it doesn't try to fix game balance wrt base costs on its own. When defining vehicles try to use the default vehicles' purchase and running costs as a reference to balance again. The general price levels can then consistently be changed by all vehicle NewGRFs in a single base cost NewGRFs. If all vehicle NewGRFs do that, there'll be no balance issue between them.
  • Try to provide a parameter switch for both purchase and running costs. Not all vehicle NewGRFs balance against default vehicles, thus you allow to adjust prices wrt other vehicle NewGRFs - and a common base cost NewGRF can then still set price balance to desired levels. You can even try to detect the parameters of your vehicle NewGRFs, if you provide a base cost balance NewGRF and react accordingly
  • Never disable other grfs. Instead disable your own, with a warning message.

Make it easy for the user

  • If you use parameters, use action 14 so that OpenTTD can provide a GUI for them.
  • If a newer version of your grf is not savegame-compatible with an older version of your grf, use action 14 to provide a check. Do not change the grfid to handle savegame compatibility unless you have a sound reason to do so (WHAT WOULD BE A GOOD REASON?).
  • Include a readme.txt with your set, unless it's so simple you don't need it. Also include a license file with your grf which describes which license you are releasing the grf under. This can be included in the readme.
  • When uploading to Bananas, try to provide a good description, as best as you can within the limited amount of text available.


  • Use the GNU Public License or a Creative Commons license. This makes it easier for others to collaborate with you. It also means your work can be maintained and updated in future - this is often needed when a set author no longer has the time to work on their grf.
  • Make sure you include your license information with your grf in any tars / zips.
  • It's strongly recommended to use a version-control system (VCS) for your code and graphics. Numerous authors have lost work due to hard drive crashes and other problems. A VCS can prevent this loss by keeping copies of your work on a remote server. It also makes it easier for you to maintain your set, and for others to collaborate with you. If you don't know how to use version-control, we can happily teach you. The #openttdcoop DevZone provides version-control repositories to newgrf projects for free.
  • If you don't have your own build system, you might consider the #openttdcoop DevZone's build system for newgrfs. These work with nml or nfo, and make it easier to build and distribute your newgrf.

Respect other artists and authors

  • If reusing assets from a GPL (or other freely licensed) set, it's not required but still nice to ask first, by forum pm or posting in the thread. It's certainly not required, but it's considered a compliment and might pay in the form that you might get valuable advice or even help :)
  • Always give the proper credits when you use work from other artists and programmers, whether you took it from existing work under a free license or use it under special permission. Credits is all the original creators have from their work, honour it.

Graphics guidelines

  • Most original TTD graphics are drawn with the light source in the lower right of the screen (about "4.30 o'clock"). The light source is best imagined as 'high up in the sky'. Shadows fall towards the top-left of the screen. There are places which incorrectly state that light comes from the top-right. If you want your graphics to be compatible with original TTD style, don't be mistaken about the lighting. [1]
  • Using sprite templates makes your life easier. Sprite templates exist for trains (by pikka) and road vehicles (modified from pikka templates by andythenorth). See [2]
Personal tools