Difference between revisions of "Action1"

From GRFSpecs
Jump to navigationJump to search
(→‎Example: left-over closing tag)
m (Add road stops to feature table)
 
(14 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
 
==Introduction==
 
==Introduction==
 
Defining a set of real sprites.
 
Defining a set of real sprites.
 
Action 01 is used to define sets of real sprites (as opposed to pseudo-sprites). It can be put anywhere in the .nfo file after [[Action8|Action 8]].
 
Action 01 is used to define sets of real sprites (as opposed to pseudo-sprites). It can be put anywhere in the .nfo file after [[Action8|Action 8]].
   
==Syntax==
+
== Syntax ==
 
The data looks as follows:
 
   
  +
=== Basic format ===
  +
{{ottdp|0.6|2.0}}
 
<sprite-number> * <length> '''01''' <feature> <num-sets> <num-ent>
 
<sprite-number> * <length> '''01''' <feature> <num-sets> <num-ent>
   
 
{| |-
 
{| |-
!Element!![[GRFActionsDetailed||Size]]!!Description
+
!Element!![[GRFActionsDetailed|Size]]!!Description
 
|-
 
|-
 
|<sprite-number>||dec||A sequential sprite number
 
|<sprite-number>||dec||A sequential sprite number
Line 21: Line 20:
 
|<feature>||B||The feature that following sprites should be used for (s.b.)
 
|<feature>||B||The feature that following sprites should be used for (s.b.)
 
|-
 
|-
|<num-sets>||B||The number of sprite sets you have (one sprite set is one vehicle/station/ship etc)
+
|<num-sets>||B||The number of sprite sets you have (one sprite set is one vehicle/station/ship etc). Setting this to 00 makes it an extended format (see below).
 
|-
 
|-
 
|<num-ent>||B*||The number of views the sprite has
 
|<num-ent>||B*||The number of views the sprite has
 
|}
 
|}
   
The block of data that always follows after action 01 should consist of num-sets * num-ent RealSprites.
+
The block of data that always follows after action 01 should consist of num-sets * num-ent RealSprites or RecolorSprites.
   
  +
=== Extended format ===
==Descriptions==
 
  +
{{ottdp|1.2.2|no|ottdrev=r24361}}
  +
<sprite-number> * <length> '''01''' <feature> '''00''' <first-set> <num-sets> <num-ent>
   
  +
{| |-
===sprite-number===
 
  +
!Element!![[GRFActionsDetailed|Size]]!!Description
  +
|-
  +
|<sprite-number>||dec||A sequential sprite number
  +
|-
  +
|<length>||dec||The total number of bytes used in this action
  +
|-
  +
|01||B||Defines action 01
  +
|-
  +
|<feature>||B||The feature that following sprites should be used for (s.b.)
  +
|-
  +
|00||B||Identfies the extended format.
  +
|-
  +
|<first-set>||B*||The ID of the first spriteset to define
  +
|-
  +
|<num-sets>||B*||The number of sprite sets you have (one sprite set is one vehicle/station/ship etc)
  +
|-
  +
|<num-ent>||B*||The number of views the sprite has
  +
|}
  +
  +
The block of data that always follows after action 01 should consist of num-sets * num-ent RealSprites or RecolorSprites.
  +
  +
== Description ==
  +
 
=== 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 [[Features|feature]] that you wish to change. Set it to:
  +
  +
{|- |
  +
!Value!![[Features|Feature]]
  +
|-
  +
|00||Trains
  +
|-
  +
|01||Road Vehicles
  +
|-
  +
|02||Ships
  +
|-
  +
|03||Aircraft
  +
|-
  +
|04||Stations
  +
|-
  +
|05||Canals/Rivers
  +
|-
  +
|07||Houses
  +
|-
  +
|09||Industry Tiles
  +
|-
  +
|0A||Industries
  +
|-
  +
|0B||Cargos
  +
|-
  +
|0D||Airports
  +
|-
  +
|0F||Objects
  +
|-
  +
|10||Railtypes
  +
|-
  +
|11||Airport Tiles
  +
|-
  +
|12||Roadtypes
  +
|-
  +
|13||Tramtypes
  +
|-
  +
|14||Road Stops
  +
|}
  +
  +
=== first-set ===
  +
This specifies the first set ID to define.
  +
  +
{{ottdp|1.2|no|ottdrev=r22925}} Since OpenTTD r22925 spritesets stay valid across multiple Action1. That is, if one Action1 defines spritesets 0 to 4, and later a second Action1 redefines spriteset 0, spritesets 1 to 4 still refer to the first Action1. Spritesets are feature-specific, each feature maintains its own mapping of ids to Action1 spritesets. (Prior to OpenTTD r22925 and in TTDPatch only spritesets from a single Action1 are referencible from an Action2 at a time. Referencing an Action1 with a different feature than the Action2 is an error.)
  +
  +
This behaviour of Action1 applies to both the basic as well as the extended format.
  +
  +
{{ottdp|1.2|no|ottdrev=r22926}} In addition the extended format allows to specify an ID for the first spriteset to define. That way individual spritesets and be redefined individually.
   
  +
There are no restriction on the order the spritesets are defined. If you define spritesets 23..25 in one Action 1, define spritesets 0..5 in another Action 1, then an Action 2 can access sets 0..5 and 23..25. Later another Action 1 can redefine spritesets 2..3, and following Action 2 could access spritesets 0..1, 2..3, 4, 23..25 from various Action 1.
This sets the type of feature that you wish to change. Set it to:
 
   
  +
Note that all spriteset defined in a single Action1 have the same amount of sprites per spriteset. Using multiple Action1 you can define spriteset with different amounts of sprites per set. Action2 will individually use the size of each referenced spriteset. There is no requirement for consistent numbers of sprites in Action2 or spritelayouts.
00 for trains
 
01 for road vehicles
 
02 for ships
 
03 for planes
 
04 for stations
 
05 for canals
 
06 for bridges
 
07 for houses
 
09 for industry tiles
 
0B for cargos
 
0F for newobjects
 
10 for rail types (since OpenTTD r18969)
 
   
===num-sets===
+
=== num-sets ===
 
The amount of stations, vehicles, ships, etc that the following sprites represent (be warned, one spriteset can be used for more as one vehicle, or truck; you will see this when you reach [[Action2|Action 2]] and [[Action3|Action 3]])
 
The amount of stations, vehicles, ships, etc that the following sprites represent (be warned, one spriteset can be used for more as one vehicle, or truck; you will see this when you reach [[Action2|Action 2]] and [[Action3|Action 3]])
   
===num-ent===
+
=== num-ent ===
   
 
This sets how many different views each entry has.
 
This sets how many different views each entry has.
Line 71: Line 134:
 
For cargos, this should always be 1. The following sprites should be no larger than 10x10 pixels or they won't fit into the station window correctly.
 
For cargos, this should always be 1. The following sprites should be no larger than 10x10 pixels or they won't fit into the station window correctly.
   
Since TTDPatch 2.0.1 alpha 49, this value is a so-called "extended byte" (see [[GRFActionsDetailed]]).
+
{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 49}} Since TTDPatch 2.0.1 alpha 49, this value is a so-called "extended byte" (see [[GRFActionsDetailed]]).
   
Since TTDPatch 2.0.1 alpha 63, it is possible to have <num-ent>=0. This is useful for defining an action 1/2 combination that only serves as invalid callback result. If the .grf file defines no graphics otherwise, this way callbacks can return an explicit failure code without needing any actual sprites to be allocated.
+
{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 63}} Since TTDPatch 2.0.1 alpha 63, it is possible to have <num-ent>=0. This is useful for defining an action 1/2 combination that only serves as invalid callback result. If the .grf file defines no graphics otherwise, this way callbacks can return an explicit failure code without needing any actual sprites to be allocated. This is also needed if the feature has [[Action2/Only_Callback_Failure | no graphics at all]].
   
==Example==
+
== Example ==
   
 
Below is an example of what a real Action 1 pseudo-sprite could look like with the sprite entries under it.
 
Below is an example of what a real Action 1 pseudo-sprite could look like with the sprite entries under it.

Latest revision as of 09:51, 11 June 2023

Introduction

Defining a set of real sprites. Action 01 is used to define sets of real sprites (as opposed to pseudo-sprites). It can be put anywhere in the .nfo file after Action 8.

Syntax

Basic format

Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.02.0

<sprite-number> * <length> 01 <feature> <num-sets> <num-ent>
Element Size Description
<sprite-number> dec A sequential sprite number
<length> dec The total number of bytes used in this action
01 B Defines action 01
<feature> B The feature that following sprites should be used for (s.b.)
<num-sets> B The number of sprite sets you have (one sprite set is one vehicle/station/ship etc). Setting this to 00 makes it an extended format (see below).
<num-ent> B* The number of views the sprite has

The block of data that always follows after action 01 should consist of num-sets * num-ent RealSprites or RecolorSprites.

Extended format

Supported by OpenTTD 1.2.2 (r24361)1.2.2 Not supported by TTDPatch

<sprite-number> * <length> 01 <feature> 00 <first-set> <num-sets> <num-ent>
Element Size Description
<sprite-number> dec A sequential sprite number
<length> dec The total number of bytes used in this action
01 B Defines action 01
<feature> B The feature that following sprites should be used for (s.b.)
00 B Identfies the extended format.
<first-set> B* The ID of the first spriteset to define
<num-sets> B* The number of sprite sets you have (one sprite set is one vehicle/station/ship etc)
<num-ent> B* The number of views the sprite has

The block of data that always follows after action 01 should consist of num-sets * num-ent RealSprites or RecolorSprites.

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
0D Airports
0F Objects
10 Railtypes
11 Airport Tiles
12 Roadtypes
13 Tramtypes
14 Road Stops

first-set

This specifies the first set ID to define.

Supported by OpenTTD 1.2 (r22925)1.2 Not supported by TTDPatch Since OpenTTD r22925 spritesets stay valid across multiple Action1. That is, if one Action1 defines spritesets 0 to 4, and later a second Action1 redefines spriteset 0, spritesets 1 to 4 still refer to the first Action1. Spritesets are feature-specific, each feature maintains its own mapping of ids to Action1 spritesets. (Prior to OpenTTD r22925 and in TTDPatch only spritesets from a single Action1 are referencible from an Action2 at a time. Referencing an Action1 with a different feature than the Action2 is an error.)

This behaviour of Action1 applies to both the basic as well as the extended format.

Supported by OpenTTD 1.2 (r22926)1.2 Not supported by TTDPatch In addition the extended format allows to specify an ID for the first spriteset to define. That way individual spritesets and be redefined individually.

There are no restriction on the order the spritesets are defined. If you define spritesets 23..25 in one Action 1, define spritesets 0..5 in another Action 1, then an Action 2 can access sets 0..5 and 23..25. Later another Action 1 can redefine spritesets 2..3, and following Action 2 could access spritesets 0..1, 2..3, 4, 23..25 from various Action 1.

Note that all spriteset defined in a single Action1 have the same amount of sprites per spriteset. Using multiple Action1 you can define spriteset with different amounts of sprites per set. Action2 will individually use the size of each referenced spriteset. There is no requirement for consistent numbers of sprites in Action2 or spritelayouts.

num-sets

The amount of stations, vehicles, ships, etc that the following sprites represent (be warned, one spriteset can be used for more as one vehicle, or truck; you will see this when you reach Action 2 and Action 3)

num-ent

This sets how many different views each entry has.

For vehicles, this corresponds to the different directions it can be in. If your vehicle is symmetrical you need 4 views, and if it isn't symmetrical then use 8 views.

A station should normally be 12 (hex) because a station is made out of 18 (decimal) sprites, although if you use a different sprite layout for your station this number may vary. For canals, it depends on the canal feature, see Action 3.

For houses and industry tiles, this should be between 1 and 4 and specifies the number of different construction stages. Sprites after the first four are always ignored. See also action 2 and 3.

For cargos, this should always be 1. The following sprites should be no larger than 10x10 pixels or they won't fit into the station window correctly.

Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.5 (2.0.1 alpha 49)2.5 Since TTDPatch 2.0.1 alpha 49, this value is a so-called "extended byte" (see GRFActionsDetailed).

Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.5 (2.0.1 alpha 63)2.5 Since TTDPatch 2.0.1 alpha 63, it is possible to have <num-ent>=0. This is useful for defining an action 1/2 combination that only serves as invalid callback result. If the .grf file defines no graphics otherwise, this way callbacks can return an explicit failure code without needing any actual sprites to be allocated. This is also needed if the feature has no graphics at all.

Example

Below is an example of what a real Action 1 pseudo-sprite could look like with the sprite entries under it.

2 * 4 01 00 01 08
3 C:\TTD\SPRITES\mytrain.pcx 66 8 01 18 8 -3 -10
4 C:\TTD\SPRITES\mytrain.pcx 82 8 09 15 20 -14 -6
5 C:\TTD\SPRITES\mytrain.pcx 114 8 01 12 28 -14 -6
6 C:\TTD\SPRITES\mytrain.pcx 162 8 09 16 20 -4 -8
7 C:\TTD\SPRITES\mytrain.pcx 194 8 01 18 8 -3 -10
8 C:\TTD\SPRITES\mytrain.pcx 210 8 09 16 20 -14 -7
9 C:\TTD\SPRITES\mytrain.pcx 242 8 01 12 28 -14 -6
10 C:\TTD\SPRITES\mytrain.pcx 290 8 09 15 20 -4 -7
Byte Meaning
2 <sprite-number>
4 <length> of the action in bytes; start counting at 01 (<action>)
01 <action>: sets this pseudo-sprite to function as action 1
00 <feature>: In this case Train
01 <num-sets>: 1 Set of views
08 <num-ent>: 8 views of this train