Andrew350: initial conversion to tramtypes (from roadtypes)

2019-12-22T11:22:14Z

initial conversion to tramtypes (from roadtypes)

New page

{{NMLNavPropVarCB}}

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

==Tramtype IDs==
Tramtypes and Roadtypes 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 tramtype/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 (tramtype_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 tramtypes.

== Vehicle and Tramtype availability ==

Vehicle and tramtype availability and compatibility is influenced by multiple properties.
Generally, the vehicle defines which tramtype it is, and the tramtypes define the compatibility between each other.
* Remember that the road vehicle flag 'ROADVEH_FLAG_TRAM' must be set in order for a road vehicle to be considered a tram.
* A vehicle exists, if its tramtype (tram 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 tramtype (tram vehicle property <code style="color:green">track_type</code>).
* A tramtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the tramtype (tram vehicle property <code style="color:green">track_type</code>).
** Another tramtype is introduced, that references the tramtype via the introduced tramtype list (tramtype property <code style="color:green">introduces_tramtype_list</code>).
** The introduction date (tramtype property <code style="color:green">introduction_date</code>) is passed and all required tramtypes (tramtype property <code style="color:green">requires_tramtype_list </code>) are available.

Via tramtype property <code style="color:green">powered_tramtype_list</code> multiple tramtypes can be defined, which shall be considered equivalent to a tramtype.
This affects the interpretation of tram vehicle property <code style="color:green">track_type</code>. If tram vehicle property <code style="color:green">track_type</code> references an undefined tramtype, then
tramtype property <code style="color:green">powered_tramtype_list</code> is checked for all defined tramtypes, whether the vehicle can be reassigned to some other tramtype.
Otherwise the vehicle is disabled.

==Tramtype properties==

{| class="t"
! property
! value range
! comment
|-
| label
| 4-byte string
| names of default tram types: "RAIL" and "ELRL". See the [[TramtypeLabels|List of tramtype 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 tramtype
|-
| toolbar_caption
| string
| Caption of the build tram toolbar. In earlier versions this is the same as the 'name'
|-
| menu_text
| string
| Shown in the dropdown menu for all tramtypes
|-
| 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 <tram type> engine" news message
|-
| powered_tramtype_list
| list of tramtype labels
| Provide a list of tram types that tram vehicles of this type are powered on, e.g. ["RAIL", "ELRL"]. Note that there is no difference between "powered" and "compatible" for tramtypes
|-
| tramtype_flags
| bitmask(TRAMTYPE_FLAG_XXX, ...)
|
;CATENARY
:Enable catenary
;NO_LEVEL_CROSSING
:Disable level crossings
;NO_HOUSES
:Disallows house construction
|-
| construction_cost
| 0 ... 65525
| Per piece of track as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8 and 16 for RAIL and ELRL, 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_tramtype_list
| list of tramtype labels
| List of tram types that need to be available to the company of the player for this tram type to be introduced at (or after) the introduction date. This limit does not apply when the tram type is introduced by the introduction of a vehicle.
|-
| introduces_tramtype_list
| list of tramtype labels
| List of tram types that get introduced when this tram type is introduced. For example, to make sure that when a fast tram type is introduced the slow variant exists.
|-
| sort_order
| 0 ... 255
| Number which defines the sort order among tram types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th tramtype.
|-
| maintenance_cost
| 0 ... 255
| Maintenance cost factor for each piece of tram of this tramtype. Default cost factors are 16 and 24 for RAIL and ELRL, respectively.
|-
| alternative_tramtype_list
| list of tramtype labels
| List of tram types which this tram type will act as fallback for, if the corresponding tram type is not defined separately
|}

===Sort order===

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

{| class="t"
! Value
! Meaning
|-
| 07
| normal tram
|-
| 17
| electrified tram
|-
| n7
| tramtype #n
|}

Thus the tram 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.

==Tramtype variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| 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
|-
| random_bits
|
| 2 pseudo random bits
|}

==Tramtype callbacks==

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

{| class="t"
! callbacks
! number of sprites
! meaning
|-
| gui
| 12
| 6 gui icons, 6 cursors
|-
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
| 19
| 11 track combinations, 4 slopes, and 4 dead ends. These sprites are required
|-
| underlay<ref name=leftout />
| 19
| 11 track combinations, 4 slopes, and 4 dead ends. These sprites are required
|-
| tunnels<ref name=leftout />
| 4
| 1 sprite for each direction. Sprite is overlay for tram in existing tunnel graphics. The original ground sprite is drawn, then the overlay, then possibly a tram 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 track combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
| catenary_back
| 29
| 11 track combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
| bridge_surfaces<ref name=leftout />
| 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.

|}

<references />
Note that there is no "default graphics" callback.

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

[[File:Nrt_gui.png]]

==== underlay ====

[[File:Nrt_underlay.png]]

==== overlay ====

[[File:Nrt_overlay.png]]

==== catenary_front ====

[[File:Nrt_catenary_front.png]]

==== catenary_back ====

[[File:Nrt_catenary_back.png]]

==== depots ====

[[File:Nrt_depot.png]]

{| 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.
|}

==== bridge_surfaces ====

[[File:Nrt_bridge.png]]


===Example code===

A typical implementation for tramtypes can look like:

<pre style="color:blue">
item(FEAT_TRAMTYPES, dctram, 0x01) {
property {
label: "DCTM";
name: string(STR_DC_TRAM);
menu_text: string(STR_DC_TRAM);
build_window_caption: string(STR_BUILD_CAPTION);
autoreplace_text: string(STR_AUTOREPLACE);
new_engine_text: string(STR_NEW_ENGINE);
powered_tramtype_list: ["DCTM","ELRL"]; // These trams are compatible with other electric trams
tramtype_flags: bitmask(TRAMTYPE_FLAG_CATENARY); // These tramways require catenary
construction_cost: 24; // Electric tramways are pricey
speed_limit: 50 km/h;
}
graphics {
underlay: ground_switch_underlay; // defines the tramtrack underlay
overlay: track_overlay_switch; // defines the tramtrack overlay
tunnels: tunnel_switch; // defines the track drawn on a tunnel tile
depots: depot_switch; // defines the depot sprites
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges depending on climate
}
}
</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:Tramtypes - Revision history

Andrew350: initial conversion to tramtypes (from roadtypes)