RandomAction2
From GRFSpecs
Contents |
Introduction
Unlike VariationalAction2, whose results are always determined by a predictable decision, RandomAction2 can use randomized results to pick one of several Action2 entries.
Format
The data looks as follows:
<Sprite-number> * <Length> 02 <feature> <set-id> [80|83] <random-triggers> <randbit> <nrand> <set-ids>
From TTDPatch 2.6 r1850 and OpenTTD r12452, and for vehicles only:
<Sprite-number> * <Length> 02 <feature> <set-id> 84 <count> <random-triggers> <randbit> <nrand> <set-ids>
| Element | Size | Description |
|---|---|---|
| <Sprite-number> | dec | A sequential sprite number |
| <length> | dec | The total number of bytes used in this action. |
| 02 | B | Defines action 02 |
| <feature> | B | For what type of vehicle/station/... should this definition be used? |
| <set-id> | B | The ID of this action 2 (used like a cargo ID) |
| 80, 83, 84 | B | Type of random action, see below. |
| <count> | B | (when present) Location of controlling vehicle. |
| <random-triggers> | B | When to re-randomize |
| <randbit> | B | What random bit to use for this action 2 |
| <nrand> | B | Number of set-ids to choose from, must be a power of 2 |
| <set-ids> | W | Action 2 set-ids to choose from. |
Description
Sprite-number
This is just the number you are at.
Length
Count the number of bytes in this action.
Feature
This sets the type of feature that you wish to change. Set it to:
| Value | Feature |
|---|---|
| 00 | Trains |
| 01 | Road Vehicles |
| 02 | Ships |
| 03 | Aircraft |
| 04 | Stations |
| 05 | Canals/Rivers |
| 07 | Houses |
| 09 | Industry Tiles |
| 0A | Industries |
| 0D | Airports |
| 0F | Objects |
| 10 | Railtypes |
| 11 | Airport Tiles |
set-ID
This defines the number of this action 2. The ID can then be used as target in an action 3 or another variational/random action 2.
80/83/84
Use 80 to randomize the object (vehicle, station, building, industry, object) based on its own triggers and bits.
Use 83 to randomize the object based on its "related" object (s.b.).
Use 84 to randomize the vehicle based on any vehicle in the consist.
| Feature | Related object |
|---|---|
| Vehicles (00-03) | First vehicle of consist |
| Stations (04) | N/A |
| Houses (07) | N/A |
| Industry tiles (09) | Industry containing tile |
| Industries (0A) | N/A |
| Objects (0F) | N/A |
count
For type 84, this specifies which vehicle's random bits this vehicle will be using and/or modifying.
The low nibble (bits 0-3) specifies how far to count from the starting vehicle. If it is zero, the count will be read from GRF register 100h instead.
The high nibble (bits 6-7, actually) specifies which vehicle is the starting vehicle, and which direction to count:
| 0 | count back (away from the engine), starting at this vehicle |
|---|---|
| 4 | count forward (toward the engine), starting at this vehicle. |
| 8 | count back, starting at the engine |
| C | count back, starting at the first vehicle in this chain of vehicles with the same ID, as for vehicle variable 41 |
Bits 4-5 are reserved and must be zero, so other values of the high nibble are not allowed.
random-triggers
This is a bit mask of triggers which cause re-randomizing. Normally, any matching trigger causes the graphics to be randomized again, but if you add 80 to the bitmask, the re-randomizing only happens if all triggers have occurred.
Trigger bits are feature-specific, see below.
randbit
<2.5 For versions before TTDPatch 2.0.1 alpha 30, leave this at 00. It doesn't quite work the way intended (it was supposed to allow independent random chains, but currently everything is re-randomized at the same time, thereby defeating this mechanism).
2.5 Since TTDPatch 2.0.1 alpha 30, only those bits that actually get triggered will be re-randomized. Prior versions always re-randomized all bits. This will make it possible to have independent sets of bits for independent triggers (or untriggered bits, set only at the time of purchase). Setting randbit determines the first bit to be re-randomized, as well as basing the random graphics on. The total number of bits used is the 2-logarithm of nrand below (e.g., for nrand=16, 4 bits are used).
nrand
Number of different sets to choose from. This must be a power of 2, i.e. 2, 4, 8, 16 etc.
set-ids
Action 2 IDs to randomly choose from
Triggers
| Feature | Random bits | Triggers | |
|---|---|---|---|
| Self | Related | ||
| Vehicles | 8 | 8 read-only | yes |
| Stations | 16 + 4 (*)(**) | no | yes |
| Canals | 8 | no | no |
| Houses | 8 | no | yes |
| Industry tiles | 8 | 16 | yes |
| Industries | 16 | no | no |
| Airports | 16 (*) | no | no |
| Objects | 8 | no | no |
| Railtypes | 2 | no | no |
| Airport tiles | 16 + 4 (*) | no | no |
(*) 16 Bits shared bits for the whole station/airport (airport and station share the same bits). 4 bits per tile.
(**) TTDPatch actually only implements 8 shared random bits (plus 4 per tile). Bits 8-15 are always zero.
Vehicles
Vehicles have 8 random bits, and the following triggers:
| Bit | Value | Trigger |
|---|---|---|
| 0 | 01 | Vehicle gets new load of cargo (only after it was empty) |
| 1 | 02 | Vehicle enters a depot and is serviced |
| 2 | 04 | The consist has unloaded all cargo |
| 3 | 08 | Any vehicle of the consist receives cargo |
| 4 | 10 | Callback 32 returned 1 |
The consist trigger bits 2 and 3 allow re-randomizing whenever the consist receives cargo after fully unloading. They should be used with action 2 type 80, not 83, and the random-triggers variable should have 80 added to it, to make the re-randomizing happen only if the consist was empty and then received new cargo.
Vehicles can read the random bits of other vehicles (using random action type 83 or 84), but they can only trigger rerandomisation of their own bits. Do not specify any triggers for rerandomisation when accessing random bits of other vehicles (via type 83 or 84), it will not do what you think.
Stations
Stations have 16+4 random bits. Bits 0 to 15 are a property of the station as a whole, and bits 16 to 19 are different for each tile. To get tile-based randomness, therefore use randbit=10 and nrand of no more than 16 (since only 4 random bits are available per tile).
| Bit | Value | Trigger |
|---|---|---|
| 0 | 01 | new cargo waiting |
| 1 | 02 | no more cargo |
| 2 | 04 | train arrives (starts unloading/loading) |
| 3 | 08 | train leaves (done unloading & loading) |
| 4 | 10 | train loads or unloads cargo |
| 5 | 20 | train reserves platform (using PBS) |
Also note that none of the above triggers will actually trigger unless prop. 12 has at least one bit set. Triggers 01 will be triggered for any of the cargo types set in prop. 12, but trigger 02 will only be triggered if all of those cargo types have no more cargo waiting. Triggers 04, 08 and 20 are triggered no matter what cargo types the train transports, as long as prop. 12 is not zero.
Triggers 04, 08, 10 and 20 only affect the platform on which they occur, as well as the random bits of the station, but not other platforms.
Because the 'occured triggers' are only stored once per station (not distinguishing tiles or cargo types), adding 80 to random-triggers does not make a lot of sense.
Town building triggers
Town buildings have 8 random bits.
| Bit | Value | Trigger |
|---|---|---|
| 0 | 01 | the building tile is processed in the periodic tile processing loop |
| 1 | 02 | the top tile of the building is processed in the periodic tile processing loop |
The periodic tile processing loop constantly processes the tiles of the map, processing any given tile in every 256 ticks (approx. 3.5 TTD days). Since no "real" event happens to town buildings, you have only this opportunity to re-randomize the look of your building.
If every 3.5 days is too fast for you, you can multiply the time-out by setting property 16 for the given tile. The time-out is 256 ticks*(prop. 16+1), so 0 means every 3.5 days, 1 means every 7 days, 2 means every 10.5 days and so on.
If trigger 02 is activated, all parts of the building that has this trigger set will get the same random bits, allowing you to randomize a multi-tile building as one unit. On the other hand, if the tiles of a multi-tile building have trigger 1 set, all tiles will be randomized individually. Note that all tiles of a multi-tile building get the same value when building the building.
Industry tile triggers
Industry tiles have 8+16 random bits. Accessed through random action 2 type 80, you get 8 tile-specific bits, and accessed through random action 2 type 83, you get 16 industry-specific bits. The triggers are the same for both. Triggers 02 and 04 are triggered for all tiles of the industry at once. Every tile can rerandomise both its own random bits and those of the industry. That is every tile can specify some bits of the industry to rerandomsize, and the union of all those bits will be rerandomsied at the end.
| Bit | Value | Trigger |
|---|---|---|
| 0 | 01 | the building tile is processed in the periodic tile processing loop[1] |
| 1 | 02 | triggers simultaneously for all tiles of the industry every 256 ticks. If the industry is a primary one, output cargo is generated at the same time. |
| 2 | 04 | cargo is delivered to the industry. If the industry is a processing one, output cargo is generated at the same time. |
- ↑
Rerandomisation of the shared bits of the industry does not happen properly in current TTDPatch.
Trigger 1 works similarly to trigger 1 for houses except that you cannot multiply the timeout: it's always 256 ticks.
Industry tiles can rerandomise both their own random bits as well as the random bits of the industry (via random action type 83). The triggers for rerandomisation are both remembered per tile and for the industry, so adding 80 to random-triggers works independently for random action type 80 and 83.
Industries have random bits. However, they can only be rerandomised by their tiles.
Canals
Canals / Rivers have 8 random bits.
There is currently no way to influence the random byte creation via triggers, internally the bits are feed from VarAction2Canals var 83 that is set when building a canal. Feature ids not supported by VarAction2Canals are undefined and should never be used.
Objects
Objects have 8 random bits per tile of the object.
There are no triggers for objects however.
Also note that the random bits are unique to each tile in the object, and are not shared across the whole object.
Rail types
Rail tiles have 2 pseudo random bits, based on tile location.
There are no triggers.
Other features
All features not mentioned in the list above have neither random bits nor triggers, including towns (which would be accessed using random action 2 type 83 for stations and industries).
