View source for TOD (Animation Data)

This is an old revision of this page, as edited by RemmyLee at 02:47, 23 October 2026. Publishing it replaces the current version.
← TOD (Animation Data)
You do not have permission to edit this page. Log in to edit.
---
title: TOD (Animation Data)
type: format
summary: Frame-by-frame animation data for 3D objects of the extended graphics library (libgs).
category: File formats
info: Extension = .TOD
info: File ID = 0x50
---

## Overview

The TOD format specifies information along the flow of time for 3D objects, and it corresponds to the extended graphics library (libgs). For each frame of a 3D animation, a TOD file describes the data of the objects that are to be created or modified or erased in that frame. The frames are then arranged in time order, so a TOD file consists of a file header followed by frame data.[^ff240]

## Header

At the top of the TOD file there is a 2-word (64-bit) header, which holds four items. Resolution is the time for which one frame is displayed, and it is counted in ticks of 1/60 second.[^ff240]

Table: TOD file header

| Word | Bits | Field | Contents |
| --- | --- | --- | --- |
| 0 | 0..7 | File ID | Identifies an animation file. The value is 0x50. |
| 0 | 8..15 | Version | Animation version. The value starts at 0x00. |
| 0 | 16..31 | Resolution | Time one frame is displayed, in ticks (1 tick = 1/60 second) |
| 1 | 0..31 | Number of frames | Number of frames in the file |

## Frame

The frames follow the header in time order. Each frame consists of a 2-word frame header followed by its packets:[^ff241]

Table: TOD frame header

| Word | Bits | Field | Contents |
| --- | --- | --- | --- |
| 0 | 0..15 | Frame size | Frame length in words, including the header |
| 0 | 16..31 | Number of packets | Number of packets |
| 1 | 0..31 | Frame number | Frame number |

## Packet

Each packet consists of a one-word packet header followed by packet data. There are several kinds of packets, and the size of the packet data differs between kinds. Even packets of the same kind can have packet data of different sizes.[^ff241]

Table: TOD packet header

| Bits | Field | Contents |
| --- | --- | --- |
| 0..15 | Object ID | The object to be handled |
| 16..19 | Packet type | The type of packet data |
| 20..23 | Flag | Meaning depends on the packet type |
| 24..31 | Packet length | Size of the packet in words (4 bytes), including the header |

The object is a 3D object (a GsDOBJ2 structure) of libgs, and the packet data is applied to that object. The packet type gives the classification of the packet data, and the meaning of the flag therefore varies with the packet type:[^ff242]

Table: Packet type values and packet data contents

| Packet type | Packet data |
| --- | --- |
| 0000 | Attribute |
| 0001 | Coordinate (RST) |
| 0010 | TMD data ID |
| 0011 | Parent object ID |
| 0100 | Matrix value |
| 0101 | TMD data |
| 0110 | Light source |
| 0111 | Camera |
| 1000 | Object control |
| 1001..1101 | User defined |
| 1110 | System reserved |
| 1111 | Special commands |

## Packet Data

### Attribute

When the packet type is 0000, the packet data sets the attribute of the GsDOBJ structure and the flag is not used. The packet data is 2 words. The first word is a mask in which a 0 bit marks an item that changes and a 1 bit marks an item that does not. The second word holds the new data in the bits of the changing items and 0 in the other bits.[^ff243]

The default for unchanged bits is therefore 1 in the first word but 0 in the second. The bits of the second word are as follows:[^ff243][^ff244]

Table: Packet data bit-by-bit breakdown

| Bit | Item | Values |
| --- | --- | --- |
| 0..2 | Material damping | 0 to 3: material damping 0 to 3 |
| 3 | Lighting mode, part 1 | 0 fog off, 1 fog on |
| 4 | Lighting mode, part 2 | 0 material on, 1 material off |
| 5 | Lighting mode, part 3 | 0 use lighting mode, 1 use default lighting mode |
| 6 | Light source | 0 light-source calculation off, 1 forced light-source calculation on |
| 7 | NearZ overflow handling | 0 z overflow clip, 1 z overflow not clip |
| 8 | Back clipping status | 0 valid, 1 invalid |
| 9..27 | Reserved | Initialized at 0 |
| 28..29 | Semi-transparency rate | 00 50% back + 50% polygon, 01 100% back + 100% polygon, 10 100% back - 100% polygon, 11 50% back + 25% polygon |
| 30 | Semi-transparency | 0 off, 1 on |
| 31 | Display | 0 display, 1 no display |

For example, to switch forced light-source calculation on, bit 6 of the first word is 0 and the other bits are 1, so the first word is 0xffbf. Bit 6 of the second word is 1 and the other bits are 0, so the second word is 0x0040.[^ff244]

The rate for value 11 is "50% back + 25% polygon" in this table, while the [TMD](/formats/tmd/) section of the manual gives "100% back + 25% polygon".[^ff244][^ff228]

### Coordinate (RST)

When the packet type is 0001, the packet data sets the coordinates of the GsDOBJ structure. The flag then has the following meaning:[^ff244][^ff245]

Table: Flag when Coordinate (RST)

| Bit | Flag | Values |
| --- | --- | --- |
| 0 | Matrix type | 0 absolute value, 1 differential matrix from the preceding frame |
| 1 | Rotation (R) | 0 none, 1 has |
| 2 | Scaling (S) | 0 none, 1 has |
| 3 | Translation (T) | 0 none, 1 has |

The configuration of the packet data depends on the rotation, scaling and translation bits of the flag. The data holds only the values whose flags are set, in the order R, S, T. Each R value takes one word, Sx and Sy share one word and Sz takes the low half of the next, and each T value takes one word.[^ff245]

Table: RST values

| Values | Contents | Format |
| --- | --- | --- |
| Rx, Ry, Rz | X, Y and Z components of the angle of rotation. One degree is 4096. | Fixed point (1, 19, 12) |
| Sx, Sy, Sz | X, Y and Z components of the scaling | Fixed point (1, 3, 12) |
| Tx, Ty, Tz | X, Y and Z components of the translation | Integer (1, 31, 0) |

### TMD Data ID and Parent Object ID

When the packet type is 0010, the packet data holds the modeling data ID (TMD data ID) of the real object. When the packet type is 0011, it holds the ID of the parent object. Both IDs are 2 bytes, and in both cases the flag is not used.[^ff245][^ff246]

### Matrix Value and TMD Data Body

When the packet type is 0100, the packet data holds the coord members of the GsCOORDINATE2 structure that the GsDOBJ2 structure points to, and the flag is not used. Packet type 0101 holds TMD data. However, this type is not supported at present.[^ff246]

### Light Source

When the packet type is 0110, the packet data sets a light source. In this case the object ID becomes a light source ID that is separate from the normal object IDs. The flag has the following meaning:[^ff246]

Table: Flag when Light Source Packet

| Bit | Flag | Values |
| --- | --- | --- |
| 0 | Data type | 0 absolute value, 1 difference from the preceding frame |
| 1 | Direction | 0 none, 1 has |
| 2 | Color | 0 none, 1 has |

The configuration of the packet data depends on the direction and color bits. The direction takes three words for X, Y and Z, and the color takes one word with B, G and R.[^ff246][^ff247]

### Camera

When the packet type is 0111, the packet data sets the viewpoint, and the object ID becomes a camera ID that is separate from the normal object IDs. Bit 0 of the flag is the camera type. Care is needed because the meaning of the other bits changes with this bit:[^ff247]

Table: Flag for Camera

| Bit | Camera type 0 | Camera type 1 |
| --- | --- | --- |
| 1 | Data type: 0 absolute, 1 difference from the preceding frame | Data type: 0 absolute, 1 difference from the preceding frame |
| 2 | Position and reference position: 0 none, 1 has | Rotation (R): 0 none, 1 has |
| 3 | Reference angle (z angle): 0 none, 1 has | Translation (T): 0 none, 1 has |

With camera type 0, Tx, Ty and Tz are the camera position and TRx, TRy and TRz are the close-up position, and Z is the angle. With camera type 1, Rx, Ry and Rz are the rotation and Tx, Ty and Tz are the translation.[^ff248]

### Object Control

When the packet type is 1000 there is no packet data, and the flag gives the operation:[^ff248]

Table: Flag for Object Control

| Flag | Meaning |
| --- | --- |
| 0 | Create |
| 1 | Kill |
| 0010..1111 | System reserved |

### Extended and Special Commands

Packet type 1110 holds extended commands. Packet type 1111 performs animation control, but the details of these special commands had not been finalized when the manual was published.[^ff248]

## References

[^ff228]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-28, Figure 63.
[^ff240]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-40, Figure 81.
[^ff241]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-41, Figure 82.
[^ff242]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-42, Figures 83 and 84.
[^ff243]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-43, Figure 85 and Table 2-3.
[^ff244]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-44, Figures 86 and 87.
[^ff245]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-45, Figure 88.
[^ff246]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-46, Figures 89 to 92.
[^ff247]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-47, Figures 93 and 94.
[^ff248]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-48, Figures 95 to 97.