Difference between revisions of "Action3"

From GRFSpecs
Jump to navigationJump to search
(Updated tables syntax)
(Add road stops to cargo IDs table)
 
(16 intermediate revisions by 9 users not shown)
Line 1: Line 1:
  +
== Introduction ==
−
=Action 3=
  
−  
−
Associate feature IDs with graphics sets.
  
−  
−
==Introduction==
  
   
 
Action 3 assigns graphics sets (referenced to by (chains of) [[Action2|action 2(s]]) to feature IDs (vehicles, stations, houses, industries, ...).
  
Action 3 assigns graphics sets (referenced to by (chains of) [[Action2|action 2(s]]) to feature IDs (vehicles, stations, houses, industries, ...).
   
−
==Format==
 +
== Format ==
   
 
The format of the data is feature-dependent.
  
The format of the data is feature-dependent.
Line 13: Line 9:
 
The data is:
  
The data is:
   
−
<pre> -+&lt;Sprite-number&gt; * &lt;Length&gt; 03 &lt;feature&gt; &lt;n-id&gt; &lt;ids...&gt; &lt;num-cid&gt; (&lt;cargo-type&gt; &lt;set-ID&gt;)... &lt;default set-ID&gt;+-</pre>
 +
<pre> &lt;Sprite-number&gt; * &lt;Length&gt; 03 &lt;feature&gt; &lt;n-id&gt; &lt;ids...&gt; &lt;num-cid&gt; (&lt;cargo-type&gt; &lt;set-ID&gt;)... &lt;default set-ID&gt;</pre>
   
 
{| class="wikitable"
  
{| class="wikitable"
Line 62: Line 58:
 
|}
  
|}
   
  +
== Description ==
−
==Filling in the terms==
  
   
−
===Sprite-number===
 +
=== Sprite-number ===
   
 
This is just the number you are at.
  
This is just the number you are at.
   
−
===Length===
 +
=== Length ===
   
 
Count the number of bytes in this action.
  
Count the number of bytes in this action.
   
−
===Feature===
 +
=== Feature ===
   
−
This sets the type of feature that you wish to change. Set it to:
 +
This sets the type of [[Features|feature]] that you wish to change. Set it to:
   
  +
{|- |
−
00 for trains
  
  +
!Value!![[Features|Feature]]
−  
−
01 for road vehicles
  
−  
−
02 for ships
  
−  
−
03 for planes
  
−  
−
04 for stations
  
−  
−
05 for canals/rivers
  
−  
−
07 for houses
  
−  
−
09 for industry tiles
  
−  
−
0A for industries
  
−  
−
0B for cargos
  
−  
−
0F for Objects
  
−  
−
10 for Railtypes
  
−  
−
===n-id===
  
−  
−
How many items of the current feature this action 3 defines new graphics for. If this is more than one, all items listed will get the same graphics. If this value has bit 7 set (i.e. 80 added), it is a wagon override. See [[Action3LiveryOverride|Action 3 - Livery Override]] for more info on this feature.
  
−  
−
You can make a definition with n-id equal to zero (and thus no ids that follow). &nbsp;This creates a generic feature-specific definition not associated with any particular feature. &nbsp;At the moment, this is used for generic callbacks, but might be extended to other functions eventually.
  
−  
−
===ids===
  
−  
−
Feature IDs to use this action 3 for. All IDs are counted from the first of their class, i.e. the first road vehicle has 00, as does the first plane, the first ship, and the first train vehicle.
  
−  
−
In OpenTTD since r13482, each ID is an extended byte for vehicles, otherwise the ID is a regular byte.
  
−  
−
For feature 05 (canals/rivers):
  
−  
−
{| class="wikitable"
  
 
|-
  
|-
  +
|00||Trains
−
!'''ID'''
  
−
!'''Description'''
  
−
!'''Number of sprites'''
  
 
|-
  
|-
  +
|01||Road Vehicles
−
|00
  
−
|Watercliffs
  
−
|4*
  
 
|-
  
|-
  +
|02||Ships
−
|01
  
−
|Locks
  
−
|24
  
 
|-
  
|-
  +
|03||Aircraft
−
|02
  
−
|Dikes
  
−
|12
  
 
|-
  
|-
  +
|04||Stations
−
|03
  
  +
|-
−
|Icons
  
  +
|05||[[Action3/Canals|Canals/Rivers]]
−
|1*
  
  +
|-
  +
|07||Houses
  +
|-
  +
|09||Industry Tiles
  +
|-
  +
|0A||Industries
 
|-
  
|-
  +
|0B||Cargos
−
|04
  
−
|Flat docks
  
−
|4
  
 
|-
  
|-
  +
|0C||Sound Effects (generic callback only)
−
|05
  
−
|River slopes
  
−
|4*
  
 
|-
  
|-
  +
|0D||Airports
−
|06
  
−
|River watersides
  
−
|12*5 (last 4 for slopes)
  
 
|-
  
|-
  +
|0E||Signals (generic callback only)
−
|07
  
  +
|-
−
|River GUI
  
  +
|0F||Objects
−
|2
  
  +
|-
  +
|10||[[Action3/Railtypes|Railtypes]]
  +
|-
  +
|11||Airport Tiles
  +
|-
  +
|12||[[Action3/Roadtypes|Roadtypes]]
  +
|-
  +
|13||[[Action3/Tramtypes|Tramtypes]]
  +
|-
  +
|14||Road Stops
 
|}
  
|}
   
  +
=== n-id ===
−
Note: The Number of sprites for feature 05 canals/rivers may change via a graphics flag set in Action0Canals
  
   
  +
How many items of the current feature this action 3 defines new graphics for. If this is more than one, all items listed will get the same graphics. If this value has bit 7 set (i.e. 80 added), it is a wagon override. See [[Action3LiveryOverride|Action 3 - Livery Override]] for more info on this feature.
−
For town buildings, the IDs are the house IDs, and specifying a house ID that haven't been defined before (by setting its property 08) doesn't do anything, but doesn't cause an error, either. Note that you don't necessarily have to assign a set-ID to a house ID, the old TTD sprite of the substitute type will be used if you don't do so. &nbsp;Industry tile IDs work in the same manner.
  
   
  +
You can make a definition with n-id equal to zero (and thus no ids that follow). &nbsp;This creates a generic feature-specific definition not associated with any particular item. &nbsp;At the moment, this is used for generic callbacks, but might be extended to other functions eventually.
−
===num-cid===
  
   
  +
=== ids ===
−
Number of cargo type definitions that follow. Can be zero if only the default follows.
  
   
  +
Feature IDs to use this action 3 for. All IDs are counted from the first of their class, i.e. the first road vehicle has 00, as does the first plane, the first ship, and the first train vehicle.
−
For features 05 (canals/rivers), 07 (houses), 09 (industry tiles), 0A (industries), and 0B (cargoes) this must always be zero.
  
   
  +
In OpenTTD since r13482, each ID is an extended byte for vehicles, otherwise the ID is a regular byte.
−
===cargo-type===
  
   
  +
Since OpenTTD 14.0, each ID is an extended byte for all features.
−
<u>For vehicles (features 00 .. 03) and stations (feature 04)</u>
  
   
  +
For canals and rivers the id has a special meaning, see its [[Action3/Canals|own Action 3 page]]
−
The cargo-type for which the set-ID applies. &nbsp;If the item is built to use this type of cargo, or if it is refitted for it, the given set-ID is used as its graphics. &nbsp;See column &quot;type A&quot; in the table at [[CargoTypes]] for a list of cargo-type values.
  
   
  +
For town buildings, the IDs are the house IDs, and specifying a house ID that haven't been defined before (by setting its property 08) doesn't do anything, but doesn't cause an error, either. Note that you don't necessarily have to assign a set-ID to a house ID, the old TTD sprite of the substitute type will be used if you don't do so. &nbsp;Industry tile IDs work in the same manner.
−
If the grf file has installed a [[Action0GeneralVariables#Cargo_translation_table_09_|cargo translation table]], the cargo type here refers to the cargo with the label in the given slot of the translation table, e.g. if you use cargo-type=08, it refers to the cargo that has the label in the ninth slot (numbered 08) in the translation table.
  
   
  +
=== num-cid ===
−
If defined, cargo-type FF is used for graphics shown in the purchase or construction window.
  
   
  +
Number of cargo type definitions that follow. Can be zero if only the default follows.
−
For stations, you can additionally define a special cargo-type of FE which prevents the default from being used (which would show the sum of all cargo). &nbsp;Instead, the given set-ID is displayed with no cargo at all.
  
   
  +
For features 05 (canals/rivers), 07 (houses), 09 (industry tiles), 0A (industries), and 0B (cargoes) this must always be zero.
−
<u>For railtypes (feature 10)</u>
  
   
  +
=== cargo-type ===
−
Railtypes are available only in OpenTTD &gt; r19056 and its action 3 re-uses the 'cargo'-type definition in order to assign the type of graphics defined by the associated set-ID:
  
   
  +
{|
−
{| class="wikitable"
  
 
|-
  
|-
  +
! Feature !! cids
−
!'cargo' type
  
−
!sprite type
  
−
!#sprites
  
−
!usage
  
 
|-
  
|-
  +
| 00..03 vehicles ||
−
|00
  
  +
* 00..FE: cargo-type (index in [[Action0/Global Settings#Cargo translation table 09|cargo translation table]]; cargobit if no table present)
−
|Icons and cursors(a)
  
  +
* FF: purchase list <ref>For dual-headed trains (prop 13) special rules for the purchase menu sprite apply: two sprites are drawn (for front and back) as if the vehicle is normally constructed. If you supply one purchase menu sprite, it will be used for both vehicle parts in the purchase menu. Provide a set of 8 sprites, and the 7th resp. 3rd sprite will
−
|16
  
  +
be drawn; provide a set of 8 blank sprites except the 7th if you want to fully control a single purchase menu sprite for a dual-headed engine.</ref>
−
|4 rail directions, autorail, depot, tunnel and convert rail. First all icons, then all cursors.
  
  +
* default: used if none of the listed cids apply
 
|-
  
|-
  +
| 04 stations ||
−
|01
  
  +
* 00..FD: cargo-type (index in [[Action0/Global Settings#Cargo translation table 09|cargo translation table]]; cargobit if no table present) waiting at the station. The waiting amount of this cargo is used in [[Action2/Stations|Action2]] to decide the spriteset.
−
|Track overlays for junctions and PBS(a)
  
  +
* FE: used if none of the listed cids apply. [[Action2/Stations|Action2]] will assume "zero waiting cargo".
−
|10
  
  +
* FF: purchase list
−
|6 flat and 4 slope pieces. Sprites should contain only the track, with no landscape.
  
  +
* default: used if none of the listed cids apply. [[Action2/Stations|Action2]] will use "sum of all waiting cargos".
 
|-
  
|-
  +
| 05 canals || default only
−
|02
  
−
|Underlay(a)
  
−
|16
  
−
|6 flat and 4 slope, and 1 X crossing pieces ''with track'', and 5 junction pieces without track. Sprites should contain the track and the 'ballast' below it. No landscape should be drawn.
  
 
|-
  
|-
  +
| 07 houses || default only
−
|03
  
−
|Tunnel(a)
  
−
|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.
  
 
|-
  
|-
  +
| 09 industry tiles || default only
−
|04
  
−
|Catenary wire
  
−
|28
  
−
|Follows the same layout for wires of the first 28 sprites as Action5 type 5.
  
 
|-
  
|-
  +
| 0A industries || default only
−
|05
  
−
|Catenary pylons
  
−
|8
  
−
|Follows the same layout for pylons of the 8 sprites after the wires as Action5 type 5.
  
 
|-
  
|-
  +
| 0B cargos || default only
−
|06
  
−
|Bridge surfaces(a)
  
−
|6
  
−
|10 sprites if we ever include diagonal bridges.
  
 
|-
  
|-
  +
| 0C sound effects || default only
−
|07
  
−
|Level crossing overlay(a)
  
−
|10
  
−
|1 rail overlay and 4 light sprites for X and Y.(b)
  
 
|-
  
|-
  +
| 0D airports || default only
−
|08
  
−
|Depots
  
−
|6
  
−
|2 sprites for each southish, 1 sprite for each northish. Follows the original layout for depot sprites.(c)
  
 
|-
  
|-
  +
| 0E signals || default only
−
|09
  
−
|Fences
  
−
|8
  
−
|X, Y, Vertical, Horizontal, SW slope, SE slope, NE slope and NW slope. Follows the same layout as original original fence sprites at sprite 1301.
  
−
|}
  
−  
−
(a) These sprites must be provided, the others may be left out, if not needed.
  
−  
−
(b) Level crossing sprites:
  
−  
−
{| class="wikitable"
  
 
|-
  
|-
  +
| 0F objects ||
−
!Sprite number for X
  
  +
* FF: purchase list
−
!Sprite number for Y
  
  +
* default: used if none of the listed cids apply
−
!Useage
  
 
|-
  
|-
  +
| 10 rail types || special cids, see [[Action3/Railtypes#cargo-type|here]]
−
|0
  
−
| &nbsp; &nbsp;1
  
−
| &nbsp; &nbsp;Rail overlay
  
 
|-
  
|-
  +
| 11 airport tiles || default only
−
|2
  
−
| &nbsp; &nbsp;3
  
−
| &nbsp; &nbsp;North light
  
 
|-
  
|-
  +
| 12 road types || special cids, see [[Action3/Tramtypes#cargo-type|here]]
−
|4
  
−
| &nbsp; &nbsp;5
  
−
| &nbsp; &nbsp;East light
  
 
|-
  
|-
  +
| 13 tram types || special cids, see [[Action3/Roadtypes#cargo-type|here]]
−
|6
  
−
| &nbsp; &nbsp;7
  
−
| &nbsp; &nbsp;West light
  
 
|-
  
|-
  +
| 14 road stops ||
−
|8
  
  +
* 00..FD: cargo-type (index in [[Action0/Global Settings#Cargo translation table 09|cargo translation table]]; cargobit if no table present) waiting at the road stop.
−
| &nbsp; &nbsp;9
  
  +
* FE: used if none of the listed cids apply.
−
| &nbsp; &nbsp;South light
  
  +
* FF: purchase list
−
|}
  
  +
* default: used if none of the listed cids apply.
−  
−
(c)Depot sprites:
  
−  
−
{| class="wikitable
  
 
|-
  
|-
−
!Sprite Number
  
−
!Useage
  
−
|-
  
−
|0
  
−
| &nbsp; &nbsp;NE wall for SE-entry depot.
  
−
|-
  
−
|1
  
−
| &nbsp; &nbsp;Depot building for SE-entry depot.
  
−
|-
  
−
|2
  
−
| &nbsp; &nbsp;NW wall for SW-entry depot.
  
−
|-
  
−
|3
  
−
| &nbsp; &nbsp;Depot building for SW-entry depot.
  
−
|-
  
−
|4
  
−
| &nbsp; &nbsp;Depot building for NE-entry depot.
  
−
|-
  
−
|5
  
−
| &nbsp; &nbsp;Depot building for NW-entry depot.
  
 
|}
  
|}
   
  +
<references/>
−
<u>For canals/rivers, houses, industry tiles, industries and cargoes (features 05, 07, 09, 0A and 0B)</u>
  
−  
−
As &lt;num-cid&gt; is zero for features 05 (canals/rivers), 07 (houses), 09 (industry tiles), 0A (industries), and 0B (cargoes), &lt;cargo-type&gt; and &lt;set-ID&gt; need to be skipped and you only have to set &lt;default set-ID&gt;.
  
−  
−
<u>For objects (feature 0F)</u>
  
−  
−
Objects support a buy menu sprite similar to vehicles (cargo-type FF).
  
   
−
===default set-ID===
 +
=== default set-ID ===
   
 
Default set-ID if no entry from the cargo-type list above matches, or if there are no special cargo-types listed at all.
  
Default set-ID if no entry from the cargo-type list above matches, or if there are no special cargo-types listed at all.
   
−
==Example==
 +
== Example ==
   
 
Below is an example of what a real action 3 pseudo-sprite could look like for a train engine.
  
Below is an example of what a real action 3 pseudo-sprite could look like for a train engine.

Latest revision as of 14:17, 24 December 2023

Introduction

Action 3 assigns graphics sets (referenced to by (chains of) action 2(s) to feature IDs (vehicles, stations, houses, industries, ...).

Format

The format of the data is feature-dependent.

The data is: 

 <Sprite-number> * <Length> 03 <feature> <n-id> <ids...> <num-cid> (<cargo-type> <set-ID>)... <default set-ID>
Element Size Description
<Sprite-number> dec A sequential sprite number
<length> dec The total number of bytes used in this action
03 B Defines action 03
<feature> B What type of feature the IDs refer to
<n-id> B Number of IDs this action 3 associates graphics with
<ids...> B/B* IDs of the current feature this action 3 associates graphics with. There must be as many IDs as <n-id> specifies
<num-cid> B Number of different cargo types to support
<cargo-type> B Cargo type for which to use the following set-ID
<set-ID> W Set-ID (from action 2 or from a varaction2 chain) to use for this cargo type
<default set-ID> W Default set-ID to use if none of the above matches

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
0B Cargos
0C Sound Effects (generic callback only)
0D Airports
0E Signals (generic callback only)
0F Objects
10 Railtypes
11 Airport Tiles
12 Roadtypes
13 Tramtypes
14 Road Stops

n-id

How many items of the current feature this action 3 defines new graphics for. If this is more than one, all items listed will get the same graphics. If this value has bit 7 set (i.e. 80 added), it is a wagon override. See Action 3 - Livery Override for more info on this feature.

You can make a definition with n-id equal to zero (and thus no ids that follow).  This creates a generic feature-specific definition not associated with any particular item.  At the moment, this is used for generic callbacks, but might be extended to other functions eventually.

ids

Feature IDs to use this action 3 for. All IDs are counted from the first of their class, i.e. the first road vehicle has 00, as does the first plane, the first ship, and the first train vehicle.

In OpenTTD since r13482, each ID is an extended byte for vehicles, otherwise the ID is a regular byte.

Since OpenTTD 14.0, each ID is an extended byte for all features.

For canals and rivers the id has a special meaning, see its own Action 3 page

For town buildings, the IDs are the house IDs, and specifying a house ID that haven't been defined before (by setting its property 08) doesn't do anything, but doesn't cause an error, either. Note that you don't necessarily have to assign a set-ID to a house ID, the old TTD sprite of the substitute type will be used if you don't do so.  Industry tile IDs work in the same manner.

num-cid

Number of cargo type definitions that follow. Can be zero if only the default follows.

For features 05 (canals/rivers), 07 (houses), 09 (industry tiles), 0A (industries), and 0B (cargoes) this must always be zero.

cargo-type

Feature cids
00..03 vehicles
  • 00..FE: cargo-type (index in cargo translation table; cargobit if no table present)
  • FF: purchase list [1]
  • default: used if none of the listed cids apply
04 stations
  • 00..FD: cargo-type (index in cargo translation table; cargobit if no table present) waiting at the station. The waiting amount of this cargo is used in Action2 to decide the spriteset.
  • FE: used if none of the listed cids apply. Action2 will assume "zero waiting cargo".
  • FF: purchase list
  • default: used if none of the listed cids apply. Action2 will use "sum of all waiting cargos".
05 canals default only
07 houses default only
09 industry tiles default only
0A industries default only
0B cargos default only
0C sound effects default only
0D airports default only
0E signals default only
0F objects
  • FF: purchase list
  • default: used if none of the listed cids apply
10 rail types special cids, see here
11 airport tiles default only
12 road types special cids, see here
13 tram types special cids, see here
14 road stops
  • 00..FD: cargo-type (index in cargo translation table; cargobit if no table present) waiting at the road stop.
  • FE: used if none of the listed cids apply.
  • FF: purchase list
  • default: used if none of the listed cids apply.
  1. ↑ For dual-headed trains (prop 13) special rules for the purchase menu sprite apply: two sprites are drawn (for front and back) as if the vehicle is normally constructed. If you supply one purchase menu sprite, it will be used for both vehicle parts in the purchase menu. Provide a set of 8 sprites, and the 7th resp. 3rd sprite will be drawn; provide a set of 8 blank sprites except the 7th if you want to fully control a single purchase menu sprite for a dual-headed engine.

default set-ID

Default set-ID if no entry from the cargo-type list above matches, or if there are no special cargo-types listed at all.

Example

Below is an example of what a real action 3 pseudo-sprite could look like for a train engine. 

 13 * 7   03 00 01 02 00 00 00
Byte Meaning
13 <sprite-number>
7 <length> of the action in bytes; start counting at 03 (<action>)
03 <action>: sets this pseudo-sprite to function as action 3
00 <feature>: 00 for trains
01 <n-id>: One ID to change in this case
02 <ids...>: vehicle ID (02 - Ploddyphut Choo-Choo)
00 <num-cid>: this engine doesn't have cargo-specific graphics
00 00 <default set-ID>: Use action 2 ID 00, because it is a word value you add 00
Retrieved from ‘https://newgrf-specs.tt-wiki.net/index.php?title=Action3&oldid=4689’