NML:Roadtypes

From GRFSpecs
Revision as of 08:38, 10 September 2023 by Andythenorth (talk | contribs) (→‎Roadtype callbacks: nfo docs had better explanation of one way overlays, copy that)
Jump to navigationJump to search
Props, Vars and CBs

Roadtypes can only be defined in OpenTTD Supported by OpenTTD 1.101.10 and NML 0.5 or later.


Roadtype IDs

Roadtypes and Tramtypes share a pool of 63 IDs. Either feature can use as many IDs as needed (i.e. it is not limited to 32 per type), but both features combined are limited to 63 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..62 range. If other roadtype/tramtype GRFs are loaded, it may be that there are not enough slots available. To prevent your entire NewGRF from being deactivated with the 'Attempt to use invalid ID'-error, you can use the following code:

if (roadtype_available("LABL") || loading_stage == LOADING_STAGE_RESERVE)
    ... item definition ...
} else if (loading_stage == LOADING_STAGE_ACTIVATE) {
    ... warning / error ...
}

The warning / error is optional, but can be used to inform the user about the missing roadtypes.

Vehicle and Roadtype availability

Vehicle and roadtype availability and compatibility is influenced by multiple properties. Generally, the vehicle defines which roadtype it is, and the roadtypes define the compatibility between each other.

  • A vehicle exists, if its roadtype (road vehicle property road_type) is defined. Otherwise the vehicle is disabled.
  • When a vehicle is introduced, it always introduces its roadtype (road vehicle property road_type).
  • A roadtype is introduced, if at least one of the following conditions is met:
    • A vehicle is introduced, that references the roadtype (road vehicle property road_type).
    • Another roadtype is introduced, that references the roadtype via the introduced roadtype list (roadtype property introduces_roadtype_list).
    • The introduction date (roadtype property introduction_date) is passed and all required roadtypes (roadtype property requires_roadtype_list ) are available.

Via roadtype property powered_roadtype_list multiple roadtypes can be defined, which shall be considered equivalent to a roadtype. This affects the interpretation of road vehicle property road_type. If road vehicle property road_type references an undefined roadtype, then roadtype property powered_roadtype_list is checked for all defined roadtypes, whether the vehicle can be reassigned to some other roadtype. Otherwise the vehicle is disabled.

Roadtype properties

property value range comment
label 4-byte string names of default road types: "ROAD" and "ELRD". See the List of roadtype labels in the NewGRF Specs for currently defined custom labels.
introduction_date date(yyyy,mm,dd) Valid range for yyyy is 0 ... 5000000.
name string Name of this roadtype
toolbar_caption string Caption of the build road toolbar
menu_text string Shown in the dropdown menu for all roadtypes
build_window_caption string Caption of the build vehicle window
autoreplace_text string String for the autoreplace window
new_engine_text string String for the "We have invented a new <road type> engine" news message
powered_roadtype_list list of roadtype labels Provide a list of road types that road vehicles of this type are powered on, e.g. ["ROAD", "ELRD"]. Note that there is no "compatible_roadtype_list" since there is no difference between "powered" and "compatible" for roadtypes
roadtype_flags bitmask(ROADTYPE_FLAG_XXX, ...)
CATENARY
Enable catenary
NO_LEVEL_CROSSING
Disable level crossings
NO_HOUSES
Disallows house construction
HIDDEN
Hides the roadtype from players, but remains available to towns
TOWN_BUILD
Enables the roadtype to be built by towns, picked by highest speed (defaults to ROAD if no speed limits?)
construction_cost 0 ... 65525 Per piece of road as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8 and 16 for ROAD and ELRD, respectively.
speed_limit 0 ... 65525 km/h (speed units) A speed limit of 0 means unlimited speed
map_colour 0 ... 255 Entry in the colour palette.
requires_roadtype_list list of roadtype labels List of road types that need to be available to the company of the player for this road type to be introduced at (or after) the introduction date. This limit does not apply when the road type is introduced by the introduction of a vehicle.
introduces_roadtype_list list of roadtype labels List of road types that get introduced when this road type is introduced. For example, to make sure that when a fast road type is introduced the slow variant exists.
sort_order 0 ... 255 Number which defines the sort order among road types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th roadtype.
maintenance_cost 0 ... 255 Maintenance cost factor for each piece of road of this roadtype. Default cost factors are 16 and 24 for ROAD and ELRD, respectively.
alternative_roadtype_list list of roadtype labels List of road types which this road type will act as fallback for, if the corresponding road type is not defined separately

Sort order

The sort_order influences the sort order of the drop down lists with road types. Default values are as follows:

Value Meaning
07 normal road
17 electrified road
n7 roadtype #n

Thus the road type that (internally) gets index 8 will get a default value of 87. These defaults are to keep the ordering when this property is not supported as they were.

Roadtype variables

name value range comment
terrain_type TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
enhanced_tunnels 0 Reserved for future use, always returns 0 in OpenTTD. Should custom tunnel entrances be implemented, other values than 0 might be returned
level_crossing_status LEVEL_CROSSING_CLOSED, LEVEL_CROSSING_OPEN
build_date 0 .. 5000000 for depots only: build date of the depot in days since 0
town_zone town zone Town zone of the tile
random_bits 2 pseudo random bits, based on tile location

Roadtype callbacks

For road types a number of callbacks are used to define road type graphics. Each should refer to a sprite set containing the relevant sprites. Refer to the example sprites or the example roadtype grf in the NML repository, for an example on what sprites are needed in what order.

callbacks number of sprites meaning
gui 12 6 gui icons, 6 cursors
track_overlay[1] 19 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are optional for roadtypes.
underlay[1] 19 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are required.
catenary_front 29 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
catenary_back 29 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
bridge_surfaces[1] 6 2 bridge middle, 4 bridge ramps
depots 6 If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn.

If present, the depot sprites are expected to include track overlay graphics.

roadstops 4 Overlays for drive-in road stops
direction_markings 18 Supported by OpenTTD 1313 and NML 0.7.4 Overlays for one-way roads: repeat (arrow facing SW, arrow NE, impassable NE-SW, arrow NW, arrow SE, impassable NW-SE) for flat, N corner raised, S corner raised.


  1. 1.0 1.1 1.2 Either all or none of these sprites should be provided.

Note that there is no "default" graphics callback.

Example sprites

gui

Nrt gui.png

underlay

Nrt underlay.png

catenary_front

Nrt catenary front.png

catenary_back

Nrt catenary back.png

depots

Nrt depot.png

Sprite Number Usage
0    NE wall for SE-entry depot.
1    Depot building for SE-entry depot.
2    NW wall for SW-entry depot.
3    Depot building for SW-entry depot.
4    Depot building for NE-entry depot.
5    Depot building for NW-entry depot.

bridge_surfaces

Nrt bridge.png

roadstops

Nrt drivein.png

direction_markings

Nrt oneway.png

Example code

A typical implementation for roadtypes can look like:

 item(FEAT_ROADTYPES, highway, 0x01) {
     property {
         label:                      "HWY_";
         name:                       string(STR_HWY);
         menu_text:                  string(STR_HWY);
         build_window_caption:       string(STR_BUILD_CAPTION);
         autoreplace_text:           string(STR_AUTOREPLACE);
         new_engine_text:            string(STR_NEW_ENGINE);
         powered_roadtype_list:      ["HWY_","ROAD"];                          // Highways are compatible with other roads
         roadtype_flags:             bitmask(ROADTYPE_FLAG_NO_LEVEL_CROSSING, ROADTYPE_FLAG_NO_HOUSES); // Highways should not have level crossings or houses
         construction_cost:          32;                                       // Highways are expensive
         speed_limit:                100 km/h;
     }
     graphics {
         underlay:        ground_switch_underlay;    // defines the usual roads
         depots:          depot_switch;              // defines the depot sprites
         bridge_surfaces: bridge_terrain_switch;     // defines the overlay drawn over bridges depending on climate
         roadstops:       roadstops_switch;          // defines the look of roadstop pavement
     }
 }

The switches and graphics blocks are defined in the usual way as described in sections switches, random switches and graphics block sections.