Action11

From GRFSpecs
Revision as of 08:57, 16 June 2011 by Planetmaker (talk | contribs) (Fix: broken link)
Jump to navigationJump to search

Introduction

Define new sound data. This action allows the definition of binary included sound samples.

Syntax

The data looks as follows:

<sprite-number> * <length> 11 <number>
Element Size Description
<sprite-number> dec A sequential sprite number
<length> dec The total number of bytes in the action
11 B Action 11
<number> W Number of binary include sprites that follow

Notes

Action 11 may only appear at most once per .grf file.

The newly defined sounds will be numbered consecutively, starting from 73 (49h) (numbers 0..72 represent original sounds). When you need to refer to your new sounds, you will have to use this numbering.

Available since TTDPatch 2.0.1 alpha 57.

Description

sprite-number

The current sprite number.

length

The total number of bytes in this action 11.

number

This defines the number of binary include sprites that follow.

These can only be added using GRFCodec 0.9.7 or later, using the following format:

17 ** sounds/e67_horn.wav
18 ** sounds/sheep.wav

All files included this way must be 8-bit mono sound files in WAV format, PCM encoding. There are two allowed frequencies: 11025 Hz and 22050 Hz. Due to some limitations of the GRF format, the file size cannot exceed 64 kB.

For those need to know or are inordinately curious, the actual encoding of a binary include is the same as a pseudosprite:

<sprite-number> * <length> FF <name-len> <name> 00 <data>
Element Size Description
<name-len> B The return value of strlen(<name>);
<length> S The name of the included file, with any leading directories stripped
00 B Null byte terminating the string (not included in size)
V A byte-for-byte copy of the contents of the file

Importing sound effects from other grf files

Since TTDPatch 2.0.1 alpha 61, it is possible to import sound effects from other grf files (or even the current file).  This does not copy the sound effect data (thus reducing memory usage), but does provide a new sound effect entry with its own action 0 properties.

This is a way of either combining useful sound effects in a single grf file and using them in several, or to duplicate sounds with different amplification or priority settings without doubling the memory usage.

The referenced grf file can be anywhere in newgrf(w).cfg and does not have to be active.  If it is not loaded, no sound will be played but that is not an error condition. This makes it possible to separate sound effects and graphics into two files, to allow people with little memory to not load the sound effects yet get working graphics.

The format of such an import sprite is the following (replacing a "**" binary sprite within the action 11 sprite block):

<sprite-number> * <length> FE 00 <GRFID> <number>
Element Size Description
<sprite-number> dec A sequential sprite number
<length> dec The total number of bytes in the action
FE B Code to identify a non-binary sprite in an action 11 block
00 B Code to identify a sound effect import
<GRFID> D GRFID of grf file to import sound effect from, may be the current one too
<number> W Sound effect number to import

Note that unlike most other reference to sound numbers, the number here is simply the number within the referenced grf file's action 11 block, and does not refer to TTD's samples for numbers 0..72. Also, when importing the sound effect, the action 0 properties are not imported and have to be set separately.

Example

Look at this tt-forums-page for how to add sounds to a train: [1]