Difference between revisions of "NML:Roadtypes"
(added two roadtype_flags) |
Andythenorth (talk | contribs) (→Roadtype callbacks: document tunnels) |
||
(11 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
{{NMLNavPropVarCB}} |
{{NMLNavPropVarCB}} |
||
− | Roadtypes can only be defined in OpenTTD {{ottd|1.10}} or later. |
+ | Roadtypes can only be defined in OpenTTD {{ottd|1.10}} and {{nml|0.5}} or later. |
==Roadtype IDs== |
==Roadtype IDs== |
||
− | Roadtypes and Tramtypes share a pool of |
+ | 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) |
if (roadtype_available("LABL") || loading_stage == LOADING_STAGE_RESERVE) |
||
Line 18: | Line 18: | ||
Vehicle and roadtype availability and compatibility is influenced by multiple properties. |
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. |
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 <code style="color:green"> |
+ | * A vehicle exists, if its roadtype (road vehicle property <code style="color:green">road_type</code>) is defined. Otherwise the vehicle is disabled. |
− | * When a vehicle is introduced, it always introduces its roadtype (road vehicle property <code style="color:green"> |
+ | * When a vehicle is introduced, it always introduces its roadtype (road vehicle property <code style="color:green">road_type</code>). |
* A roadtype is introduced, if at least one of the following conditions is met: |
* 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 <code style="color:green"> |
+ | ** A vehicle is introduced, that references the roadtype (road vehicle property <code style="color:green">road_type</code>). |
** Another roadtype is introduced, that references the roadtype via the introduced roadtype list (roadtype property <code style="color:green">introduces_roadtype_list</code>). |
** Another roadtype is introduced, that references the roadtype via the introduced roadtype list (roadtype property <code style="color:green">introduces_roadtype_list</code>). |
||
** The introduction date (roadtype property <code style="color:green">introduction_date</code>) is passed and all required roadtypes (roadtype property <code style="color:green">requires_roadtype_list </code>) are available. |
** The introduction date (roadtype property <code style="color:green">introduction_date</code>) is passed and all required roadtypes (roadtype property <code style="color:green">requires_roadtype_list </code>) are available. |
||
− | Via roadtype property <code style="color:green"> |
+ | Via roadtype property <code style="color:green">powered_roadtype_list</code> multiple roadtypes can be defined, which shall be considered equivalent to a roadtype. |
− | This affects the interpretation of road vehicle property <code style="color:green"> |
+ | This affects the interpretation of road vehicle property <code style="color:green">road_type</code>. If road vehicle property <code style="color:green">road_type</code> references an undefined roadtype, then |
− | roadtype property <code style="color:green"> |
+ | roadtype property <code style="color:green">powered_roadtype_list</code> is checked for all defined roadtypes, whether the vehicle can be reassigned to some other roadtype. |
Otherwise the vehicle is disabled. |
Otherwise the vehicle is disabled. |
||
==Roadtype properties== |
==Roadtype properties== |
||
− | {| class=" |
+ | {| class="wikitable sortable" |
! property |
! property |
||
! value range |
! value range |
||
Line 71: | Line 71: | ||
| powered_roadtype_list |
| powered_roadtype_list |
||
| list of roadtype labels |
| 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 difference between "powered" and "compatible" for roadtypes |
+ | | 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 |
| roadtype_flags |
||
Line 85: | Line 85: | ||
:Hides the roadtype from players, but remains available to towns |
:Hides the roadtype from players, but remains available to towns |
||
;TOWN_BUILD |
;TOWN_BUILD |
||
− | :Enables the roadtype to be built by towns, |
+ | :Enables the roadtype to be built by towns, picked by highest speed (defaults to ROAD if no speed limits?) |
|- |
|- |
||
| construction_cost |
| construction_cost |
||
Line 142: | Line 142: | ||
==Roadtype variables== |
==Roadtype variables== |
||
− | {| class=" |
+ | {| class="wikitable sortable" |
! name |
! name |
||
! value range |
! value range |
||
Line 150: | Line 150: | ||
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW |
| 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_status |
||
Line 165: | Line 169: | ||
| random_bits |
| random_bits |
||
| |
| |
||
− | | 2 pseudo random bits |
+ | | 2 pseudo random bits, based on tile location |
|} |
|} |
||
Line 172: | Line 176: | ||
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|example sprites]] or the example roadtype grf in the NML repository, for an example on what sprites are needed in what order. |
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|example sprites]] or the example roadtype grf in the NML repository, for an example on what sprites are needed in what order. |
||
− | {| class=" |
+ | {| class="wikitable sortable" |
! callbacks |
! callbacks |
||
! number of sprites |
! number of sprites |
||
Line 191: | Line 195: | ||
| tunnels<ref name=leftout /> |
| tunnels<ref name=leftout /> |
||
| 4 |
| 4 |
||
− | | 1 sprite for each direction. Sprite is overlay for road in existing tunnel graphics. The original ground sprite is drawn, then the overlay, then possibly a road vehicle and the original tunnel head is drawn over the top. This keeps compatibility with different landscape types. Sprite order: SW, NW, NE, SE. |
+ | | {{ottd|13}} and {{nml|0.7.2}} 1 sprite for each direction. Sprite is overlay for road in existing tunnel graphics. The original ground sprite is drawn, then the overlay, then possibly a road vehicle and the original tunnel head is drawn over the top. This keeps compatibility with different landscape types. Sprite order: SW, NW, NE, SE. |
|- |
|- |
||
| catenary_front |
| catenary_front |
||
Line 220: | Line 224: | ||
| 4 |
| 4 |
||
| Overlays for drive-in road stops |
| Overlays for drive-in road stops |
||
+ | |- |
||
+ | | direction_markings |
||
+ | | 18 |
||
+ | | {{ottd|13}} 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. |
||
|} |
|} |
||
+ | |||
<references /> |
<references /> |
||
− | Note that there is no "default graphics |
+ | Note that there is no "default" graphics callback. |
===Example sprites=== |
===Example sprites=== |
||
Line 286: | Line 295: | ||
Illustration: [[File:RoadtypeTunnelExample.png]] |
Illustration: [[File:RoadtypeTunnelExample.png]] |
||
--> |
--> |
||
+ | |||
+ | ==== direction_markings ==== |
||
+ | |||
+ | [[File:Nrt_oneway.png]] |
||
===Example code=== |
===Example code=== |
||
Line 307: | Line 320: | ||
graphics { |
graphics { |
||
underlay: ground_switch_underlay; // defines the usual roads |
underlay: ground_switch_underlay; // defines the usual roads |
||
− | tunnels: tunnel_switch; // defines the roads drawn on a tunnel tile |
||
depots: depot_switch; // defines the depot sprites |
depots: depot_switch; // defines the depot sprites |
||
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges depending on climate |
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges depending on climate |
Latest revision as of 08:41, 10 September 2023
Vehicles, Stations, Canals, Bridges, Towns, Houses, Industries (Tiles), Cargos, Airports+Tiles, Objects, Railtypes, Roadtypes, Tramtypes, Terrain
- common props | vars | CBs
- train | roadveh | ship | aircr props
- common variables
- industry props | vars | CBs
- tile props | vars | CBs
- airport props | vars | CBs
- tile props | vars | CBs
Roadtypes can only be defined in OpenTTD 1.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 propertyrequires_roadtype_list
) are available.
- A vehicle is introduced, that references the roadtype (road vehicle property
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, ...) |
|
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. |
tunnels[1] | 4 | 13 and NML 0.7.2 1 sprite for each direction. Sprite is overlay for road in existing tunnel graphics. The original ground sprite is drawn, then the overlay, then possibly a road vehicle and the original tunnel head is drawn over the top. This keeps compatibility with different landscape types. Sprite order: SW, NW, NE, SE. |
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 | 13 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. |
Note that there is no "default" graphics callback.
Example sprites
gui
underlay
catenary_front
catenary_back
depots
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
roadstops
direction_markings
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.