VariationalAction2/Stations

From GRFSpecs
Jump to navigationJump to search

Introduction

Variables

Variable Version Size Description
40 D Platform info and relative position
41 D Platform info and relative position for individually built sections
42 D Terrain and track type
43 * D Player info, see vehicle variable 43
44 B Path-based signalling info
45 W Rail continuation info
46,47 D Platform info, counted from the middle
48 D Bitmask of accepted cargos
49 D Platform info and relative position of same-direction section
4A B Current animation frame
60 D Amount of cargo waiting
61 D Time since the cargo was last picked up
62 D Rating of the cargo
63 D Time spent en-route
64 W Information about the last vehicle picking this cargo up
65 B Amount of cargo acceptance
66 D Animation frame of nearby tile
67 D Land info of nearby tiles
68 D Station info of nearby tiles
69 D Information about cargo accepted in the past
80 B Number and length of train platforms
F0 B Bit mask of facilities attached to station (not appropriate for irregular stations)
FA W Date when station was built in days since 1920

* Available in the purchase list as well (since 2.5 beta 2).

For other 80+x variables confer the station structure. Note that you have to subtract 0x10 from the offsets there, or else the facility bit mask and construction date would not be accessible; instead you lose access to variables 00..0F which are meaningless anyway.

WARNING: Please do not use variables 8C..EB directly. The meaning of these variables changes if the newcargos switch is on. Use the variables 60..64 instead (see below). Those always work correctly.

Description

Platform info (40, 41, 46, 47, 49)

Variables 40, 41, 46, 47 and 49 all return information about the current tile, which platform it is on and how far along the platform. The difference is in the section of the station that they consider.

Variables Regular station Irregular station
40, 46 Whole station Counting entire length and all adjacent platforms
41, 47 Individually built sections
49 Whole station Counting length and platforms that have the same direction

The term "counting" here refers to starting at the tile in question, and counting tiles in all four directions. The two directions aligned with the station direction will be the length of the station, and the other two directions give the number of platforms. For variables 40 and 46, this counting stops at the edge of the station, i.e. the first non-station tile. For variable 49, it stops either at the edge, or at a station tile that is in the wrong direction.  The resulting information is probably not really useful in the case of irregular stations, with the exception of edge detection. To correctly detect edges, you have the choice of either the station->non-station transition (vars. 40, 46), or additional an opposite-direction transition (var. 49).

Variable 41 is largely unaffected by irregular stations, because it only refers to individually built sections. However, when these individual sections are built over existing tiles, the var. 41 information of surrounding tiles changes as well, due to an internal limitation in how it is stored.

For variables 40, 41 and 49, the position is counted from the northern most edge of the station, and returned in the form xTNLcCpP, where:

Variable Meaning
x undefined, use bit mask to mask it out
T Tile type: the current tile type; only valid for callback 14
N Total number of platforms
L Total platform length
c Platform number current being drawn, counted from the end (starting at zero)
C Platform number currently being drawn (starting from zero)
p Position along this platform counted from the end, zero at the end
P Position along this platform, zero at the beginning

Here, the "beginning" of a station is its northern-most (up on the screen) tile, and the "end" is the southern-most (down on the screen) tile. Each variable consists of 4 bits.

For variables 46 and 47, the position is counted from the middle, i.e. the center tile has C=0 and P=0. For even lengths and numbers of platforms, the middle tile is at position L/2 resp. N/2, e.g. for length 6, it is tile 3, which is the fourth tile. The return format is xTNLxxCP, where T, N and L are as above, and C and P are the positions counted from the middle.

Since C and P can have negative numbers, here's how this is encoded:

Hex Binary Decimal
0 0000 0
1 0001 1
7 0111 7
8 1000 -8
9 1001 -7
E 1110 -2
F 1111 -1

The counting goes like this, preferring an extra negative number for an even count (because there are 8 negative numbers available but only 7 positive ones):

Count Numbers
1
          0
2
      -1  0
3
      -1  0  1
4
   -2 -1  0  1
5
   -2 -1  0  1  2
6
-3 -2 -1  0  1  2

(etc.)

Terrain and track type (42)

Variable 42 is of the format xxxxttTT, where TT is the terrain type and tt is the railway track type.

They can have the following values:

TT Meaning
0 normal (grass)
1 desert
2 rainforest
4 on or above snowline


tt Meaning
0 railroad, regular
1 railroad, electrified
2 monorail
3 maglev

Path-based signalling info (44)

This returns the following value in bits 0-2: (bit 2 only available from alpha 47 and up)

State Value (binary) Value (decimal)
Reserved 111 7
Not reserved 100 4
No PBS 010 2

At the moment, PBS on/off refers to the switch setting, in a future alpha version it will actually refer to whether the switch is on and the current block actually uses PBS.

The bits are defined this way to allow easy fallback to non-PBS cases. If you need graphics to show the "unreserved" state in non-PBS cases, use bit 0, but if you need the "reserved" state in non-PBS cases, use bit 1. To explicitly check whether PBS is active or not, use bit 2.

All other bits are reserved and must be masked out.

Rail continuation info (45)

This variable returns 16 bits of info whether the rail tracks continue in the eight tiles adjacent to the station tile.

Bit Value Set if rail continues in direction of...
0 01 +Length
1 02 -Length
2 04 +Platforms
3 08 -Platforms
4 10 +Length, +Platforms
5 20 -Length, +Platforms
6 40 +Length, -Platforms
7 80 -Length, -Platforms

The following picture illustrates which bits represent which tile for the two possible station orientations:

Station var45.png

Bits 0 to 3 are set if there is track on the given tile, and it has a connection to the station tile. For bits 2, 3, the station of course has itself no connection to those tiles, but this doesn't matter for this variable. Bits 4 to 7 check connections to the neighbouring platform tile, i.e. bits 4 and 5 resp. 6 and 7 indicate a connection from that tile to tile 2 resp. 3. (This has changed again with 2.5 beta 4 r325.)

Bits 8..15 repeat the above, but are set if there are any train tracks on the tile and disregard whether the track is connected to the station or not entirely.

Bitmask of accepted cargos (48)

(This variable is available from TTDPatch 2.0.1 alpha 55 vcs 3 only)

Returns a doubleword where the nth bit is set if and only if the station accepts the cargo whose climate-dependent ID is n. If newcargos is off, bits 12..31 are guaranteed to be zero. If you need to check acceptance for a climate-independent ID, you can use variable 65 instead.

NOTE:Variables 60..64 are available from TTDPatch 2.0.1 alpha 55 vcs 3 only!

Amount of cargo waiting (60)

The parameter is a cargo number (see note below). Currently, the returned value is between 0 and 32767, but this may later change to support the range -32768..32767.

Time since the cargo was last picked up (61)

The parameter is a cargo number (see note below). The unit is 185 ticks (approx. 2.5 TTD days). If the given type has never been seen on the station, the returned value is zero, otherwise, the return value isn't larger than 255.

Rating of the cargo (62)

The parameter is a cargo number (see note below). The returned value is between 0 and 255 (255 means 100% rating), or FFFFFFFFh if the cargo is unrated.

Time spent en-route (63)

The parameter is a cargo number (see note below). Returns the time elapsed since the cargo appeared on a station. If the cargo has never been seen on the station, the returned value is 0, otherwise it's between 0 and 255. The unit is 185 ticks (approx. 2.5 TTD days).

Information about the last vehicle picking this cargo up (64)

The parameter is a cargo number (see note below). Bits 0..7 contain the speed of the last vehicle, while bits 8..15 contain the age of the last vehicle in years. If no vehicle has attempted to pick up this cargo yet, the result is FF00h.

Amount of cargo acceptance (65)

(From TTDPatch 2.5 beta 2)

The parameter is a cargo number (see note below). The return value contains the acceptance of the given cargo type in 1/8 units. The station accepts the cargo if its acceptance is at least 8/8 units. Without newcargos, the returned value is between 0 and 15 (inclusive). With newcargos enabled, the return value is either 8 or 0.

NOTE: In GRF version 6, parametrized variables 60..65 accept a climate-dependent cargo number. In GRF version 7 and later, these variables accept a climate-independent cargo ID. If your GRF has a cargo translation table, then this ID is the index in that table; otherwise, it's the cargo bit.

Animation frame of nearby tile (66)

(From TTDPatch 2.5 beta 5)

The parameter defines the offset relative to the current tile. Both nibbles are considered signed (that is, 8h=8, 9h=-7, ...., Fh=-1, 0h=0, 1h=1, ..., 7h=7). The high nibble contains the amount to move sideways (between platforms), the low one is the amount to move along the platform. Negative offsets move northwards, positive ones southwards. If the selected tile is a rail station tile that belongs to the current station, its animation state is returned. Otherwise, FFFFFFFFh is returned.

Land info of nearby tiles (67)

This variable works like industry tile variable 60, except for three things:

  • The offsets in the parameter are interpreted relatively to the alignment of the station, the same way as for variable 66
  • The ss part is "mirrored" (bit 0 and 2 swapped) for the NW-SE orientation; this will allow you to handle analogous slopes of the two orientations without checking the orientation explicitly (since TTDPatch 2.6 r1693)
  • Bit 0 of the bb part is undefined

Station info of nearby tiles (68)

The parameter of this variable works the same way as the parameter of variable 66. The returned value is FFFFFFFFh if the selected tile isn't a railway station tile. Otherwise, the returned value can be separated to the following parts:

Bits Meaning
0..7 If the tile is defined in the current GRF, this is the setID used in the definition. Otherwise, the content is undefined.
8..9 0 - the tile uses original TTD graphics

1 - the tile is defined in the current GRF

2 - the tile is defined in another GRF

10 set if the selected tile belongs to the current station, clear otherwise
11 clear if the selected tile is parallel with the current one, set if perpendicular to it
12..13 0 - plain platform

1 - platform with building

2 - platform with roof, left side

3 - platform with roof, right side

14..31 Undefined, reserved for future use

Information about cargo accepted in the past (69)

The parameter of this variable has the same format as for variables 60..65. The returned value looks like this:

Bits Meaning
0 Set if the given cargo was ever accepted at this station
1 Set if the given cargo was accepted last month
2 Set if the given cargo was accepted this month
3 Set if the given cargo was accepted since last periodic processing (which happens every 250 ticks)
4..31 Undefined, reserved for future use

The information required for this variable is stored in the station2 structure, and therefore works only if the station2 structure is present. The station2 structure is present if any of the following is true:

  • Generalfixes is on, and miscmods.noextendstationrange is off
  • Any of fifoloading, newcargos or irregularstations is on

If the station2 structure isn't present, the returned value is always zero.

Example