TR4 file format

Contributors: Rgbold, Turbo Pascal, Yuri Zhivago, Dr. Willard, TRWad, Popov, others ?

This document describes only differences between TR3 and TR4 file format. Please, refer to the TRosetta Stone document to get informations about TR1 / TR2 and TR3 file format.
This document is not complete, there are yet some unknowns. Feel free to fill in the blanks and let us know that we can modify this document.

Types used
General format of a .TR4 file
Format of the geometry block

Room Lights
Tri & Quad polys in mesh objects
Flyby cameras
Cinematic frames replaced by AI data
Changes in tr2_sprite_texture
Mesh objects
Object textures
Animations
Miscellaneous

Types used

name	size
bit8	a signed 8 bits
bitu8	an unsigned 8 bits
bit16	a signed 16 bits
bitu16	an unsigned 16 bits
bit32	a signed 32 bits
bitu32	an unsigned 32 bits
float	a 4 bytes float

Other types can be used: if it's the case, refer to the TRosetta Stone document to have their definitions (for eg: tr2_color)

General format of a .TR4 file

bitu32	"TR4",0
bitu16	Number of non bumped room tiles
bitu16	Number of tiles for objects
bitu16	Number of bumped room tiles
bitu32	Uncompressed size of texture 1
bitu32	Compressed size of texture 1
bitu8[]	(compressed) Texture 1 (32 bits texture)
bitu32	Uncompressed size of texture 2
bitu32	Compressed size of texture 2
bitu8[]	(compressed) Texture 2 (16 bits texture)
bitu32	Uncompressed size of texture 3
bitu32	Compressed size of texture 3
bitu8[]	(compressed) Texture 3 (32 bits texture)	-> a 256x512 texture with the font & sky
bitu32	Uncompressed size of geometry
bitu32	Compressed size of geometry
bitu8[]	(compressed) Geometry
bitu32	num_sounds
*num_sounds struct TR4_TrailingSound**
{
bitu32	UncompSize;	// Uncompressed sound size
bitu32	CompSize;	// Compressed sound size -> compression is ADPCM (WAV format)
bitu8	sound_data[];	// data of the sound - size is CompSize bitu8
}

Notes

the compression used is the zlib one
sounds have a Riff wave format
for the level to be played correctly with the TRLE engine, sounds must not be compressed. In addition, they must be at 22.05 Khz / 16 bits per sample / mono (at least, this format works !)

Format of the geometry block

-> same structures than in TR3 format, except:

Room Lights

// Follows a D3D light structure, I think, could be wrong (46 bytes)
typedef struct
{
bit32	Xposition;	// world coords
bit32	Yposition;	// world coords
bit32	Zposition;	// world coords
tr2_colour	Color;	// three bytes rgb values
bitu8	LightType;	// same as D3D (i.e. 2 is for spotlight)
bitu8	unknown;	// always 0xff?
bitu8	Intensity;
float	In;
float	Out;
float	Length;
float	Cutoff;
float	X,Y,Z;	// direction??
} tr4_room_light;

Tri & Quad polys in mesh objects

// Triangle surface (10 bytes)
typedef struct
{
bitu16	Vertices[3];	// The 3 vertices of a tri
bitu16	Texture;	// Object-texture index
bitu16	Lighting;	// transparency flag & strength of the hilight
} tr4_face3;

// Quadrangle surface (12 bytes)
typedef struct
{
bitu16	Vertices[4];	// The 4 vertices of a quad
bitu16	Texture;	// Object-texture index
bitu16	Lighting;	// transparency flag & strength of the hilight
} tr4_face4;

The new field Lighting has this layout:

Bit 0	if set, alpha channel = intensity (same meaning that when the Attribute field of tr2_object_texture is 2. Cf TRosetta stone document)
Bits 1->7	strength of the hilight. In TR4, objects can exhibit some kind of light reflection when seen from some particular angles. These bits give the strength of this effect: the more bigger the value is, the more visible is the effect.

Notes

As in TR3, the Texture field can have its bit 15 set -> only for tris & quads used by rooms - unknown meaning
The extra field Lighting exists only for tris / quads making meshes (used by moveables and static meshes), not for tris / quads making rooms !

Flyby cameras

Before SoundSources (cf. TRosetta stone document) is a new field for Flyby_Camera data:

bitu32	Number_of_FBCameras;
// Data for a flyby camera (40 bytes)
typedef struct
{
bit32	pos[6];	// Positions ? (x1,y1,z1,x2,y2,z2)
bitu8	index[2];	// A pair of indices
bitu16	Unknown[5];	// ??
bit32	ID;	// Index of something
} tr4_extra_camera;

Cinematic frames replaced by AI data

There are no cinematic frames in TR4. Instead of that, there is the following structure:

bitu32	num_AIData;	// this field replaces the bitu16 NumCinematicFrames of TR1/2/3 levels
// Data for a AI object (24 bytes)
typedef struct
{
bitu16	ObjectID;	// the objectID from the AI object (AI_FOLLOW is 402)
bitu16	Room;
bit32	X,Y,A;
bitu16	OCB;
bitu16	Flags;	// The trigger flags (button 1-5, first button has value 2)
bit32	Angle;	// rotation
} tr4_AI_object;

Changes in tr2_sprite_texture

This structure has the same size than before but some of its fields have changed of meaning:

// Data for a sprite (16 bytes)
typedef struct
{
bitu16	Tile;
bitu8	unknown1;	// ??
bitu8	unknown2;	// ??
bit16	Width;	// = (real_width-1) * 256
bit16	Height;	// = (real_height-1) * 256
bit16	x1,y1;	// top-left corner of the texture
bit16	x2,y2;	// bottom-right corner of the texture
} tr4_sprite_texture;

In addition, the NumSpriteTextures field (see TRosetta stone) is preceeded by the 3 ASCII bytes 'SPR'

Mesh objects

Meshes have no longer colored tris / quads. So, NumColoredRectangles, ColoredRectangles[], NumColoredTriangles, ColoredTriangles[] no longer exist in the tr2_mesh structure (cf. TRosetta stone document for the tr2_mesh_structure).

Object textures

The NumObjectTextures field (see TRosetta stone) is now preceeded by \0TEX (4 bytes -> \0 is the bitu8 value 0). The structure tr2_object_texture itself has changed:

// Data for an object texture (38 bytes vice 20 in TR1/2/3)
typedef struct
{
bitu16	Attribute;	// same meaning than in TR3
bitu16	Tile;	// same meaning than in TR3
bitu16	Flags;	// new in TR4
tr2_object_texture_vert	Vertices[4];	// same meaning than in TR3
bitu32	Unknown1,Unknown2;	// new in TR4: x & y offset in something ?
bitu32	XSize,YSize;	// new in TR4: width-1 & height-1 of the object texture
} tr4_object_texture;

Meaning of Flags:

Bits 0->2	mapping correction. It seems that these bits change the way the texture is applied...
Bit 11->12	2 bits giving the bump mapping type. Can be 0x01 or 0x10. It's 0x00 if not bump mapped. Only textures for room or animated textures can be bump mapped, not meshes
Bit 15	if set, the texture is for a tri/quad from a room or animated texture. If not set, the texture is for a mesh

Notes

rgbold said that the Attribute field could have a value of "2" for 2-sided textures, but it seems wrong: this field has not changed in TR4 and the value "2" seems to mean alpha=intensity as in TR3
Unknown1 and Unknown2 are said as beeing "XOffset and YOffset" by Dr.Willard, but it seems that changing these values do nothing... In addition, they seem not related to a second texturing as thought by Dr.Willard
Tile is really bits 0 through 14: bit 15 is a flag which says, if set, that this object texture is for a triangle. If not set, the object texture is for a quad.
In the texture coords now 0 is used for low value vice 1 (see the Xcoordinate and Ycoordinate fields of the tr2_object_texture_vert structure in the TRosetta Stone document)

Animations

The tr2_animation structure has changed a little:

// Data for an animation structure (40 bytes vice 32 in TR1/2/3)
typedef struct
{
bitu32	dwFrameOffset;	// same meaning than in TR3
bitu8	bFrameRate;	// same meaning than in TR3
bitu8	bFrameSize;	// same meaning than in TR3
bitu16	wStateId;	// same meaning than in TR3
bit16	Unknown;	// same meaning than in TR3
bit16	sSpeed;	// same meaning than in TR3
bitu16	wAccelLo;	// same meaning than in TR3
bit16	sAccelHi;	// same meaning than in TR3
bitu8	Unknown2[8];	// new in TR4
bitu16	wFrameStart;	// same meaning than in TR3
bitu16	wFrameEnd;	// same meaning than in TR3
bitu16	wNextAnimation;	// same meaning than in TR3
bitu16	wNextFrame;	// same meaning than in TR3
bitu16	wNumStateChanges;	// same meaning than in TR3
bitu16	wStateChangeOffset;	// same meaning than in TR3
bitu16	wNumAnimCommands;	// same meaning than in TR3
bitu16	wAnimCommand;	// same meaning than in TR3
} tr4_animation;

Notes

The Unknown2[8] are not always 0 as thought by rgbold. When non zero, it seems that these bytes have the same sort of values than the existing (Unknown, sSpeed, wAccelLo, sAccelHi) fields (which count 8 bytes too). So these 8 unknowns could be (Unknown2,sSpeed2,wAccelLo2, sAccelHi2) fields...
The wNumAnimCommands field can have wrong values (0xaaaa or 0xaaa7 for eg): don't know why, but if > 256, you could consider it to be 0 (that's what is done in TrViewer, but the real value is recorded to be use later when the level is saved: maybe the TR Engine needs this value...)
Angles in animation frames have changed: in the single axe rotation case, you must multiply by 360/4096 instead of 360/1024 to get the angle in degrees (see the TRosetta Stone document for more informations about animation frames)

Miscellaneous

There are no 8bit or 16 bit palettes
There is no lightmap
There are no 8 bits textures
TR4 levels have an additional 6 bytes at the end of the uncompressed geometry block that seem to be always 0