animation_fileformat.txt

Copyright (c) 2013-2014 Albert "Alberth" Hofkamp

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



The animation file format stores named animations for CorsixTH. It starts with
a header, followed by a number of *blocks*. A block has a block type, and some
information. It may also refer to other blocks of a different type.

Each type of block is numbered independently of the other block types. The
first block of a block type has number 0, the second block in the file of the
same block type has number 1, and so on. A reference to another block only
stores the number, the type of the block being referenced is derived from the
block containing the reference. The blocks with their references form a
directed acyclic graph, and the file format guarantees that any referenced
block has been encountered (and loaded) before encountering the reference,
when reading the file sequentially from start to end. Block reference
0xFFFFFFFF means there is no block to reference to.

The core concept is an animation sequence of something that exists in the
game. It can be a 'real' animation of a sliding door, or a treatment in
progress. It could be a 'still', like a desk or a plant. An animation consists
of one or more frames, a display of how it looks at a point in time. A frame
consists of one or more sprites, placed at the right spot. In many cases, the
same animation exists several times, for example a moving door animation for
the case that it is in a north-south wall, and one for the case that the door
is in a east-west wall. To make it simpler to keep such animations together,
animations are grouped. It contains up to four animations, one for each
direction of view.


Block descriptions
==================

Below are the block descriptions, starting with the header (the first entry in
the file, followed by other blocks that eventually lead to grouped animation
blocks.

All numbers are 2-complementary in low endian (that is lo bytes before hi
bytes).


Header
------

Offset  Length  Description
======  ======  ============================================================
   0       4    File identification 'C', 'T', 'H', 'G'.
   4       2    Version number, 512 + 1.
   6       4    Number of grouped animation blocks in the file.
  10       4    Number of frame blocks in the file.
  14       4    Total number sprite elements in the frames.
  18       4    Number of sprite blocks in the file.
  22       4    Total number of bytes sprite data.
======  ======  ============================================================

Versions 0 to 511 are reserved for the free graphics formats that exist today.


Grouped animation block
-----------------------

Offset  Length  Description
======  ======  ============================================================
   0       2    Block identification 'C', 'A'.
   2       2    Tile size.
   4       4    Number of frames in the animation.
   8       ?    Name of the animation group, 1 byte length prefix containing
                the number of characters in the string.
   ?       4    Reference to the first frame block for 'north' view.
   ?       4    Reference to the first frame block for 'east'  view.
   ?       4    Reference to the first frame block for 'south' view.
   ?       4    Reference to the first frame block for 'west'  view.
======  ======  ============================================================

Each animation in a grouped animation block has the same number of frames.
An animation in one view direction has consecutive frame blocks. For example
if the number of frames is 3, and the first frame in north view is 143, the
second frame is number 144, and the third frame is at 145.

Frame block
-----------

Offset  Length  Description
======  ======  ============================================================
   0       2    Block identification 'F', 'R'.
   2       2    Sound to play (0 means no sound).
   4       2    Number of sprite elements in the frame.
   6     N*12   Sprite elements in the frame.
======  ======  ============================================================

Sprite element
--------------
A sprite element is part of a frame block, and contains a reference to the
actual sprite, and offsets and flags for its frame in the animation.

Offset  Length  Description
======  ======  ============================================================
   0       4    Reference to a sprite block.
   4       2    X offset of the element.
   6       2    Y offset of the element.
   8       1    Display condition (layer class)
   9       1    Display value (layer id)
  10       2    Flags
======  ======  ============================================================

Defined bits in the flags:
- 0x1 flip the image vertically
- 0x2 flip the image horizontally
- 0x4 draw the image with alpha 50%
- 0x8 draw the image with alpha 75%

Sprite block
------------
This is basically the same as a sprite in previous versions, just the header
contains less information. The pixel format supports full color 32bpp, with
image sizes of up to 65534x65534 pixels, allows transparency, and up to 256
recolour layers.

Offset  Length  Description
======  ======  ============================================================
   0       2    Block identification 'S', 'P'
   2       2    Width of the sprite.
   4       2    Height of the sprite.
   6       4    Length of the data of this sprite.
  10       ?    (width * height) pixel data as a continuous stream.
======  ======  ============================================================

The pixel data starts at the top-left pixel, and runs horizontally (and
continues at the left of the next line when reaching the end). This continues
until the last pixel at the bottom-right has been written.

Sequences of pixels with the same characteristics are taken together in blocks
of up to 64 pixels long, and encoded. There are four types of blocks:

1. Fixed fully opaque 32bpp pixels (all the coloured pixels that are always the
   same).
2. Fixed partially transparent 32bpp pixels (glow effects, or 50% transparency).
3. Fixed fully transparent pixels (empty space around the displayed shape to
   make it a rectangular image).
4. Recolour layer (pixels that are retrieved from an RGB table with 256 entries
   that acts like a palette). The data stored in the sprite is just the index
   to use for each pixel. Opacity is the same for the entire block.

   Typically there are tables with ranges of colours, and the sprite contains
   the intensity as the index.


Below is the encoding for each type of pixel block:

1. Fixed fully opaque 32bpp pixels (RGB).
   - 1 byte length (values 0-63)
   - N x 3 byte pixel colours (RGB).

2. Fixed partially transparent 32bpp pixels (RGB).
   - 1 byte length (values 0-63) + 64
   - 1 byte amount of opacity (0-255).
   - N x 3 byte pixel colours (RGB).

3. Fixed fully transparent pixels.
   - 1 byte length (values 0-63) + 128

4. Recolour layer.
   - 1 byte length (values 0-63) + 64 + 128
   - 1 byte layer to apply (0-255).
   - 1 byte amount of opacity (0-255).
   - N bytes table index.

vim: et tw=78 spell