Unreal Tournament Package File Format

by Sapphire

After having recently finished writing a basic JavaScript plugin to parse this file format, I felt a little frustrated at what I considered to be the lack of easily understandable information when I began researching this topic.

Of the few resources out there, I couldn't find any which actually go through an existing package step by step, which I think would have helped me a lot when starting out. As a result, I've decided to write this brief guide in the hope that it may help someone.

As stated, there are a few existing guides, some parts of which I have copied/paraphrased here; the rest I have written myself.

The package used in this example is CTF-Face, aka "Facing Worlds".

Overview

The UT package format has the following structure:

Long int/DWORD data types are signed, 4 bytes long, and stored in little-endian format.

Package Header

The package header always begins at offset 0. If the package version is less than 68, "Heritage" count/offset values may also be present instead of the GUID.

Example

The package header for CTF-Face is shown below. Hover over the table rows to highlight the corresponding bytes within the raw header data.

^*When downloading a package in-game, files are saved using the GUID as their filename. With each of the four long int values read in little-endian format, CTF-Face would be saved as "68722E6411D38195E0006BA2D2321081.uxx".

Name Table

The name table contains all unique object names within the package. The structure is as follows:

Example

As indicated in the package header, the name table for CTF-Face begins at byte 64. The first five values are shown below:

Import Table

The import table contains n entries, where n is the import count specified in byte 28 of the header. Each table entry is structured as follows:

^*See the Compact Index section to understand how values are ascertained from this data type.

^**See Object References.

Example

The first five entries of CTF-Face's import table are as follows:

Export Table

As with the import table, the export table contains n entries, where n is the export count specified in byte 20 of the header. Each table entry is structured as follows:

Example

The first three entries of CTF-Face's export table are as follows:

Package Flags

Packages may have several "flags" or properties, as detailed in the table below. The package flags value for CTF-Face is 0x01 which corresponds to the PKG_AllowDownload flag.

A package's flags can be read by performing a bitwise AND on its flag value with each of the pre-defined flag values. For example, if a package had a package flag of 11 (or 0x0B in hex):

0x0B & 0x01 // 1 - PKG_AllowDownload flag present
0x0B & 0x02 // 2 - PKG_ClientOptional flag present
0x0B & 0x04 // 0 - PKG_ServerSideOnly flag NOT present
0x0B & 0x08 // 1 - PKG_BrokenLinks flag present

The PKG_Unsecure and PKG_Need flags aren't present as their values are greater than 0x0B.

Object Flags

As with the package file itself, objects (i.e. the data contained within the package) can have several flags as well:

Object References

Objects within a package may reference other objects. To differentiate between an object in the export table and the import table, a positive value is given for export entries, and negative for the import. To "convert" a negative value to a usable index, remove the negative sign and subtract 1 (e.g. -5 → 5 → 4). This can be done easily using the bitwise NOT operator.

Example

Part of the decoration in the red base uses a rune texture:

The name of this texture is "runeSgn2", part of the "Deco" group within the texture package SkyCity. This object's package index value is -72, meaning it's index #71 in the import table. This is the Deco object, which in turn has a package index of -2, i.e. the SkyCity object. As SkyCity is its own package (SkyCity.utx), this object has a package index of 0 or NULL, i.e. it has no "parent" package.

Compact Index Format

Tim Sweeney, the format's creator, states Compact indices exist so that small numbers can be stored efficiently.

Rather than storing small numbers in a fixed 4-byte "long int"/DWORD, the compact index format is variable in size, ranging from 1-5 bytes. A comparison highlighting the difference in size is shown below:

Converting a value to a compact index is achieved by using 1-2 bits of each byte to store information about the value, and the remaining bits to store the value itself.

The first byte of a compact index is structured as follows:

Bits 6 and 7 are essentially used as flags:

• when bit 6 is set, the value continues into next byte;
• when bit 7 is set, the value is negative.

All other bytes, if any, are structured as follows:

Example

This example will show how to represent the number -100 as a compact index.

The absolute value, 100, is represented in binary as 01100100. As bits 6 and 7 are required to indicate continuation and the negative sign, the last two bits (0 and 1) have to be moved along to the next byte:

Put back together, the binary value is now 0000000111100100 or 0xE401 in hex, saving two bytes compared to a regular long int value.

Interactive Example

Enter a number below to see the value as represented by the compact index format.

References

1. Unreal Packages by Tim Sweeney, 1999.
2. Unreal Tournament Package File Format, Version 1.6 by Antonio Cordero Balcázar, 2001.
3. Package File Format by Jesco, 2003. Available from http://www.unrealtexture.com/Unreal/Downloads/3DEditing/UnrealEd/Tutorials/unrealwiki-offline/package-file-format.html

Page last updated: 8th March 2020