Andrew350: remove some unnecessary things

2019-12-22T11:03:09Z

remove some unnecessary things

← Older revision		Revision as of 11:03, 22 December 2019
Line 51:		Line 51:
	\| toolbar_caption		\| toolbar_caption
	\| string		\| string
	\| Caption of the build road toolbar~~. In earlier versions this is the same as the 'name'~~		\| Caption of the build road toolbar
	\|-		\|-
	\| menu_text		\| menu_text
Line 157:		Line 157:
	\| town_zone		\| town_zone
	\| [[NML:List of town zones\|town zone]]		\| [[NML:List of town zones\|town zone]]
	\| Town zone of the tile~~. (Only available for level crossings and depots.)~~		\| Town zone of the tile
	\|-		\|-
	\| random_bits		\| random_bits

Andrew350: fine-tuned the specs for roadtypes, cross referenced from frosch's draft specs

2019-12-22T09:35:12Z

fine-tuned the specs for roadtypes, cross referenced from frosch's draft specs

Show changes

Andrew350: Intitial conversion from railtype spec

2019-12-22T07:54:33Z

Intitial conversion from railtype spec

New page

{{NMLNavPropVarCB}}

Roadtypes can only be defined in OpenTTD {{ottd|1.10}} or later.

==Roadtype IDs==
Roadtypes and Tramtypes share a pool of 64 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 64 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..63 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 <code style="color:green">track_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">track_type</code>).
* 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">track_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>).
** 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">compatible_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">track_type</code>. If road vehicle property <code style="color:green">track_type</code> references an undefined roadtype, then
roadtype property <code style="color:green">compatible_roadtype_list</code> is checked for all defined roadtypes, whether the vehicle can be reassigned to some other roadtype.
Otherwise the vehicle is disabled.

==Roadtype properties==

{| class="t"
! property
! value range
! comment
|-
| label
| 4-byte string
| names of default road types: "ROAD", "ELRL", "MONO", "MGLV". See the [[RoadtypeLabels|List of roadtype labels]] in the NewGRF Specs for currently defined custom labels.
|-
| introduction_date
| date(yyyy,mm,dd)
|
{{ottd|1.1|r21842}} Valid range for yyyy is 0 ... 5000000.
|-
| name
| string
| Name of this roadtype
|-
| toolbar_caption
| string
| {{ottdp|1.2|no|ottdrev=23129}} Caption of the build road toolbar. In earlier versions this is the same as the 'name'
|-
| 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
|-
| compatible_roadtype_list
| list of roadtype labels
| Provide a list of road types that road vehicles of this type can also run on. e.g. ["ROAD", "ELRL", "MONO"]
|-
| powered_roadtype_list
| list of roadtype labels
| Provide a list of road types that road vehicles of this type are powered on.
|-
| roadtype_flags
| bitmask(ROADTYPE_FLAG_XXX, ...)
| XXX = [CATENARY <nowiki>|</nowiki> NO_LEVEL_CROSSING] Flags enable catenary and/or disable level crossings.
|-
| curve_speed_multiplier
| 0...255
| max curve speed is defined as multiple of the base curve speed (see below)
|-
| station_graphics
| ROADTYPE_STATION_NORMAL, ROADTYPE_STATION_MONOROAD, ROADTYPE_STATION_MAGLEV
| Type of station graphics to use for the default stations
|-
| construction_cost
| 0 ... 65525
|
{{ottd|1.1|r19307}} per piece of track as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8, 12, 16 and 24 for ROAD, ELRL, MONO and MGLV.
|-
| speed_limit
| 0 ... 65525 km/h (speed units)
| A speed limit of 0 means unlimited speed
|-
| acceleration_model
| ACC_MODEL_ROAD, ACC_MODEL_MONOROAD, ACC_MODEL_MAGLEV
| ACC_MODEL_ROAD and ACC_MODEL_MONOROAD behave the same currently
|-
| map_colour
| 0 ... 255
|
{{ottd|1.1|r19307}} entry in the colour palette.
|-
| requires_roadtype_list
| list of roadtype labels
|
{{ottd|1.1|r21842}} List of road types on 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
|
{{ottd|1.1|r21841}} 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
|
{{ottd|1.1|r21866}} 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
|
|
{{ottd|1.2|r23415}} Maintenance cost factor for each piece of tracks of this roadtype. Default cost factors are 8, 12, 16 and 24 for ROAD, ELRL, MONO and MGLV.
|-
| alternative_roadtype_list
| list of roadtype labels
|
{{ottd|1.2|r23758}} 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:

{| class="t"
! Value
! Meaning
|-
| 07
| normal road
|-
| 17
| electrified road
|-
| 27
| monoroad
|-
| 37
| maglev
|-
| 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.

===Base speeds for curves===

The base speeds relevant for the curve_speed_multiplier are:

{| class="t"
! curve length
! base speed [km/h]
|-
| 0 (90 degree turn)
| 30
|-
| 1
| 44
|-
| 2
| 55
|-
| 3
| 66
|-
| 4
| 75
|-
| 5
| 84
|-
| 6
| 91
|-
| 7
| 98
|-
| 8
| 103
|-
| 9
| 108
|-
| 10
| 111
|-
| 11
| 114
|-
| 12+
| 115
|}

==Roadtype variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| enhanced_tunnels
| 0
| should custom tunnel entrances be modified 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
| [[NML:List of town zones|town zone]]
| Town zone of the tile. (Only available for level crossings and depots.)
|}

==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|example sprites]] or the example roadtype grf in the NML repository, for an example on what sprites are needed in what order.

{| class="t"
! callbacks
! number of sprites
! meaning
|-
| gui
| 16
| 4 road directions, autoroad, depot, tunnel and convert road sprites for road menu.
|-
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
| 10
| 6 flat and 4 slope sprites. Track without landscape. Used in junctions, and also with path signals, if the "Show reserved tracks" option is enabled in the game settings.
|-
| underlay<ref name=leftout />
| 16
| 6 flat and 4 slope, one crossing WITH track, 5 junction pieces without track. Tracks with ballast but without landscape.
|-
| tunnels<ref name=leftout />
| 4
| 1 sprite for each direction. Sprite is overlay for track 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_wire
| 28
|
|-
| catenary_pylons
| 8
|
|-
| bridge_surfaces<ref name=leftout />
| 6
|
|-
| level_crossings<ref name=leftout />
| 10
| For each direction: one track sprite and 4 sprites for road lights etc
|-
| depots<ref name=depotr22854>{{ottd|1.2|r22854}} In OpenTTD prior to r22854, depot sprites would not be used if the above 'all or none' sprites were not supplied.</ref>
| 6
| 2 sprites for each south-ish, 1 sprite for each north-ish depot. Like original depots.
|-
| fences
| 8 / 16
| x, y, vertical, horizontal, SW, SE, NE and NW slopes like original fences at sprite 1301. {{ottdp|1.6|no|ottdrev=r27343}} Since OpenTTD r27343 there is also a 16 sprites version, see below.
|-
| tunnel_overlay<ref name=tunnel_overlay>Above 'all or none' sprites must be supplied, if these sprites are to be used.</ref>
| 4
| If this callback is defined, tunnels for this roadtype will be drawn differently. First, a grass underlay base sprite is drawn, then the 'tunnels'-sprite. Next, road vehicle sprites if applicable and then a grass overlay and finally the sprite from this type (tunnel_overlay). The grass sprites are defined in the base set and do not contain any parts of the tracks or portal, so these have to be fully provided by the roadtype sprites.
* <code style:darkgreen>getbits(extra_callback_info1, 0, 8)</code>: 0 for normal tunnels, without any extra features (like tracks above). All other values are reserved for future extensions.
|-
| signals
| 8
| {{ottd|1.3|r24367}} 1 sprite for each direction, order is SW(-facing), NE, NW, SE, E, W, S, N. For more information, see [[#signals|below]]
|}

<references />
If a callback is not implemented or fails, graphics from the fallback roadtype (picked via the <code style="color:darkgreen">station_graphics</code> property) will be used instead.<br />
Note that there is no "default graphics"-callback.

===Example sprites===
==== gui ====

[[File:roadtype_gui.png]]

==== track_overlay ====

[[File:roadtype_overlay.png]]

==== underlay ====

[[File:roadtype_underlay.png]]

==== level_crossings ====

You can define a special track piece which crosses the road and for each of two directions and each of the corners of the tile a separate sprite for a light, sign, or whatever should go there.

{| class="wikitable"
|-
!Sprite number for X
!Sprite number for Y
!Useage
|-
|0
|    1
|    Rail overlay
|-
|2
|    3
|    North light
|-
|4
|    5
|    East light
|-
|6
|    7
|    West light
|-
|8
|    9
|    South light
|}

[[File:roadtype_levelcrossing.png]]

==== depots ====

{| class="wikitable
|-
!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.
|}

==== fences ====

[[File:roadtype_fences.png]]

{{ottdp|1.6|no|ottdrev=r27343}} Since OpenTTD r27343 there is also a 16 sprites version, this allows to use different sprites resp. offsets for the fences on either track side.

{| |-
! Sprite number !! Tile slope !! Track bit !! Fence position !! Version
|-
| 0 || flat || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 1 || flat || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 2 || flat || left || E || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 3 || flat || upper || S || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 4 || SW || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 5 || SE || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 6 || NE || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 7 || NW || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 8 || flat || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 9 || flat || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 10 || flat || left || W || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 11 || flat || upper || N || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 12 || SW || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 13 || SE || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 14 || NE || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 15 || NW || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
|}

==== tunnel_overlay ====

If this callback is defined, tunnels for this roadtype will be drawn differently.

First, a grass underlay base sprite is drawn, then the 'tunnels'-sprite. Next, road vehicle sprites if applicable and then a grass overlay and finally the sprite from this callback. The grass sprites are defined in the base set and do not contain any parts of the tracks or portal, so these have to be fully provided by the roadtype sprites.

Illustration: [[File:RoadtypeTunnelExample.png]]

==== signals ====

This callback can be used to supply custom signal graphics.

The resulting sprite set must consist of 8 sprites, corresponding to the following signal directions: SW-facing, NE-facing, NW-facing, SE-facing, E-facing, W-facing, S-facing, N-facing. If resolving fails or results in an empty sprite group, the matching base set sprite will be used instead.

Variable <code style:darkgreen>extra_callback_info2</code> contains the state, variant and type of the signal. Use the builtin function <code style:darkgreen>getbits()</code> in the following fashion to access the information:
<ul><li>
Signal state: <code style:darkgreen>getbits(extra_callback_info2, 0, 8)</code>:
{| |-
! Result !! Meaning
|-
| 00 || Red signal
|-
| 01 || Green signal
|-
| all other values || Reserved
|}
</li><li>
Signal variant: <code style:darkgreen>getbits(extra_callback_info2, 8, 8)</code>:
{| |-
! Result !! Meaning
|-
| 00 || Light (electric) signal
|-
| 01 || Semaphore
|-
| all other values || Reserved
|}
</li><li>
Signal type: <code style:darkgreen>getbits(extra_callback_info2, 16, 8)</code>:
{| |-
! Result !! Meaning
|-
| 00 || Normal block signal
|-
| 01 || Entry pre-signal
|-
| 02 || Exit pre-signal
|-
| 03 || Combo pre-signal
|-
| 04 || Two-way path signal
|-
| 05 || One-way path signal
|-
| all other values || Reserved
|}
</li></ul>
Variable <code style:darkgreen>extra_callback_info1</code> contains the drawing context.
<ul><li>
<code style:darkgreen>getbits(extra_callback_info1, 0, 8)</code>:
{| |-
! Result !! Meaning
|-
| 0 || Signal is drawn in a viewport, i.e. on the map.
|-
| 0x10 || Signal is drawn in the signal GUI. The returned sprite set must still have 8 sprites, but OpenTTD will only use the 7th sprite, so all other sprites can be empty.
|-
| all other values || Reserved
|}
</li></ul>

===Example code===

A typical implementation for roadtypes can look like:

<pre style="color:blue">
item(FEAT_ROADTYPES, elroad, 0x01) {
property {
label: "SHIN";
name: string(STR_EL_ROAD);
menu_text: string(STR_EL_ROAD);
build_window_caption: string(STR_BUILD_CAPTION);
autoreplace_text: string(STR_AUTOREPLACE);
new_engine_text: string(STR_NEW_ENGINE);
compatile_roadtype_list: ["SHIN","ROAD","ELRL"]; // Tracks of road and electrified road are compatible
powered_roadtype_list: ["ELRL","SHIN"]; // But we got only power when we have electricity
roadtype_flags: bitmask(ROADTYPE_FLAG_NO_LEVEL_CROSSING); // High speed tracks should not have level crossings
curve_speed_multiplier: 1;
station_graphics: ROADTYPE_STATION_MAGLEV; // We want the most modern stations
construction_cost: 32; // should be pretty steep
speed_limit: 500 km/h;
acceleration_model: ACC_MODEL_ROAD; // This is still road, though
}
graphics {
track_overlay: ground_switch_overlay; // defines the sprites drawn as overlay for junctions and highlight
underlay: ground_switch_underlay; // defines the usual tracks and the underlay for junctions
level_crossings: level_crossing_switch; // defines level crossings including traffic lights and blocking bars
tunnels: tunnel_switch; // defines the tracks drawn on a funnel tile
depots: depot_switch_electric; // defines the depot sprites
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges
fences: fences_set; // defines the look of fences
// we don't define catenery wire and pylons, thus we use the default which comes with the base graphics.
}
}
</pre>

The switches and graphics blocks are defined in the usual way as described in sections [[NML:Switch|switches]], [[NML:Random switch|random switches]] and [[NML:Graphics|graphics block]] sections.

User:Andrew350/NML:Roadtypes - Revision history

Andrew350: remove some unnecessary things

Andrew350: fine-tuned the specs for roadtypes, cross referenced from frosch's draft specs

Andrew350: Intitial conversion from railtype spec