IFP

From GTAMods Wiki
Revision as of 14:07, 15 September 2010 by Aschratt (talk | contribs)
Jump to navigation Jump to search

IFP is the animation format of the Grand Theft Auto series since GTA III. With GTA San Andreas there came a new version of the file format but it still supports animations of the old version. IFP files can contain several single animations which are split up to objects and linked to the animated object or actor in that way. Each object contains a certain number of frames including a time key. Two frames are interpolated by the game.

File Specification

Animation packages are building a simple hierarchy which is constant over all versions. Basicly each animation file consists of an header storing general file information. This header is followed by the animations themselves. In this way one animation file stores animations just like archive files holds different data as a flat list.

Each animation consists of multiple objects representing a bone of the model the animation gets linked to. Each object holds a list of frames. Those define information about the mathmatical description of the object in the world like translation, scaling and rotation.

The following structure shows an abstract animation tree:

IFP File
 |
 +-- Animation
 |    |
 |    +-- Object
 |    |    |
 |    |    +-- Frame
 |    |    +-- Frame
 |    |    +-- ...
 |    |
 |    +-- Object
 |    |    |
 |    |    +-- Frame
 |    |    +-- Frame
 |    |    +-- ...
 |    |
 |    +-- ...
 |
 +-- Animation
 |    |
 |    +-- ...
 |
 +-- ...

This tree is just an indirect result of the simple structure hierarchy of version 1 but parsers may use it for both versions.

Data types

By default animation packages are using the following data types:

  • CHAR - ASCII encrypted character (1 byte)
  • INT32/UINT32 - signed/unsigned 32 bit integer (4 byte)
  • FLOAT - single precision floating point number (4 byte)
  • TVector3 - FLOAT[3] (12 byte)
  • TVector4 - FLOAT[4] (16 byte)

Version 1

Strings

Offsets are always relative to the current file position. To convert a relative offset to an absolute one just add the number of read bytes. Strings are always padded to 4 byte bounds. The "AnimNameLength" string after the "NAME" information marker describes the string including the terminating zero-byte. You have to round up this value until the number is able to be divided by 4 without any rest, to get the number of bytes you have to write.

Data structures

Version 1 packages are introducing some additional data structures. Those are always indicated by an 4 byte constant length string. The following table lists the different data structures and their formats. All data structures are inherting from an abstract base data structure. This base data structure must not be used inside the file (also this would not make sense since it does not hold any data except information about identifying itself). The whole file follows this rules so animation package itself can be seen as one section.

Structure and descriptionSpecification
BASE
Abstract base section.
(8 byte)
identifier  : CHAR[4]
offset      : UINT              // offset to the end of the section
ANPK
Major section of the file.
information : INFO<TAnimation>  // section information data (see below)
INFO<T>
Collection of multiple sub sections of type T.
entries     : INT32             // (count of encapsuled sections)
name        : TString           // (name of the collection)
sections    : T[entries]        // Subsections
NAME
Holds an string.
name        : TString
DGAN
Holds data for TAnimation.
anim. info  : INFO<CPAN>
CPAN
Holds data for animation objects.
object info : ANIM
ANIM
Holds data for animation frames.
object name : TString           // Also the name of the bone
frames      : INT32             // Number of frames
unknown     : INT32             // Usually 0
next        : INT32             // Next sibling
prev        : INT32             // Previous sibling
frame data  : KFRM
KFRM
'Abstract' section inherting from BASE and representing a frame type.
There are 3 known specialisations of this base structure: KR00, KRT0 and KRTS.
time key    : FLOAT             // This value is the last one of the specialised sections.
KR00
Inherting from KFRM and defines an collection of rotated frames.
(Offset - 4) / 16 = X
rot         : TVector4[X]       // Rotation as quaternion
KRT0
Inherting from KFRM and defines an collection of rotated and translated frames.
(Offset - 4) / 28 = X
{
  rot       : TVector4          // Rotation as quaternion
  pos       : TVector3          // Translation
}[X]                            // Repeated X times.
KRTS
Inherting from KFRM and defines an collection of rotated, translated and scaled frames.
(Offset - 4) / 40 = X
{
  rot       : TVector4          // Rotation as quaternion
  pos       : TVector3          // Translation
  scale     : TVector3          // Scale
}[X]                            // Repeated X times.

Note: The sections are listed in the order they appear inside the file for better understanding.

Animation

The data structures descriped above can be used to define the data structure for animations. Note that TAnimation does not inherit from BASE. Offset information are stored inside the encapsuled animation data.

Structure and descriptionSpecification
TAnimation
An animation entry of the package.
(8 byte)
anim. name  : NAME
anim. data  : DGAN

Exact version 1 hierarchy

The following tree shows an basic hierarchy of an version 1 animation file:

ANPK
|
+-- INFO<TAnimation>
     |
     +-- NAME/DGAN
     |         |
     |         +-- INFO<CPAN>
     |         |    |
     |         |    +-- ANIM
     |         |    +-- ANIM
     |         |    +-- ...
     |         |
     |         +-- ...
     |
     +-- ...


Version 2

Version 2 archives got basically the same hierarchy as above, but the structures are a bit different. In version 2 all strings are null-terminated, but they got a constant size of 24 bytes.

Header

4b   - FourCC   - 'ANP3' (Animation Package 3, Version identifier. However there is no pack with ANP2)
4b   - Int32    - Offset to end of file
24b  - Char[24] - internal file name used in the script
4b   - Int32    - Number of Animations

Animation

24b  - Char[24] - Animation Name
4b   - Int32    - Number of Objects
4b   - Int32    - Size of frame data
4b   - Int32    - Unknown, always 1

The size of data value is a number of bytes which corresponds to the exact size of the frame's usable data, including the compressed coordinates and rotation info.

Object

24b  - Char[24] - Object Name
4b   - Int32    - Frame type: Child = 3, Root = 4
4b   - Int32    - Number of Frames
4b   - Int32    - Bone ID

Frame

Root frames usually follow the following structure:

2b   - Int16    - Quaternion X
2b   - Int16    - Quaternion Y
2b   - Int16    - Quaternion Z
2b   - Int16    - Quaternion W
2b   - Int16    - Time (in seconds)
2b   - Int16    - Translation X
2b   - Int16    - Translation Y
2b   - Int16    - Translation Z

Child sections normally have no translation values:

2b   - Int16    - Quaternion X
2b   - Int16    - Quaternion Y
2b   - Int16    - Quaternion Z
2b   - Int16    - Quaternion W
2b   - Int16    - Time (in seconds)

To convert quaternion and translation values to floating values divide them by 4096.

External links