Ultima VII Internal Formats

This page documents the Ultima VII engine's internal formats.

Data Types and Structure
Decimal values are given as 123; hexadecimal values are given as 1Fh. All files use little-endian coding. 1122h, for example, is stored as the byte sequence (22h 11h). Signed integers are stored in two's-complement arithmetic. These types are used throughout this document:


 * char - An ASCII character stored as a uint8.
 * uint8/uint16/uint24/uint32 - Unsigned one, two, three, and four-byte integers.
 * int8/int16/int32 - Signed one, two, and four-byte integers.

Files
This section lists the files in an Ultima VII installation and discusses what is known about them. Further details are found in the File Formats section below. "#" means a single digit (0-9); "*" means any number of any character; "?" means any single character.


 * *.exe - Game executables.
 * game##.u7 - Savegame files.
 * static/ - Contains unchanging game data.
 * static/*.adv - Sound device drivers.
 * static/*mus.dat, static/*sfx.dat - Music and sound effects information for the sound device drivers.
 * static/ammo.dat
 * static/armor.dat
 * static/endgame.dat
 * static/endscore.xmi
 * static/endshape.flx
 * static/equip.dat
 * static/faces.vga
 * static/fonts.vga
 * static/gumps.vga
 * static/initgame.dat
 * static/introadm.dat
 * static/intropal.dat
 * static/intrordm.dat
 * static/introsnd.dat
 * static/linkdep# (1 or 2)
 * static/mainshp.flx
 * static/monsters.dat
 * static/npcflag.dat
 * static/occlude.dat - Occlusion bit for world graphics. See the World Shapes section.
 * static/palettes.flx - Main game palettes. See the Palettes section.
 * static/pointers.shp
 * static/ready.dat
 * static/schedule.dat
 * static/shapes.vga - Contains the world graphics, both the ground tiles and the movable shapes. See the World Shapes section below.
 * static/shpdims.dat - Appears to contain dimensions related to shapes; see the World Shapes section.
 * static/sprites.vga
 * static/text.flx
 * static/tfa.dat - Contains flags and data for the world shapes; see the World Shapes section.
 * static/u7chunks - Chunk templates; see the World Data section.
 * static/u7ifix?? (where ?? are hexadecimal digits) - Contains unmovable objects; see the World Data section.
 * static/u7intro.tim
 * static/u7map - Chunk template map; see the World Data section.
 * static/u7speech.spc
 * static/u7strax.drv
 * static/u7voice.flx
 * static/usecode
 * static/weapons.dat
 * static/wgtvol.dat - Contains weight and volume information for shapes; see the World Shapes section.
 * static/wihh.dat
 * static/xform.tbl - Tables for the translucent colours in the palette; see the Palettes section.
 * static/xmidi.ad
 * static/xmidi.mt
 * gamedat/ - Contains temporary data used during the running of a game.
 * gamedat/action.dat
 * gamedat/av_flags.dat
 * gamedat/flaginit
 * gamedat/frames.flg
 * gamedat/gametim?.dat (where ? is a-m)
 * gamedat/identity
 * gamedat/itemnode.dat
 * gamedat/mapcoord.dat
 * gamedat/misstrac.dat
 * gamedat/party
 * gamedat/path.dat
 * gamedat/path0.dat
 * gamedat/randseed.dat
 * gamedat/u7_ostia.dat
 * gamedat/u7ibuf.dat
 * gamedat/u7ireg?? (where ?? are hexadecimal digits)
 * gamedat/u7nbuf.dat
 * gamedat/weather.dat

Common File Formats
This section documents file formats that are shared among many different files.

FLX Archives (.flx extension)
This is an archive file used extensively throughout the game. Each record has the same type, which depends upon the file itself.

Shapes (.shp files and others)
This describes a graphics image. It is composed of a set of frames, with this header:

The total width and height of a frame are (MaxX + OffsetX + 1) and (MaxY + OffsetY + 1) respectively. Here is pseudocode for decoding the RLE data:

while(true) { int BlockData = ReadUInt16; int BlockLength = BlockData >> 1; int BlockType = BlockData & 1;

if(BlockData == 0) break; int OffsetX = ReadInt16; int OffsetY = ReadInt16;

if(BlockType == 0) ReadImage(OffsetX, OffsetY, BlockLength); else { int EndX = OffsetX + BlockLength;

while(OffsetX < EndX) { int RunData = ReadUInt8; int RunLength = RunData >> 1; int RunType = RunData & 1;

if(RunType == 0) ReadImage(OffsetX, OffsetY, RunLength); else { var Value = ReadUInt8; ReadImageRun(OffsetX, OffsetY, RunLength, Value); }

OffsetX += RunLength; }   } }

ShapeFrameIndex
This refers to both a shape indexing the archive from the World Shapes section, and a frame within them.

File Formats
This section documents the file formats for specific files.

World Shapes (static/shapes.vga, static/shpdims.dat, static/wgtvol.dat, static/occlude.dat)
The world shapes describe the graphics and information about all the objects in the world, excluding some special effects.

"static/shapes.vga" contains the graphical data. "static/shpdims.dat" includes data that are not well understood. "static/wgtvol.dat" includes weight and volume information. "static/tfa.dat" contains flags and type information about shapes.

Graphics Archive (static/shapes.vga)
This FLX archive file contains the world graphics. From index 0 to 149/95h (inclusive) it contains 8x8 tiles used for the ground, up to 32 per record. From index 150/96h and up it contains Shape records, documented above.

Dimensions (static/shpdims.dat)
This contains dimensional data for shapes (only shapes index 150/96h and up). It contains a set of (uint8 Vertical, uint8 Horizontal), with this bit format:

This file is extremely poorly understood. None of its attributes make particular sense.

Shape Weight/Volume (static/wgtvol.dat)
This contains weight and volume data for all shapes. It contains a set of (uint8 Weight, uint8 Volume), where Weight is in units of 0.1 stone.

Shape Flags (static/tfa.dat)
This contains types and flags information for all shapes. It contains a set of (uint24 Bitfield), described below:

These are the shape type values:

Shape Occlusion Bit (static/occlude.dat)
This file contains a bit that can be used to solve some bugs in object sorting. There is one bit for each world shape in ascending order (so the first shape is mask 1, the second shape is mask 2, and so on). This seems to largely be set for walls and ceilings.

Palettes (static/palettes.flx, static/xform.tbl)
This {{#aFlxArchive|FLX archive]] file contains the palettes used throughout the game. Each palette has the format (Color[256] Colors), where Color is (uint8 Red, uint8 Green, uint8 Blue), and each component is between 0 and 63. There are 12 palettes in use. Color 255 is transparent.

Translucency FLX Archive (static/xform.tbl)
For world palettes, colours 244/F4h to 254/FEh inclusive are special transparent colours that are used when the Translucent flag is set on a world shape's property. The FLX archive "static/xform.tbl" contains tables to transform an underlying colour into a new colour if the colour being drawn is one of those set. Each entry is (uint8[256] OutputIndices). The table is in reverse order; index 0 is for colour 254, index 1 is for colour 253, and so on.

The equations producing the mapping table are far more complex than simple transparency, and trying to replicate them is made more difficult by the limited palette of colours they had to map to. This table shows the closest matching colours that would produce the same effect that use simple transparency. Each colour value is from 0 (darkest/transparent) to 1 (brightest/opaque).

World Data (static/u7chunks, static/u7map)
World data are separated into three sections: ground, fixed objects, and regular objects.

The ground tiles are a series of 8x8 pixel tiles that constitute the floor. Those are grouped into 16x16 chunks, along with static geometry. These template Chunks are referenced by 16x16 Regions, and there are 12x12 Regions in the world map.

Chunk Templates (static/u7chunks)
This file contains a list of chunk templates that are then indexed by the regions.

A shape index refers to both tiles and shapes. The shape should be inserted into the world as static geometry at zero height.

Static Chunk Data (static/u7map)
This file contains the chunks for the static map. The map is partitioned into (Region[12 * 12] Regions) (in [x + y * 12] order), where Region is (uint16[16 * 16] Chunks), where each value is an index into "static/u7chunks" described above.

Fixed Items Data (static/u7ifix??)
These files contain the fixed objects for the region. They are named as u7ifixXX, where XX is a hexadecimal number that is (RegionX + RegionY * 12).

Within the FLX Archive files are 16*16 records for each chunk in the region in [ChunkX + ChunkY * 16] order. If an entry is empty, it contains no fixed objects. Otherwise it contains a list of (uint16 Bitfield, ShapeFrameIndex ShapeFrame), where the bitfield described below: