Difference between revisions of "NML:Railtypes"
(Add note about item IDs) |
(Document town_zone var) |
||
Line 214: | Line 214: | ||
| 0 .. 5000000 |
| 0 .. 5000000 |
||
| for depots only: build date of the depot in days since 0 |
| 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.) |
||
|} |
|} |
||
− | |||
==Railtype callbacks== |
==Railtype callbacks== |
Revision as of 20:33, 14 September 2012
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
Railtypes can only be defined in OpenTTD 1.0 or later.
Railtype IDs
Railtype IDs are limited to 16 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..15 range. If other railtype GRFs are loaded, it may be that there are not enough railtype 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 (railtype_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 railtypes.
Railtype properties
property | value range | comment |
---|---|---|
label | 4-byte string | names of default rail types: "RAIL", "ELRL", "MONO", "MGLV". See the List of railtype labels in the NewGRF Specs for currently defined custom labels. |
introduction_date | date(yyyy,mm,dd) | |
name | string | Name of this railtype |
toolbar_caption | string | 1.2 Caption of the build rail toolbar. In earlier versions this is the same as the 'name' |
menu_text | string | Shown in the dropdown menu for all railtypes |
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 <rail type> engine" news message |
compatible_railtype_list | list of railtype labels | Provide a list of rail types that trains of this type can also run on. e.g. ["RAIL", "ELRL", "MONO"] |
powered_railtype_list | list of railtype labels | Provide a list of rail types that trains of this type are powered on. |
railtype_flags | bitmask(RAILTYPE_FLAG_XXX, ...) | XXX = [CATENARY | NO_LEVEL_CROSSING] Flags enable catenary and/or disable level crossings. |
curve_speed_multiplier | 0...65525 | max curve speed is defined as multiple of the base curve speed (see below) |
station_graphics | RAILTYPE_STATION_NORMAL, RAILTYPE_STATION_MONORAIL, RAILTYPE_STATION_MAGLEV | Type of station graphics to use for the default stations |
construction_cost | 0 ... 65525 |
1.1 per piece of track as multiplier to PR_BUILD_RAIL base cost. Default cost factors are 8, 12, 16 and 24 for RAIL, ELRL, MONO and MGLV. |
speed_limit | 0 ... 65525 km/h (speed units) | A speed limit of 0 means unlimited speed |
acceleration_model | ACC_MODEL_RAIL, ACC_MODEL_MONORAIL, ACC_MODEL_MAGLEV | ACC_MODEL_RAIL and ACC_MODEL_MONORAIL behave the same currently |
map_colour | 0 ... 255 | |
requires_railtype_list | list of railtype labels |
1.1 List of rail types on that need to be available to the company of the player for this rail type to be introduced at (or after) the introduction date. This limit does not apply when the rail type is introduced by the introduction of a vehicle. |
introduces_railtype_list | list of railtype labels |
1.1 List of rail types that get introduced when this rail type is introduced. For example, to make sure that when a fast rail type is introduced the slow variant exists. |
sort_order | 0 ... 255 |
1.1 number which defines the sort order among rail types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th railtype. |
maintenance_cost |
1.2 Maintenance cost factor for each piece of tracks of this railtype. Default cost factors are 8, 12, 16 and 24 for RAIL, ELRL, MONO and MGLV. | |
alternative_railtype_list | list of railtype labels |
1.2 List or rail types which this rail type will act as fallback for, if the corresponding rail type is not defined separately |
Sort order
The sort_order influences the sort order of the drop down lists with rail types. Default values are as follows:
Value | Meaning |
---|---|
07 | normal rail |
17 | electrified rail |
27 | monorail |
37 | maglev |
n7 | railtype #n |
Thus the rail 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:
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 |
Railtype variables
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 | town zone | Town zone of the tile. (Only available for level crossings and depots.) |
Railtype callbacks
For rail types a number of callbacks are used to define rail type graphics. Each should refer to a sprite set containing the relevant sprites. Refer to the example sprites or the example railtype grf in the NML repository, for an example on what sprites are needed in what order.
callbacks | number of sprites | meaning |
---|---|---|
gui | 16 | 4 rail directions, autorail, depot, tunnel and convert rail sprites for rail menu |
track_overlay[1] | 10 | 6 flat and 4 slope sprites. Track without landscape |
underlay[1] | 16 | 6 flat and 4 slope, one crossing WITH track, 5 junction pieces without track. Tracks with ballast but without landscape |
tunnels[1] | 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 train 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[1] | 6 | |
level_crossings[1] | 10 | For each direction: one track sprite and 4 sprites for road lights etc |
depots[2] | 6 | 2 sprites for each south-ish, 1 sprite for each north-ish depot. Like original depots. |
fences | 8 | x, y, vertical, horizontal, SW, SE, NE and NW slopes like original fences at sprite 1301 |
tunnel_overlay[3] | 4 | If this callback is defined, tunnels for this railtype will be drawn differently. First, a grass underlay base sprite is drawn, then the 'tunnels'-sprite. Next, train 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 railtype sprites. extra_callback_info1 contains 0 for normal tunnels, without any extra features (like tracks above). All other values are reserved for future extensions.
|
signals | 8 | 1.3 1 sprite for each direction, order is SW(-facing), NE, SE, NW, E, W, S, N. For more information, see below |
If a callback is not implemented or fails, graphics from the fallback railtype (picked via the station_graphics
property) will be used instead.
Note that there is no "default graphics"-callback.
Example sprites
gui
track_overlay
underlay
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.
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 |
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. |
fences
tunnel_overlay
If this callback is defined, tunnels for this railtype will be drawn differently.
First, a grass underlay base sprite is drawn, then the 'tunnels'-sprite. Next, train 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 railtype sprites.
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. Variable extra_callback_info2
contains information about the kind of signal to be drawn. If resolving fails or results in an empty sprite group, the matching base set sprite will be used instead.
Format of extra_callback_info2: 0xRRTTVVSS
TT: Signal type | Meaning |
---|---|
0 | Normal block signal |
1 | Entry pre-signal |
2 | Exit pre-signal |
3 | Combo pre-signal |
4 | Two-way path signal |
5 | One-way path signal |
all other values | Reserved |
VV: Signal variant | Meaning |
---|---|
0 | Light (electric) signal |
1 | Semaphore |
all other values | Reserved |
SS: Signal state | Meaning |
---|---|
0 | Red signal |
1 | Green signal |
all other values | Reserved |
The most significant byte (RR) is reserved and must be and-masked out.
extra_callback_info1
can be used to distinguish between map and GUI sprites:
Lowest byte of variable 10 | 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 |
The other bytes of extra_callback_info1
are reserved, and must be masked.
Example code
A typical implementation for railtypes can look like:
item(FEAT_RAILTYPES, elrail, 0x01) { property { label: "SHIN"; name: string(STR_EL_RAIL); menu_text: string(STR_EL_RAIL); build_window_caption: string(STR_BUILD_CAPTION); autoreplace_text: string(STR_AUTOREPLACE); new_engine_text: string(STR_NEW_ENGINE); compatile_railtype_list: ["SHIN","RAIL","ELRL"]; // Tracks of rail and electrified rail are compatible powered_railtype_list: ["ELRL","SHIN"]; // But we got only power when we have electricity railtype_flags: bitmask(RAILTYPE_FLAG_NO_LEVEL_CROSSING); // High speed tracks should not have level crossings curve_speed_multiplier: 1; station_graphics: RAILTYPE_STATION_MAGLEV; // We want the most modern stations construction_cost: 32; // should be pretty steep speed_limit: 500 km/h; acceleration_model: ACC_MODEL_RAIL; // This is still rail, 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. } }
The switches and graphics blocks are defined in the usual way as described in sections switches, random switches and graphics block sections.