Redguard Preservation — Documentation

Documented findings from reverse-engineering The Elder Scrolls Adventures: Redguard (1998) — file formats, engine behavior, and undocumented features. Analysis is primarily based on the GOG release (Glide renderer), with original-CD differences noted where known.

GOG Version Contents

Main Files

Asset Directories

GOG vs Original CD Differences

Redguard shipped with two parallel sets of 3D model assets for different renderers:

The two directories contain the same models re-exported for different renderers. The Glide versions (v4.0/v5.0) have a cleaner header layout and different texture encoding. See 3D — v2.6/v2.7 Header Differences for details.

Note: The GOG distribution contains fxart/ only. The software-renderer 3dart/ directory shipped on the original CD but is not present in the GOG release.

File Formats Overview

Binary, little-endian file formats.

3D Model File Format

Binary, little-endian static (single-frame) model format.

.3D files are static (single-frame) models. For the animated multi-frame variant, see 3DC.md.

Versions

Four versions exist: v2.6, v2.7, v4.0, v5.0. See GOG vs Original CD Differences for which directories contain which versions.

• v2.6 / v2.7 — Different header semantics and face data encoding from v4.0/v5.0.
• v5.0 — Adds Section4 (SubObject BVH).

Header (64 bytes)

v2.6/v2.7 Header Differences

The header is the same 64 bytes, but many fields have different semantics:

v2.6/v2.7 Frame Data Differences

The 16-byte frame data record has different field semantics:

v2.6/v2.7 Face Data Differences

Parsers must remap header fields before use. See External References for the remap logic.

Engine version gate: The shipped engine rejects files where the version byte (offset 0x01) is less than ASCII '4' (0x34). This means v2.6/v2.7 .3DC files on the game disc are not loaded at runtime — they are development-era leftovers. The engine only loads v4.0+ files. External parsers (DaveHumphrey, RGUnity, this project) support both versions for preservation completeness.

Section Layout

Sections appear in this order (offsets from header):

1. Face Data — at 0x40, num_faces variable-size records
2. Vertex Coordinates — num_vertices × 12 bytes
3. Face Normals — num_faces × 12 bytes
4. Frame Data — num_frames × 16-byte records
5. Section4 — SubObject BVH entries (when present)
6. Vertex-Normal Indirection Table — total_face_vertices × u32
7. Vertex Normals — num_vertices × 12 bytes

Frame Data

Located at offset_frame_data. Array of num_frames × 16-byte records.

For .3D files this is always a single entry pointing to the base geometry.

vertex_offset and normal_offset point to the base vertex coordinate and face normal sections (same values as header fields 0x30 and 0x34).

Face Data

Located at offset_face_data (always 0x40). Array of num_faces variable-size records.

v4.0 / v5.0 Face Record

Texture Decoding (v4.0 / v5.0)

Solid color (if texture_data_raw >> 20 == 0x0FFF):

• color_index = (texture_data_raw >> 8) & 0xFF
• tex_hi is always 0xFF for solid-color faces.

Textured (otherwise):

• Texture file ID (BCD-like encoding):

  tmp = (texture_data_raw >> 8) - 4000000
  ones     = (tmp / 250) % 40
  tens     = ((tmp - ones*250) / 1000) % 100
  hundreds = (tmp - ones*250 - tens*1000) / 4000
  texture_id = ones + tens + hundreds
  

  This yields the TEXBSI.### file number.

• Image sub-ID within that TEXBSI file:

  ones = (texture_data_raw & 0xFF) % 10
  tens = ((texture_data_raw & 0xFF) / 40) * 10
  image_id = ones + tens
  

v2.6 / v2.7 Face Record

Texture decode from texture_data (the u16 at offset 0x02):

• Solid color if (texture_data >> 7) < 2: color_index = texture_data & 0xFF
• Textured: texture_id = texture_data >> 7, image_id = texture_data & 0x7F

FaceVertex

UV coordinates are cumulative deltas in 4-bit fixed-point format: each vertex’s absolute U/V = previous vertex’s U/V + this delta. First vertex in the face starts from 0.

The raw i16 values are in 1/16th pixel precision. To convert to pixel-space texture coordinates, multiply by 1/16 (or divide by 16). To normalize to 0–1 UV range, divide by 16 × texture_width (U) and 16 × texture_height (V). This fixed-point scale applies identically to first-vertex values and subsequent deltas.

Face Vertex Count Distribution

Vertex Coordinates

Located at offset_vertex_coords. Array of num_vertices × 12 bytes.

Each vertex is 3 × i32 (signed 32-bit integers), scaled by 1/256.0 to get world-space coordinates.

Face Normals

Located at offset_face_normals. Array of num_faces × 12 bytes.

Each normal is 3 × i32, scaled by 1/256.0. Per-face normals (one per face, not per vertex).

Vertex Normals

Located at offset_vertex_normals (header offset 0x2C). Array of num_vertices × 12 bytes.

Each entry is 3 × f32 (IEEE 754 single-precision). Per-vertex normals (unit vectors). Some entries may be NaN (bit pattern 0xFFC00000 for all three components), indicating no normal was computed for that vertex.

Vertex-Normal Indirection Table

Located at offset_normal_indices (header offset 0x28). Array of total_face_vertices × u32.

Each entry is a file offset pointing into the vertex-normal data section. Maps each face-vertex to its vertex normal, allowing faces that share a vertex to use different normals (for hard edges).

Shading Model Selection

Per-vertex shading is determined by the indirection table and vertex normal validity:

.3D files typically have the indirection table (per-face-vertex normal control). .3DC files always omit it (offset_normal_indices = 0) and fall back to direct vertex-index lookup.

Section4: SubObject BVH

Located at offset_section4 (header offset 0x1C). Contains section4_count variable-size entries. Present when offset and count are non-zero.

Each entry is a bounding-volume node with face references:

External References

• UESP: Mod:Model Files — community-maintained model-format notes and version behavior.
• uesp/redguard-3dfiletest Redguard3dFile.cpp — DaveHumphrey’s C++ parser, including v2.6/v2.7 header remap logic (ConvertHeader27).
• RGUnity/redguard-unity RG3DFile.cs — production parser implementation used by the Unity reimplementation (cross-check for face/texture decoding behavior).

3DC Animated Model File Format

Animated variant of the 3D model format. Same binary layout — identical header and section structure — but with multiple animation frames.

Differences from .3D

All shared structures (header, face data, vertex coordinates, face normals, vertex normals, texture encoding) are documented in 3D.md.

Animation Frame Data

The frame data array at offset_frame_data contains num_frames × 16-byte records (see 3D.md — Frame Data for the record layout).

Frame 0 always points to the base geometry (same as .3D files). Frames 1+ contain per-frame vertex positions and face normals in a compact encoding determined by frame_type:

frame_type Values

frame_type is only meaningful in frame 0’s record. Frame 1+ records always have frame_type = 0.

10-10-10-2 Packed Normal Format

Used for face normals in frames 1+:

Bits  0- 9: nx (10-bit signed, subtract 1024 if >= 512)
Bits 10-19: ny (10-bit signed, subtract 1024 if >= 512)
Bits 20-29: nz (10-bit signed, subtract 1024 if >= 512)
Bits 30-31: unused (values: 0 and 3)

Each component is divided by 256.0 to produce the final normal vector.

The engine’s normal decoder extracts the three 10-bit signed components via sign-extending shifts and discards bits 30–31:

nx = (float)((packed << 22) >> 22) * scale;   // bits  0–9, sign-extended
ny = (float)((packed << 12) >> 22) * scale;   // bits 10–19, sign-extended
nz = (float)((packed <<  2) >> 22) * scale;   // bits 20–29, sign-extended
// bits 30–31 are shifted out by << 2 — never read

The values (0 and 3) are likely packing artifacts — 3 (0b11) can result from sign extension during the build tool’s encoding step. Parsers should mask or discard these bits.

Section Layout

Same as 3D.md — Section Layout, but with animated frame data inserted and .3D-only sections absent:

1. Face Data — at 0x40
2. Vertex Coordinates — base frame positions
3. Face Normals — base frame normals
4. Frame Data — num_frames × 16-byte records
5. Animated Frame Vertex/Normal Data — frames 1+ geometry
6. Vertex Normals — per-vertex normals (f32 × 3)

External References

• UESP: Mod:Model Files — baseline notes for shared .3D/.3DC structures and version differences.
• RGUnity/redguard-unity RG3DFile.cs — practical reference for animated-frame decoding paths used in a full game implementation.

ROB File Format

Binary container format. Holds multiple 3D model segments — either embedded inline or as references to external .3DC files.

ROB stores model geometry buckets, not per-instance scene placement transforms. World/object placement comes from scene files (RGM), which reference these models.

Overall Structure

[Header — 20 bytes]
[Segment 0 — 80-byte header + data]
[Segment 1 — 80-byte header + data]
...
[Segment N-1]
[Footer — 4 bytes: "END "]

Some fields use big-endian encoding (a remnant of the original Sega Saturn development), while most use little-endian. Endianness is noted per field.

Header (20 bytes)

Segment Header (80 bytes)

Each segment has a fixed 80-byte header followed by data_size bytes of payload.

Bounding Box Invariant

bbox_extent == bbox_positive + bbox_negative for all three axes.

For symmetric models: bbox_positive == bbox_negative (center at origin). For asymmetric models, the difference encodes the center offset.

Segment Types

Segment Flags (0x0E)

The engine reads only the high byte (file offset 0x0F) of this u16 field. The low byte is always 0x00 and is ignored. The high byte is stored as a render mode selector in the model’s internal data — a value of 0 defaults to 0xFF (standard rendering).

Segment Attributes (0x10)

A single byte of per-segment attribute flags.

Segment Data

For segment_type == 0 (embedded): the data payload is a complete 3D model file starting with its own 64-byte header. Parse with the standard 3D parser.

For segment_type == 256 (menu-specific embedded): same as type 0 — payload is a complete 3D model file. Parse identically. See MENU.ROB Segments below.

For segment_type == 512 (external reference): no data payload. Load the referenced .3DC file from the asset directory using name as the filename stem. External references are exclusively .3DC (animated models) — static .3D geometry is always embedded inline as type 0 segments, never referenced externally.

MENU.ROB Segments

MENU.ROB is the only ROB file containing type 256 segments. It holds 3D models used for the game’s menu screens.

Version v4.02 appears only in these three MB_PG segments — it is not found in any other ROB file or standalone 3D/3DC file.

Footer

4-byte ASCII marker: "END " (with trailing space). Always present.

External References

• UESP: Mod:ROB File Format — high-level ROB structure and historical notes.
• RGUnity/redguard-unity RGROBFile.cs — segment parsing behavior in a working loader.

RGM Scene File Format

Scene/map container with sectioned records for placed objects, script metadata, and auxiliary world data. The RA*-prefixed sections (RASC, RAHD, RAAT, RAHK, etc.) form the per-map SOUP scripting layer — see SOUP Scripting for a consolidated map of all script data sources and runtime boundaries.

Section Framing

Each section starts with an 8-byte header. Some sections then include a 4-byte little-endian record_count word at the beginning of section data.

For count-prefixed sections (MPOB, MPSO, MPRP, and several others), section payload begins with:

Little-endian.

Sections are parsed sequentially until END .

MPOB (Object Instances)

MPOB starts with a little-endian object count, followed by 66-byte records.

All fields little-endian.

Position decode used by current exporter:

• scale constant: 1 / 5120
• x = -(pos_x * 256) * scale
• y = -(pos_y * 256) * scale
• z = -(0x00FF_FFFF - (pos_z * 256)) * scale

Bethesda 2048-unit Euler angles:

2048 discrete units represent a full 360° rotation — a power-of-two binary angle encoding. The raw u32 is reduced modulo 2048 (equivalently masked with & 0x7FF), giving a value in the range [0, 2047]. Each unit equals 180/1024 ≈ 0.176°.

degrees = (value % 2048) * (180.0 / 1024.0)

MPOB model lookup behavior:

• Primary source is model_name (9 bytes, null-trimmed).
• If model_name is empty, exporter falls back to RAAN using RAHD script metadata (see RAAN).
• If RAAN also yields no result, script_name is used as a last resort.
• Example: script_name = FAVIS resolves via RAAN to FVPRA001.

MPSO uses a 12-byte model_name field (no fallback chain — model name is always present).

MPSO (Static Objects)

MPSO starts with a little-endian object count, followed by 66-byte records.

All fields little-endian.

The exporter converts rotation_matrix from Q4.28 to float and emits a node matrix with translation.

Rotation parity note:

• MPSO rotation_matrix must be interpreted with transposed index mapping when building the scene rotation matrix:
  • row 0 = [m0, m3, m6]
  • row 1 = [m1, m4, m7]
  • row 2 = [m2, m5, m8]
• Earlier row-major mapping ([m0,m1,m2], [m3,m4,m5], [m6,m7,m8]) produced incorrect static-object orientation for cases like TV_SEAT and BT_BOARD.

MPRP (Rope Chains)

MPRP starts with a little-endian record count, followed by 80-byte records.

All fields little-endian.

Rope instancing behavior:

• Decode base translation with the same MPOB scale/sign rules.
• Spawn length copies of rope_model.
• For each link: subtract 0.8 from Y and place one instance.
• If static_model is present, place one additional instance after the chain.

Current parser behavior: MPRP is parsed into typed 80-byte records only when section payload is an exact fit for record_count; otherwise raw fallback is kept.

RALC (Location Data)

RALC contains scripted coordinate offsets for objects (e.g. the Boatman’s waypoints). Records are 12-byte entries.

All fields little-endian.

Offsets are applied to the object’s base MPOB position (pos × 256) by script commands MoveToLocation and WanderToLocation. Per-object RALC entry counts and offsets are stored in the corresponding RAHD record.

RAVC (VCollide)

RAVC uses 9-byte entries and appears only in a subset of maps (CATACOMB and DRINT — collision data for the dragon and golem).

All fields little-endian.

Current parser behavior: records are parsed as fixed 9-byte entries only when section payload is an exact fit; otherwise raw fallback is kept. RAVC is flat-out missing (not just empty) in RGM files without collision objects.

WDNM (Walk Node Map)

WDNM defines walk node maps for AI pathfinding. Count-prefixed: record count is the number of walk-map blocks.

All fields little-endian.

WalkMap Record

WalkNode Record

NodeRoute Record (4 bytes)

RAHD (Actor Header)

RAHD is a count-prefixed section with 165-byte records. Each record provides per-actor metadata: script name, bytecode location in RASC, string/variable table pointers, animation references, collision data, and attribute hooks.

Section payload starts with a 4-byte LE record count, followed by 4 fixed bytes (1B 80 37 00), then count × 165 bytes of records. The engine reads the count and prefix separately, then bulk-reads count × 165 bytes as the record array. Offsets below are within each 165-byte record (starting at payload offset 8 + i × 165). The Rust parser in this repo starts records 4 bytes earlier (at 4 + i × 165) and adds 4 to all field offsets.

At load time, the engine converts most offset fields into absolute pointers by adding the corresponding section’s data pointer (rebasing). Offset 0x00 is overwritten with a linked-list next-pointer at runtime.

All typed fields are little-endian.

Total record size: 165 bytes (0xA5).

RAAN (Animation File References)

RAAN contains animation/model file path entries. Records are variable-length null-terminated strings with a 6-byte prefix.

Entry structure at a given byte offset (from RAHD raan_offset):

The engine iterates RAAN entries by skipping the 6-byte prefix, then scanning forward to the null terminator of file_path. The 4-byte dword at offset 0x00 is NOT used for seeking — the next entry is found purely by string scan.

The model name is extracted by stripping directory separators, file extension, and uppercasing the stem.

Model Fallback Resolution

When an MPOB record has an empty model_name, the exporter resolves a model via RAHD/RAAN:

1. Look up script_name in the RAHD index to get (raan_offset, raan_count).
2. Parse the RAAN entry at raan_offset to extract the file path.
3. Strip the path to a bare filename stem (e.g. fxart\FVPRA001.3DC → FVPRA001).
4. Use the stem as the model name for asset lookup.
5. If no RAHD/RAAN match, fall back to using script_name as the model name.

RAFS (FSphere)

RAFS contains bounding-sphere data for actors. Records are 11 bytes each (RAHD rafs_index rebases as rafs_data + index × 11). Internal per-field layout is not decoded. The engine only loads this section if its size exceeds 10 bytes.

RAST (String Data)

RAST contains all script string literals as null-terminated strings concatenated into a single blob. No count prefix; it is a flat byte array. Individual strings are located by offsets stored in RASB.

During loading, RASB offsets are rebased by adding the RAST data pointer, converting relative offsets into direct pointers.

RASB (String Offset Table)

RASB contains u32 LE offsets into RAST, one per string per actor. Each actor’s portion starts at string_offsets_index (from RAHD) and contains num_strings entries.

Total section length: sum of all actors’ num_strings × 4.

RAVA (Local Variables)

RAVA contains initial values for local script variables as a flat array of i32 LE integers. The first 4 bytes are always zero (sentinel).

Each actor’s portion starts at byte offset variable_offset (from RAHD; divide by 4 for the array index) and contains num_variables entries. When an actor has multiple instances, variables are replicated instances times. Variables are addressed by index in script bytecode (opcode 0x0A).

RASC (Script Bytecode)

RASC contains compiled SOUP386 scripting bytecode as a contiguous byte blob. Per-actor instruction blocks are located via RAHD offsets (script_data_offset, script_length, script_pc) and executed by the SOUP virtual machine.

For VM architecture, opcode encoding, operator tables, and execution semantics, see SOUP Scripting. For the definition-file format, see SOUP386.DEF.

Section Layout

Total payload = first actor script_data_offset + sum of all actors’ script_length values. For each actor, execution starts at script_pc relative to that actor’s block.

Other RA* sections (for example RAHK, RALC, RAVC) provide data referenced by RASC, often as u32 offset arrays rebased to loaded script memory.

RAHK (Hook Data)

RAHK contains hook offset tables. Entries are u32 LE offsets that are rebased against the RASC bytecode base address at load time, enabling scripts to register named entry points (hooks) that external events can invoke.

Per-actor hook counts and offsets are stored in the corresponding RAHD record. Entries are accessed at base + index × 4 + 0x25 — the 0x25-byte region before the offset array is a section header. The upper 16 bits of each u32 entry are extracted separately (>> 0x10) as a secondary field. No additional per-entry structure beyond the u32 offset array exists.

RAEX (Extra Data)

RAEX contains per-actor extra data with 30-byte fixed-size records (15 × i16 LE fields). The engine requires this section during loading. Record count is section_data_length ÷ 30. Per-actor RAEX offsets are stored in RAHD (raex_offset).

Field names Grip0 through RangeMax are from the in-game debug console.

All fields little-endian.

Total record size: 30 bytes (0x1E). Record count is section_data_length / 30.

RAAT (Attribute Data)

RAAT contains per-actor attribute tables. Each actor has a 256-byte attribute block, ordered sequentially (actor 0 at offset 0, actor 1 at offset 256, etc.).

Attribute names are defined in the auto…endauto section of SOUP386.DEF (see SOUP386.DEF). Each byte is a named attribute value; zero means unset. Attributes are read/written by the script functions GetAttribute and SetAttribute.

Total section length: record_count × 256.

RAGR (Animation Groups)

RAGR contains animation group definitions that link actors to their animation data in RAAN. RAGR provides the RGM-embedded equivalent of the AIAN section found in standalone .AI files; the engine selects one or the other source based on a runtime mode flag.

Per-actor RAGR data is located via RAHD.ragr_offset (offset 0x31). Entries are size-prefixed: the first u16 is the entry payload size (excluding itself); a value of 0 terminates the list. Advance to the next entry: current_position + 2 + entry_size.

The prefix byte used by the AIAN (standalone .AI) path is NOT present in RGM RAGR — instead, that value comes from RAHD offset 0x2D.

Animation Group Entry

All fields little-endian.

In ISLAND.RGM, Cyrus (RAHD record 22, ragr_offset=1318) has 152 animation groups. 58 groups contain attachment commands (opcode 0/4/10 with non-zero vertex index). Vertex 1 = hand attachment (sword combat), vertex -10 = scabbard attachment.

Animation Command (3 bytes, packed LE)

Each command is a 24-bit little-endian packed value. The low 4 bits select the opcode type, which determines how the remaining 20 bits are allocated to parameters.

Opcode 0 (ShowFrame) — the only opcode that sets the attachment vertex:

byte 0          byte 1          byte 2
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
├─hdl─┤ ├─op──┤ ├v┤ ├──handle─┤ ├───vertex────┤

opcode       = byte0 & 0x0F                        (4 bits)
handle_index = (byte0 >> 4) | ((byte1 & 0x3F) << 4)  (10-bit signed)
vertex_index = (byte1 >> 6) | (byte2 << 2)           (10-bit signed)

Both handle_index and vertex_index are 10-bit sign-extended values (range −512..+511). The handle_index is a relative index into the per-actor animation handle lookup table (built from RAAN entries at load time; patched to absolute runtime handles during loading). The vertex_index identifies which vertex to track for item attachment — see Item Attachment System.

Opcodes 4 (PlaySound) and 10 (ChangeAnimGroup) share the same 10+10 bit layout but their parameters are NOT handle/vertex — they are sound params and animation jump targets respectively. See attachment.md for the full 16-opcode table with names, bit layouts, and playback behavior.

RANM (Namespace)

RANM contains object namespace strings used for cross-script object references. Each actor’s portion is located by offset and length fields stored in RAHD (within the undecoded gap at 0x5D). The extracted string provides the actor’s canonical name for ObjDot* opcodes using selector byte 4 (named object from string table).

MPSL (Lights)

MPSL starts with a little-endian record count, followed by 42-byte records.

All fields little-endian.

Position fields use the same i24+pad encoding as MPOB/MPSO.

MPMK (Markers)

MPMK starts with a little-endian record count, followed by 13-byte records.

All fields little-endian.

Position fields use the same i24+pad encoding as MPOB/MPSO. No explicit record ID field. The engine branches on marker type (byte +0x04 in runtime struct) with values 0x02 and 0x06 triggering distinct paths.

MPSZ (Sizes)

MPSZ contains per-actor state data. Unlike other MP* sections, MPSZ does NOT use the standard count-prefixed layout — the first u32 is data, not a record count.

The engine allocates actor_count × 0x1A (26) bytes at runtime and builds a linked list of 26-byte records. Each record is populated from RAHD fields during loading.

File-level record sizes vary across maps (7–26+ bytes per actor). The file-to-runtime unpacking involves conditional rebasing from RAHD fields. Present in all 27 shipped RGM files (245–7056 bytes).

MPSF (Flat Objects)

MPSF starts with a little-endian record count, followed by 24-byte records. Each record places a textured quad in the scene.

All fields little-endian.

Position decode uses the same MPOB scale/sign rules. MPSF items are flat quads with zero rotation.

Redguard Preservation CLI

Scene Export Notes

• RGM carries scene placement transforms; ROB alone does not.
• Practical scene assembly requires MPOB + MPSO + MPRP + MPSF.
• Model lookup needs direct file stems, ROB segment-name resolution, and RAHD/RAAN fallback for empty MPOB.model_name (see RAHD and RAAN).
• Some names in shipped RGM files are truncated forms like NAME.3 and require normalization (strip from last . to get the segment stem).
• MPOB rotation parity uses degree-angle conversion; MPSO parity depends on the transposed matrix mapping above.
• MPSO rotation parity in scene export is obtained by interpreting Q4.28 values as a row-major 3x3 matrix, converting through quaternion space, applying mesh-axis flip in YZX Euler space (-X, +Y, -Z), then rebuilding the final rotation.
• Non-visual MPOB entries (sound triggers like WATERSND/WINDSND, door scripts like LOCKDOOR, lighting markers like NTLIGHT, entrance triggers like ENT*) have no model geometry; they emit transform-only nodes in the scene graph.
• Node naming convention: B_NNN_<script> for MPOB, SNNN_<model> for MPSO, FNNN_<texid>/<imgid> for MPSF.
• MPOB actors may carry a script-specific texture override from RAHD (textureId near record tail). Applying that override is required for correct character skin variants (for example Cartographer NPCs).

ROB segment resolution order

When a model name is not found as a direct file, the exporter scans all registered ROB files for a matching embedded segment. ROBs are scanned in source-priority order: fxart (v4.0/v5.0 models) before maps before 3dart (v2.6/v2.7 models).

v2.6/v2.7 models in 3dart/ ROBs have a known vertex-parsing limitation (vertex coordinates read as zero for ROB-embedded segments). Using fxart ROBs avoids this and produces correct geometry.

JSON Sidecar Output

When converting an RGM file via cargo run -- convert, a .json sidecar is written alongside the .glb containing all actor metadata that does not fit in the glTF format:

• Per-actor RAGR animation groups with every frame command decoded by opcode type
• Per-actor RAEX records (grip, scabbard, combat ranges, texture overrides)
• RAHD cross-reference (actor index and script name)

Each animation command is decoded with opcode-specific parameter names:

All commands include opcode (numeric) and name (e.g. "ShowFrame", "PlaySound").

External References

• UESP: Mod:RGM File Format
• UESP: Mod:Redguard File Formats
• RGUnity/redguard-unity RGRGMFile.cs — RGM section parser
• RGUnity/redguard-unity RGRGMScriptStore.cs — RASC bytecode interpreter with dispatch loop and complete flags table (369 entries)
• RGUnity/redguard-unity soupdeffcn_nimpl.cs — Complete SOUP function ID-to-name table (367 functions)
• Dillonn241/redguard-mod-manager ScriptReader.java — RASC bytecode disassembler (bytecode to readable script text)
• Dillonn241/redguard-mod-manager ScriptParser.java — RASC bytecode assembler (script text to bytecode); confirms round-trip encoding
• Dillonn241/redguard-mod-manager MapFile.java — RGM section reader/writer with complete chunk tag list
• Dillonn241/redguard-mod-manager MapHeader.java — RAHD record parser with field offsets
• Dillonn241/redguard-mod-manager MapDatabase.java — SOUP386.DEF parser (function, flag, reference, attribute definitions)

WLD World Geometry File Format

Terrain/world-grid container with a fixed 4-section layout; each section stores four 128x128 byte maps.

4 WLD files exist in /maps: EXTPALAC.WLD, HIDEOUT.WLD, ISLAND.WLD, NECRISLE.WLD.

Overall Structure

All WLD files are exactly 263,432 bytes.

[Header — 1184 bytes]
[Section 0 — 65558 bytes]
[Section 1 — 65558 bytes]
[Section 2 — 65558 bytes]
[Section 3 — 65558 bytes]
[Footer — 16 bytes]

Each section (65,558 bytes) is:

[Section Header — 22 bytes]
[Map 1 — 128×128 bytes (heightmap)]
[Map 2 — 128×128 bytes (unused, zero-filled)]
[Map 3 — 128×128 bytes (texture/material)]
[Map 4 — 128×128 bytes (unused, zero-filled)]

Header (1184 bytes)

The file header is 296 dwords (u32[296]). Most are zero; 12 are non-zero.

Logical field groups within the 296-dword header:

• unknown1[6] (u32[6]) at 0x00..0x17
• sec_hdr_size (u32) at 0x18
• file_size (u32) at 0x1C
• unknown2[28] (u32[28]) at 0x20..0x8F
• sec_ofs[4] (u32[4]) at 0x90..0x9F
• unknown3[256] (u32[256]) at 0xA0..0x49F

0xA0..0x49F is a contiguous u32[256] block (unknown3), not a single field. Only unknown3[0] is non-zero; the remaining 255 dwords are zero.

The header is byte-identical across all 4 shipped WLD files. All remaining header dwords not listed above are zero.

The loader reads the first 0x90 bytes, validates 0x14 == 1 and 0x18 == 22, and uses only section_cols, section_rows, and section_header_size at runtime. Fields beyond 0x1C — including sec_ofs[4] and unknown3[256] — are not read by the terrain loader.

Section Header (22 bytes)

Each section starts with 11 little-endian words (u16[11]):

Section headers are identical across all 4 shipped WLD files. unknown1[0] varies by section index: section0=2152, section1=568, section2=1308, section3=10. texbsi_file is always 302. map_size is always 256.

The loader reads each 22-byte section header but does not decode or reference any fields — it proceeds directly to map-plane reads. The engine hard-wires texbsi.302 for terrain textures regardless of the per-section texbsi_file value.

unknown1[0] cannot be a TEXBSI id (values like 568 and 1308 have no matching files). It appears to be build-tooling metadata fixed per section slot.

Section headers (identical across all files):

Map Planes

After each 22-byte section header, four 128x128 byte maps follow.

• Map 1: heightmap plane; low 7 bits are height (0–127), high bit is a build-time flag stripped at load time. See Map 1 High Bit.
• Map 2: unused — always zero-filled; skipped by the engine at load time.
• Map 3: texture/material plane; packed bits:
  • low 6 bits (0..63) = texture index
  • high 2 bits (0..3) = quarter-turn rotation
• Map 4: unused — always zero-filled; skipped by the engine at load time.

The engine only uses Map 1 and Map 3. Maps 2 and 4 are skipped during loading — their bytes are read to advance the file stream, but the data is never stored or used.

texbsi_file = 302 matches on-disk texture archive fxart/TEXBSI.302.

In TEXBSI.302, image names follow D02xxx, which aligns with TEXBSI naming rules:

• filename low two digits (02) match image-name file number (D02xxx)
• filename hundreds digit (3) matches type-char group (D)

Notes:

• Map 3 bit packing (index + rotation) is corroborated by UESP documentation.
• Original-engine terrain initialization hard-loads texbsi.302 and precomputes a 64-entry terrain texture lookup table from that archive, matching Map 3’s 0..63 index space.
• Engine string analysis confirms texbsi.302 is referenced by the terrain initialization path; texbsi.%s is referenced by the generic TEXBSI loader path, not the terrain-table initialization path.
• Conclusion: per-section texbsi_file switching is not used by the original engine’s terrain renderer; terrain textures come from TEXBSI.302.

Cross-check against shipped fxart/TEXBSI.302:

• Map 3 index range 0..63 is fully covered by image ids in TEXBSI.302 (name suffixes 00..63).
• The previously “missing” ids (00, 05, 06, 07, 30, 31, 32, 52) are present as alternate record forms in the TEXBSI stream (not just the main BSIF image-record form), matching UESP’s note that index mapping is not a simple 1:1 record-order lookup.
• Those alternate-form ids are IFHD animated records in TEXBSI.302, consistent with lookup by image-id suffix rather than simple static-record order.
• Rotation bits are still populated when texture index is 0; this suggests engine-side handling likely treats index 0 as dominant (rotation may be ignored for empty/default tiles).

Bank summary (fxart/TEXBSI.*, D-prefix terrain-style banks):

• Only TEXBSI.302 has full 0..63 coverage (56 BSIF static records + 8 IFHD animated records). Other D* banks are partial/specialized.
• Combined with engine evidence (the engine hard-wires texbsi.302), the original engine’s terrain path should be treated as fixed-bank (302) rather than generic per-bank Map 3 lookup behavior.

Map 1 High Bit (0x80)

The game engine strips the high bit (& 0x7F) from every Map 1 byte at WLD load time, before storing height values in its runtime buffer. The high bit is discarded and never used for rendering, height lookup, texture selection, or any other runtime purpose.

The high bit tends to appear on outer-border cells and cells with large height deltas. It may be a build-time artifact (e.g., marking boundary or steep cells for the level editor) that the runtime engine does not consume.

Each section contributes one 128x128 tile per map plane. The four section tiles combine into a 2x2 world grid (256x256) as described by UESP.

Terrain Rendering Pipeline

At runtime, Map 1 and Map 3 are loaded into separate buffers and processed independently — there is no interaction between the two during rendering.

Grid Coordinate System

Each grid cell is 256 engine units wide. Terrain vertex positions are computed as:

world_x = grid_index_x × 256
world_z = grid_index_z × 256
world_y = -height_table[heightmap_byte & 0x7F]

No origin offset is applied to vertex positions. A separate world→grid reverse-lookup (used for camera cell detection) applies half-cell offsets (−0.5 on X, +0.5 on Z), but these do not affect terrain geometry.

Height Values (Map 1)

Each Map 1 byte is masked to 7 bits (& 0x7F) at load time, producing height values in the range 0–127. These values index into a 128-entry float lookup table to produce world-space Y coordinates.

The engine stores a static source table of positive float values and negates them at initialization (-ABS(source)), so terrain heights are negative — the terrain surface sits below a reference plane. A second initialization mode computes water_level - ABS(source), adjusting heights relative to a configurable water-level parameter.

Height Lookup Table

The 128-entry source table (values in engine units before negation):

   0:     0    40    40    40    80    80    80   120   120   120
  10:   160   160   160   200   200   200   240   240   240   280
  20:   280   320   320   320   360   360   400   400   400   440
  30:   440   480   480   480   520   520   560   560   600   600
  40:   600   640   640   680   680   720   720   760   760   800
  50:   800   840   840   880   880   920   920   960  1000  1000
  60:  1040  1040  1080  1120  1120  1160  1160  1200  1240  1240
  70:  1280  1320  1320  1360  1400  1440  1440  1480  1520  1560
  80:  1600  1600  1640  1680  1720  1760  1800  1840  1880  1920
  90:  1960  2000  2040  2080  2120  2200  2240  2280  2320  2400
 100:  2440  2520  2560  2640  2680  2760  2840  2920  3000  3080
 110:  3160  3240  3360  3440  3560  3680  3800  3960  4080  4280
 120:  4440  4680  4920  5200  5560  6040  6680  7760

The table uses a non-linear encoding with three regions:

• Indices 0–52 (values 0–2120): near-linear with ~40-unit steps and repeated values, giving maximum height precision for flat and gently sloped terrain where the player spends most time.
• Indices 53–69 (values 2120–3240): transition zone with gradually increasing step sizes.
• Indices 70–127 (values 3240–7760): accelerating steps (80 → 120 → 240 → 1080), compressing tall cliffs and peaks into fewer index values.

This is a hand-tuned gamma-like curve that allocates more precision to common terrain heights (flat ground, gentle slopes) while still supporting the full elevation range with 7 bits of storage.

Texture Selection (Map 3)

Each Map 3 byte encodes two fields:

In the original engine, the texture index selects one of 64 preloaded terrain texture entries sourced from TEXBSI.302 (not a per-section runtime bank switch). The rotation selects one of four UV orientation states (0°, 90°, 180°, 270° counter-clockwise).

Terrain Texture Blending (SURFACE.INI)

The engine loads a SURFACE.INI configuration file (from the game directory) that defines per-texture-index blend behavior and surface-type sound remapping. This drives a pixel-level alpha-blending system for terrain tile transitions — it does not affect geometry, UVs, or material assignment.

Water Tiles

The terrain renderer treats certain texture indices as water or special tiles. When all four corners of a grid cell have texture indices in the set {0, 5, 30, 31}, the cell is rendered as a water surface instead of normal terrain geometry. This applies water-plane rendering with wave animation effects. See Water Waves for the per-frame displacement formula and rendering pipeline.

Terrain Normals

The engine computes smooth vertex normals for terrain in three passes:

1. Face normals — Each grid cell is split into two triangles (TL→BR→TR and BR→TL→BL). A cross-product normal is computed per triangle.
2. Vertex averaging — At each grid vertex, the face normals from all adjacent triangles are summed and normalized. Each interior vertex touches 6 triangles from 4 cells: both triangles of the cell to the upper-left and lower-right, plus one triangle each from the cells above and to the left.
3. Rendering — The averaged vertex normals are used for Gouraud-interpolated shading across each triangle.

This produces smooth terrain shading. The per-triangle face normals (pass 1) are retained as intermediate values but are not used directly for rendering.

Footer (16 bytes)

The final 16 bytes are constant in all files:

54 55 4C 4F 28 C0 43 00 FF FF FF FF 35 37 04 00

Interpreted as four dwords (u32, little-endian):

1. 0x4F4C5554 ("TULO" bytes in file order)
2. 0x0043C028
3. 0xFFFFFFFF
4. 0x00043735

The WLD loader does not read or parse this footer; it stops after reading the 4 section data blocks. The footer is a build-time artifact or reserved metadata ignored at runtime. Field-level semantics are unknown.

Relationships to Other Formats

• RGM stores scene/object placement for the same levels.
• PVO stores octree-style spatial/visibility data for some of the same levels. WLD terrain is not included in PVO visibility culling. The engine’s PVO visibility check operates exclusively on placed objects — it searches MLST entries against MPSO records and actor pointers, and is called only from the placed-object render loop. Terrain is rendered through a separate unconditional path (the engine’s terrain surface subsystem). Default visibility is 1 (visible) when PVO data is absent.
• TEXBSI supplies textures referenced by Map 3 indices (Map 3 index range 0–63 is fully covered by TEXBSI.302).

External References

• UESP: Mod:World Files
• UESP: Mod:Redguard File Formats
• uesp/redguard-3dfiletest 3DFileTest/Common/
• RGUnity/redguard-unity RGWLDFile.cs

SFX Sound Effects File Format

Single-file container for all game sound effects, stored as MAIN.SFX in the SOUND directory. Does not include voice clips (those are in ENGLISH.RTX).

Overall Structure

FXHD section (44 bytes)
FXDT section (variable)
"END " (4 bytes)

Effects are stored sequentially with no offset table. The game references effects by their 0-based index in the file.

FXHD (Header Section)

44 bytes total. Section size word is big-endian; remaining fields are little-endian.

FXDT (Data Section)

Begins with a big-endian u32 section size (excluding itself), followed immediately by sequential effect records.

Effect Record

27-byte header followed by raw PCM audio data.

All fields little-endian unless noted.

Loop Behavior

The engine checks only whether loop_flag is non-zero — the specific value is not interpreted.

• loop_flag = 0: play once (non-looping effects)
• loop_flag = -1 (0xFF): enable looping (used for ambient loops like fire, water, wind)
• loop_flag = -31 (0xE1): enable looping (functionally identical to -1; only used on effect 117, the snake charmer tune)

loop_offset and loop_end appear to be unused features — always loop_offset = 0 and loop_end = 0xFFFFFFFF.

Runtime Effect Structure

The engine allocates a 34-byte (0x22) runtime structure per effect, reading 26 bytes (0x00–0x19) from the file. The remaining 8 bytes are computed at runtime:

Related Formats

• RTX — dialogue audio container. Uses the same 27-byte audio header structure (offsets 0x00–0x1A) as SFX effect records. SFX stores sound effects; RTX stores voice clips.

External References

• UESP: Mod:SFX File

RTX Dialogue Audio Format

Container format used for dialogue strings and audio assets (for example ENGLISH.RTX).

Overview

RTX stores two payload kinds under a common chunk/index system:

• String-only entries (ASCII text payload)
• Audio entries (string metadata + fixed audio header + audio bytes)

The file uses:

• per-chunk on-disk headers (tag + big-endian payload size)
• a footer that points to a central index table

All values below are validated against ENGLISH.RTX.

File Layout

[chunk records ...]
[index table]
[footer]

Footer (12 bytes, file end)

For ENGLISH.RTX:

• footer_tag = RNAV
• index_offset = 184629473
• index_count = 4866

Chunk Record (on disk)

Every payload in the data region has an 8-byte chunk header before it:

Index Table

The index is an array of 12-byte entries. Each entry points to one chunk payload.

Validation notes (all 4866 entries):

• payload_offset - 8 points to a chunk header with matching tag
• header payload_size (big-endian) matches indexed payload_size
• all indexed ranges are in bounds (offset + size <= file_size)
• entries are ordered by descending payload offset

Payload Types

Payload type is identified by byte payload[1]:

• 0 = string-only entry
• 1 = audio entry

String-Only Payload (payload[1] = 0)

Payload size rule:

payload_size = 6 + string_len

Audio Payload (payload[1] = 1)

Audio payload size rule:

payload_size = 6 + string_len + 27 + audio_length

Audio Header (27 bytes)

All fields little-endian unless noted.

Notes

• Tags are 4-byte IDs and are not globally reused in ENGLISH.RTX.
• A few tags include punctuation (for example #bon, ?vql).
• The index points to payload starts; on-disk chunk headers are always 8 bytes earlier.

Related Formats

• SFX — sound effects container. Uses the same 27-byte audio header structure (offsets 0x00–0x1A) as RTX audio entries. RTX stores voice clips; SFX stores sound effects.

Redguard Preservation CLI

Read

cargo run -- read ENGLISH.RTX parses the file and prints a per-entry summary: tag, type (TEXT or AUDIO), audio format, sample rate, duration, and a label preview.

Convert

cargo run -- convert ENGLISH.RTX -o output_dir/ extracts all audio entries as individual .wav files (named by 4-character tag, e.g. zbza.wav) and writes an index.json sidecar containing metadata for all 4866 entries (both text-only and audio).

Validated against ENGLISH.RTX: 3933 .wav files + 933 text entries in index.json.

External References

• RGUnity/redguard-unity RGRTXFile.cs | RTX container reader
• Dillonn241/redguard-mod-manager RtxDatabase.java | RTX read/write with round-trip support
• Dillonn241/redguard-mod-manager RtxEntry.java | RTX entry structure and audio format definitions
• UESP: Redguard Console (script command context)

TEXBSI Texture File Format

Container format for indexed-color texture images. Files are named TEXBSI.### where ### is the texture bank number.

Overall Structure

A TEXBSI file is a flat sequence of image records with no file-level header. The sequence ends when a 9-byte null sentinel is encountered.

[Image Record 0]
[Image Record 1]
...
[Image Record N]
[9 × 0x00]   ← end sentinel

Image Record

Image-record envelope fields are little-endian.

Image Name Encoding

The 9-byte name encodes the file number and sub-image index:

"E01005\0\0\0" → type 'E', file 01, image index 005
"A02003\0\0\0" → type 'A', file 02, image index 003

The image index (last 3 digits) is how 3D model faces reference sub-images via image_id.

Filename/name coupling across shipped TEXBSI.### files:

• ### % 100 matches the 2-digit file number in image names.
• ### / 100 maps to type-char family: 0->A, 1->B, 2->C, 3->D, 4->E, 5->F.

Examples:

• TEXBSI.302 contains D02xxx images.
• TEXBSI.114 contains B14xxx images.

Type characters range from A through F.

The type character has no semantic meaning — it is a deterministic artifact of the base-40 name encoding used internally. The game converts numeric texture IDs to 6-character strings using the alphabet 0123456789abcdefghijklmnopqrstuvwxyz~_#%, then shifts the first character by subtracting 0x31. The type letter is simply which base-40 digit range the texture ID falls into (A=digit 27, B=28, …, F=32). The game never tests or filters by the type character — it round-trips through the numeric ID.

Subrecord Structure

Every subrecord has an 8-byte header:

Subrecord size words are big-endian.

Subrecords always appear in this order:

BSIF or IFHD  (mutually exclusive)
BHDR           (required)
CMAP           (optional, only with IFHD)
DATA           (required)
END            (terminates the record — no size field)

Subrecord Payloads

BSIF — Static Image Marker

Payload size: 0 bytes (empty). Marks a static (non-animated) image.

IFHD — Animated Image Marker

Payload size: 44 bytes (always 01 followed by 43 00 bytes). Marks an animated image.

When IFHD is present, the DATA subrecord uses the animated offset-table format.

BHDR — Image Header (26 bytes)

All fields are little-endian.

CMAP — Embedded Palette (768 bytes)

256 × RGB triplets (3 bytes each, values 0–255). Same layout as COL files.

Optional — always co-occurs with IFHD (animated images). When absent, the image uses an external .COL palette file.

DATA — Pixel Data

Static images (BSIF present, frame_count == 1):

Payload is width × height bytes of 8-bit indexed color, row-major, top-to-bottom. Each byte is a palette index (0–255). Index 0 = transparent.

Animated images (IFHD present, frame_count > 1):

Payload starts with an offset table of height × frame_count LE u32 entries. Each entry is a byte offset from the start of the DATA payload to the first byte of that row. Rows can be shared across frames (identical rows point to the same data).

offset_table[frame * height + row] → byte offset to row data (width bytes)

END — Record Terminator

4-byte tag "END " (with trailing space). No size field. Followed by 4 zero bytes.

Pixel Decoding

for each pixel byte:
  if byte == 0:    → transparent (alpha = 0)
  else:            → palette[byte] as RGB (alpha = 255)

Palette values are raw 8-bit RGB (0–255). No gamma correction needed.

Palette Selection

When decoding pixel data, palette lookup order is:

1. External .COL palette — the scene-level palette file passed to the converter (e.g. ISLAND.COL). Which COL file to use is determined per-scene by the game engine.
2. Embedded CMAP — the 256-color palette stored inside the image record (only present in animated IFHD images).
3. Grayscale fallback — if neither is available, each index maps to a gray value.

How 3D Models Reference Textures

Each face in a 3D model encodes a texture_id and image_id:

• texture_id → selects the TEXBSI.### file number
• image_id → selects the sub-image within that file (0-indexed, matching the 3-digit suffix in the image name)

See 3D.md — Texture Decoding for the BCD encoding.

External References

• UESP: Mod:TEXBSI File Format — community byte-layout notes for TEXBSI records and subrecords.
• uesp/redguard-3dfiletest RedguardTexBsiFile.cpp
• RGUnity/redguard-unity RGTEXBSIFile.cs
• RGUnity/redguard-unity RGBSIFile.cs

COL Palette File Format

256-color RGB palette format.

Each file maps color indices (0–255) to RGB values. Models reference palette entries via color_index in solid-color face data (see 3D.md).

Overall Structure

All COL files are exactly 776 bytes.

Palette entry N is at offset 8 + N × 3, yielding bytes (R, G, B).

Usage

COL files are per-scene, not per-model. Different levels use different palettes (e.g. ISLAND.COL, CATACOMB.COL). The same color_index in a model’s face data produces different colors depending on which palette is active.

Entry 0 is always (0, 0, 0) — black.

Related Formats

• TEXBSI — the CMAP subrecord in animated TEXBSI images uses the identical 256 × RGB triplet layout (768 bytes). CMAP palettes are embedded per-image; COL palettes are per-scene.
• FNT — font files embed their own BPAL/FPAL palettes (same 768-byte layout), independent of scene COL palettes.

Redguard Preservation CLI

The convert command exports a COL file as two companion files:

• Swatch PNG — 256×256 image with a 16×16 grid of color swatches (16 px per cell). Index 0 is top-left, 255 is bottom-right, row-major order.
• Palette JSON — structured metadata with per-entry index, r, g, b (0–255), and hex fields. Versioned as redguard-col-v1.

The output path determines the primary filename; the companion file shares the same stem with the other extension. Passing -o ISLAND.png produces ISLAND.png + ISLAND.json; passing -o ISLAND.json produces the same pair.

External References

• UESP: Mod:Palette Files — dedicated Redguard COL page with the 8-byte header + 768-byte palette layout.
• UESP: User:Daveh/Redguard File Formats — COL size and palette usage notes.

FNT Bitmap Font File Format

Chunked bitmap-font format with per-file palette and per-glyph indexed image data.

.FNT stores UI/dialog font glyphs as palette-indexed bitmaps. Each file embeds its own palette (not scene COL palettes), then stores glyph records in ASCII order. For palette structure background, see COL.md.

Top-Level Layout

The file is a sequence of named chunks, followed by an end marker:

1. FNHD (always present)
2. BPAL or FPAL (always present)
3. FBMP (always present)
4. RDAT (optional)
5. END marker

Common chunk orders:

• FNHD -> BPAL -> FBMP -> END
• FNHD -> BPAL -> FBMP -> RDAT -> END
• FNHD -> FPAL -> FBMP -> END (ARIALVS.FNT only)

Chunk Header

Each chunk begins with an 8-byte header:

Chunk-length fields are big-endian.

END is a 4-byte marker tag with no payload. ARIALVS.FNT has 4 additional trailing zero bytes after END .

FNHD Chunk (56 bytes)

FNHD payload is always 56 bytes.

Numeric fields are little-endian.

BPAL / FPAL Chunk (Palette)

Palette payload is always 768 bytes (256 RGB triplets).

Notes:

• BPAL is the normal tag.
• FPAL appears in ARIALVS.FNT with the same 768-byte payload shape.
• These palettes are local to each font file, independent of scene palettes in COL.md.

FBMP Chunk (Glyph Records)

FBMP payload contains character_count glyph records in sequential codepoint order starting at character_start.

Each glyph record:

Numeric fields are little-endian.

Value ranges:

• offset_left: 0..5
• offset_top: 0..19
• width: 1..22
• height: 1..25

FBMP payload length equals the sum of all glyph record sizes (10-byte header + width * height pixels each).

RDAT Chunk (Optional, 173 bytes)

RDAT is optional and always 173 bytes when present.

Layout (partially decoded):

Numeric fields are little-endian.

RDAT is metadata. The font loader uses FNHD, FPAL/BPAL, and FBMP; it does not parse RDAT payload data.

External References

• UESP: Mod:Font Files — primary external reference for FNHD/BPAL/FBMP/RDAT chunk semantics.
• UESP: Redguard:Glide Differences — renderer-specific font usage differences (non-structure behavior).
• UESP: Mod:RedguardFNTImporter — tooling-oriented evidence for practical import/export expectations.

PVO File Format

Pre-computed Visibility Octree. Binary spatial data format located in the /maps directory alongside .RGM (scene) and .WLD (terrain) files.

5 PVO files exist, each corresponding to a game level: CATACOMB, CAVERNS, DRINT, ISLAND, PALACE.

For a complete reference parser with pseudocode, see PVO Parser.

Purpose

PVO files store pre-computed visibility data used for geometry culling at runtime. Instead of calculating which polygons are visible from the camera every frame, the game looks up the camera position in the octree and retrieves a pre-built list of visible group IDs.

The runtime lookup works as follows: take the camera’s world-space position, walk the octree from root to leaf by comparing coordinates against each node’s center, then collect the polygon indices stored in that leaf’s PLST entries (which reference ranges in the MLST table). Only those polygons are submitted for rendering — everything else is skipped.

The data is generated offline by placing a virtual camera at every point on a uniform 256-unit grid across the level, running a visibility query at each point, and baking the results into the octree. See Generation Process for details.

Overall Structure

The file uses the same section-framing as RGM: 4-byte ASCII tag + 4-byte big-endian data length.

[OCTH — header]
[OCTR — octree node records]
[PLST — leaf polygon-list records]
[MLST — master polygon index table]
[END  — footer]

Each section is framed as:

Section layout

A sixth section tag PTCH exists in the executable’s string table but is not present in shipped files. The engine writes and loads PTCH sections through dedicated save/load paths (the pvopatchsave console command triggers a write).

Best-effort runtime characterization from engine behavior:

• PTCH section length is serialized as patch_count * 6 bytes.
• The loader allocates and reads 6-byte records from PTCH.
• Patch application expands record data into MLST object-id lists used by PVO visibility checks.

Per-record layout (resolved from add/remove/apply behavior):

Engine behavior:

• Add patch: writes octr_node_index at record+0 and object_index at record+4.
• Delete patch: matches/removes records by the same pair (octr_node_index, object_index).
• Apply patch: scans records matching current octr_node_index and appends object_index values into the runtime visibility-id buffer.

OCTH Section — Header (52 bytes payload)

Node count relationship

total_nodes = leaf_nodes + interior_nodes where interior_nodes equals the number of 0xFFFFFFFF leaf_ref values in the OCTR section:

mlst_polygon_count confirmation

Center coordinates and extents

The octree root spans [center - cell_size, center + cell_size] on each axis.

OCTR Section — Octree Node Records

Serialized octree nodes written sequentially. Each node is a variable-length record addressed by byte offset within the section.

Node record format

Record size = 5 + popcount(child_mask) * 4

Possible sizes: 5, 9, 13, 17, 21, 25, 29, 33, 37 bytes.

Octant assignment

The 3-bit octant index encodes spatial position relative to the node center:

bit 0 (value 1) = z > center_z
bit 1 (value 2) = y > center_y
bit 2 (value 4) = x > center_x

Octant 0 = (x-, y-, z-)    Octant 4 = (x+, y-, z-)
Octant 1 = (x-, y-, z+)    Octant 5 = (x+, y-, z+)
Octant 2 = (x-, y+, z-)    Octant 6 = (x+, y+, z-)
Octant 3 = (x-, y+, z+)    Octant 7 = (x+, y+, z+)

Common child_mask patterns

Child and leaf sentinel values

Two sentinel values appear in octree records:

• 0xFFFFFFFF in the leaf_ref field marks interior-only nodes — nodes with children but no directly associated polygon list. The count of these values equals interior_nodes from the header. In runtime traversal code, 0xFFFFFFFF also serves as the null terminator that ends octree walks.
• 0xFFFFFFFE in child_refs marks an uninitialized/placeholder child node. During runtime octree traversal, this value indicates an unpopulated slot; when traversal visits it, the slot is overwritten with the current position. This is distinct from a null child (0xFFFFFFFF) and from a valid child offset.

PLST Section — Leaf Polygon-List Records

Serialized leaf data written sequentially. This is the largest section in every file. Each leaf describes which polygon groups are visible from an octree cell.

Leaf record format

Record size = 1 + 6 * entry_count

Each entry:

Each entry references a contiguous slice: mlst[mlst_start .. mlst_start + count].

Constraint: mlst_start + count <= mlst_polygon_count.

Entries within a leaf represent distinct polygon groups. The full visible set for a leaf is the union of all its entry slices. Multiple leaves may share the same MLST ranges.

leaf_ref values in OCTR are byte offsets into this section, pointing to the start of a leaf record.

MLST Section — Master Polygon Index Table

A flat array of u16 visibility group indices.

• Length: mlst_polygon_count * 2 bytes.

This table is the master list of visibility groups referenced by the octree. PLST entries reference contiguous ranges within this table.

Index semantics

Each u16 value is a placed-object visibility ID, not an individual face index. The indices form a dense, zero-based sequential range with no gaps. The visibility check at runtime uses two lookup paths based on the index value:

• Indices 0 .. MPSO_count-1: direct MPSO record index. The runtime multiplies the index by 66 (0x42 = MPSO record size) and adds the MPSO array base to get the placed-object record.
• Indices MPSO_count .. N-1: secondary table index. The runtime subtracts MPSO_count and uses the result as an index into a separate pointer table. This table holds additional static objects loaded at runtime (e.g. via LoadStatic script commands, MPRP rope chains, or other non-MPSO visibility targets).

The MPSO record size (66 bytes = 0x42) appears as the multiplier in visibility lookups.

END Section — Footer

8 bytes: END (4 ASCII bytes) followed by 0x00000000 (4 zero bytes). Data length is 0.

Generation Process

PVO files are generated by iterating a uniform 3D grid over the world bounding box:

1. Compute world bounding box from level geometry.
2. Iterate a uniform 3D grid at 256-unit spacing.
3. At each grid point, run a visibility query to determine which polygons are visible.
4. Insert the visible polygon set as a leaf into the octree.
5. Prune single-child branches, then write the file.

Debug console commands

Secondary Visibility Table

MLST indices >= MPSO_count reference a secondary pointer table built at runtime. This table is populated by iterating the placed object list and collecting objects whose visibility flag (offset +0x7a in the runtime object struct) is non-zero.

The visibility flag is set by SOUP script functions during object initialization. Objects that receive this flag — such as dynamically loaded static models — become trackable by the PVO system alongside the primary MPSO-based objects.

External References

• UESP: Mod:Redguard File Formats
• UESP: User:Daveh/Redguard File Formats
• RGUnity/redguard-unity RGFileImport/RGGFXImport/

PVO Parser — Pseudocode

Reference parser for the PVO (Pre-computed Visibility Octree) file format. See PVO Format for format specification.

All field-level details below are validated against all 5 shipped PVO files with byte-exact section boundary matches.

Data Types

u8       — unsigned 8-bit
u16_le   — unsigned 16-bit, little-endian
u32_le   — unsigned 32-bit, little-endian
i32_le   — signed 32-bit, little-endian
u32_be   — unsigned 32-bit, big-endian
tag      — 4 ASCII bytes (e.g. "OCTH")

Structures

struct PvoFile {
    header:     OcthHeader,
    nodes:      Vec<OctrNode>,      // OCTR section, indexed by byte offset
    leaves:     Vec<PlstLeaf>,      // PLST section, indexed by byte offset
    mlst:       Vec<u16_le>,        // MLST section, flat polygon index table
}

struct OcthHeader {
    depth:              u32,        // always 10 — max octree depth
    total_nodes:        u32,        // len(nodes)
    leaf_nodes:         u32,        // nodes with leaf_ref != 0xFFFFFFFF
    mlst_polygon_count: u32,        // len(mlst)
    reserved:           u32,        // always 0
    cell_size:          u32,        // root half-extent (16384 or 8192)
    center_x:           i32,        // octree root center
    center_y:           i32,
    center_z:           i32,
    _pad:               [u32; 4],   // always zero
}

struct OctrNode {
    byte_offset:  usize,            // position within OCTR data (for child_ref lookups)
    child_mask:   u8,               // bit i set → child i present (octants 0..7)
    leaf_ref:     u32,              // byte offset into PLST, or 0xFFFFFFFF (no leaf)
    child_refs:   Vec<(u8, u32)>,   // (octant_index, byte_offset into OCTR) per set bit
}

struct PlstLeaf {
    byte_offset:  usize,            // position within PLST data (for leaf_ref lookups)
    entries:      Vec<PlstEntry>,
}

struct PlstEntry {
    count:        u16,              // number of polygon indices in this sub-list
    mlst_start:   u32,              // starting index into the MLST array
}

Section Framing

Every section uses identical framing. Parse sections sequentially until END .

fn read_section_header(reader) -> (tag: [u8; 4], data_length: u32):
    tag         = reader.read_bytes(4)
    data_length = reader.read_u32_be()
    return (tag, data_length)

Top-Level Parser

fn parse_pvo(reader) -> PvoFile:
    // --- OCTH ---
    (tag, data_length) = read_section_header(reader)
    assert tag == "OCTH"
    assert data_length == 52
    header = parse_octh(reader)

    // --- OCTR ---
    (tag, data_length) = read_section_header(reader)
    assert tag == "OCTR"
    nodes = parse_octr(reader, data_length)

    // --- PLST ---
    (tag, data_length) = read_section_header(reader)
    assert tag == "PLST"
    leaves = parse_plst(reader, data_length)

    // --- MLST ---
    (tag, data_length) = read_section_header(reader)
    assert tag == "MLST"
    assert data_length == header.mlst_polygon_count * 2
    mlst = parse_mlst(reader, data_length)

    // --- END ---
    (tag, data_length) = read_section_header(reader)
    assert tag == "END "
    assert data_length == 0

    // --- Validation ---
    assert len(nodes) == header.total_nodes
    leaf_count = count(n for n in nodes if n.leaf_ref != 0xFFFFFFFF)
    assert leaf_count == header.leaf_nodes

    return PvoFile { header, nodes, leaves, mlst }

OCTH Parser

fn parse_octh(reader) -> OcthHeader:
    header = OcthHeader {
        depth:              reader.read_u32_le(),   // 0x08
        total_nodes:        reader.read_u32_le(),   // 0x0C
        leaf_nodes:         reader.read_u32_le(),   // 0x10
        mlst_polygon_count: reader.read_u32_le(),   // 0x14
        reserved:           reader.read_u32_le(),   // 0x18 — always 0
        cell_size:          reader.read_u32_le(),   // 0x1C
        center_x:           reader.read_i32_le(),   // 0x20
        center_y:           reader.read_i32_le(),   // 0x24
        center_z:           reader.read_i32_le(),   // 0x28
        _pad:               reader.read_bytes(16),  // 0x2C — always zero
    }
    return header

OCTR Parser

Octree nodes are serialized as a flat sequence of variable-length records. Each record describes one octree node. The records are addressed by byte offset within the OCTR data section.

fn parse_octr(reader, data_length: u32) -> Vec<OctrNode>:
    nodes = []
    bytes_read = 0

    while bytes_read < data_length:
        node_offset = bytes_read

        child_mask = reader.read_u8()
        leaf_ref   = reader.read_u32_le()
        bytes_read += 5

        // Read one child_ref per set bit in child_mask (low bit first)
        child_refs = []
        for octant in 0..8:
            if child_mask & (1 << octant) != 0:
                ref = reader.read_u32_le()
                child_refs.push((octant, ref))
                bytes_read += 4

        nodes.push(OctrNode {
            byte_offset: node_offset,
            child_mask,
            leaf_ref,
            child_refs,
        })

    assert bytes_read == data_length
    return nodes

Node record binary layout

 Byte 0       Bytes 1..4        Bytes 5..5+4n
┌──────────┬─────────────────┬────────────────────────────────┐
│child_mask│   leaf_ref      │ child_ref[0] .. child_ref[n-1] │
│  (u8)    │   (u32_le)      │ (u32_le each)                  │
└──────────┴─────────────────┴────────────────────────────────┘
 n = popcount(child_mask)
 record_size = 5 + 4n

Octant numbering

The 3-bit octant index encodes spatial position relative to the node center:

 bit 0 (1) = z > center_z
 bit 1 (2) = y > center_y
 bit 2 (4) = x > center_x

 Octant 0 = (x-, y-, z-)    Octant 4 = (x+, y-, z-)
 Octant 1 = (x-, y-, z+)    Octant 5 = (x+, y-, z+)
 Octant 2 = (x-, y+, z-)    Octant 6 = (x+, y+, z-)
 Octant 3 = (x-, y+, z+)    Octant 7 = (x+, y+, z+)

Interpreting references

• leaf_ref: byte offset into the PLST section data. 0xFFFFFFFF = no leaf (interior-only node).
• child_refs: byte offset into the OCTR section data. Use to look up child nodes by their byte_offset field.

Reference consistency in shipped files:

• 100% of child_refs match a node byte_offset.
• 100% of leaf_refs fall within PLST bounds.

PLST Parser

Leaf records describe which polygon groups are visible from an octree cell. Each leaf contains a list of (count, mlst_start) entries that reference ranges within the MLST polygon index table. Multiple leaves may share the same MLST ranges.

fn parse_plst(reader, data_length: u32) -> Vec<PlstLeaf>:
    leaves = []
    bytes_read = 0

    while bytes_read < data_length:
        leaf_offset = bytes_read

        entry_count = reader.read_u8()
        bytes_read += 1

        entries = []
        for _ in 0..entry_count:
            count      = reader.read_u16_le()
            mlst_start = reader.read_u32_le()
            entries.push(PlstEntry { count, mlst_start })
            bytes_read += 6

        leaves.push(PlstLeaf {
            byte_offset: leaf_offset,
            entries,
        })

    assert bytes_read == data_length
    return leaves

Leaf record binary layout

 Byte 0         Bytes 1..1+6n
┌────────────┬──────────────────────────────────────────┐
│entry_count │ entry[0]          .. entry[n-1]          │
│  (u8)      │ [count:u16][mlst_start:u32] each         │
└────────────┴──────────────────────────────────────────┘
 record_size = 1 + 6 * entry_count

Entry semantics

Each entry references a contiguous slice of the MLST array:

 polygons = mlst[mlst_start .. mlst_start + count]

Constraint: mlst_start + count <= header.mlst_polygon_count.

Entries within a leaf represent distinct polygon groups (e.g. different model faces, terrain sections). The full set of visible polygons for a leaf is the union of all its entry slices.

MLST Parser

Flat array of u16_le placed-object visibility IDs. Each entry is an MPSO record index identifying a placed object for visibility determination, not an individual face/polygon index.

fn parse_mlst(reader, data_length: u32) -> Vec<u16>:
    count = data_length / 2
    mlst = []
    for _ in 0..count:
        mlst.push(reader.read_u16_le())
    return mlst

Octree Reconstruction

To build the tree in memory from the flat node list:

fn build_tree(nodes: Vec<OctrNode>) -> OctrNode:
    // Build lookup: byte_offset -> node index
    offset_to_idx = {}
    for (i, node) in nodes.enumerate():
        offset_to_idx[node.byte_offset] = i

    // The root is always the first node (byte_offset 0)
    root = nodes[0]

    // Recursively link children
    fn link(node_idx, nodes, offset_to_idx):
        node = nodes[node_idx]
        for (octant, child_offset) in node.child_refs:
            child_idx = offset_to_idx[child_offset]
            node.children[octant] = link(child_idx, nodes, offset_to_idx)
        return node

    return link(0, nodes, offset_to_idx)

Visibility Query

Given a world-space point, traverse the octree to find which polygons are visible:

fn query_visible(tree: OctrNode, header: OcthHeader, leaves: Vec<PlstLeaf>,
                 mlst: Vec<u16>, point_x: i32, point_y: i32, point_z: i32) -> Set<u16>:

    node = tree
    cx, cy, cz = header.center_x, header.center_y, header.center_z
    half = header.cell_size

    // Walk from root to leaf
    while true:
        // Determine octant for query point
        octant = 0
        if point_z > cz: octant |= 1
        if point_y > cy: octant |= 2
        if point_x > cx: octant |= 4

        // Descend into child
        if node.child_mask & (1 << octant) == 0:
            break   // no child in this octant

        child_offset = node.child_ref_for_octant(octant)
        node = tree.lookup(child_offset)

        // Update center and half-extent for child cell
        half = half / 2
        if point_x > cx: cx += half  else: cx -= half
        if point_y > cy: cy += half  else: cy -= half
        if point_z > cz: cz += half  else: cz -= half

    // Collect visible polygons from the leaf
    visible = Set()
    if node.leaf_ref != 0xFFFFFFFF:
        leaf = leaves.lookup(node.leaf_ref)
        for entry in leaf.entries:
            for i in entry.mlst_start .. entry.mlst_start + entry.count:
                visible.add(mlst[i])

    return visible

SOUP386.DEF

Runtime text definition file that declares the SOUP scripting API surface (functions, references, attributes, and flags).

Overview

SOUP386.DEF is loaded by the runtime and used to build script-call metadata at startup. Compiled script bytecode in RASC/.AI refers to function and flag indices that are resolved using this definition file.

The file is plain text and organized as named sections.

Section Layout

Function index 0 is treated as NullFunction in runtime behavior.

Relationship to RGM Script Data

• RASC and standalone .AI contain compiled script bytecode. No .AI files ship with the game — see SOUP Scripting for details.
• Bytecode function calls encode function IDs (u16 indices).
• Those indices are resolved using the runtime function table built from [functions] in SOUP386.DEF.
• RAAT attribute bytes are interpreted using names declared in the auto … endauto attribute block.

See RGM.md for RASC/RAAT container details and SOUP.md for script-source boundaries.

Notes

• Runtime behavior includes a DEF-to-script compatibility/checksum validation path in the engine.
• Some declared functions do not appear in shipped map scripts; declaration in DEF does not imply invocation.

External References

• RGUnity/redguard-unity soupdeffcn_nimpl.cs
• Dillonn241/redguard-mod-manager MapDatabase.java
• UESP Mod:RGM File Format

Configuration Files

Text-based INI configuration files shipped with the game.

Game Root Directory

Asset Directory Files

SYSTEM.INI

Primary engine configuration file controlling rendering, gameplay, camera, dialog, debug, and 3D subsystem parameters.

Shipped sample path: /Redguard/SYSTEM.INI (e.g. .../GOG Galaxy/Redguard/Redguard/SYSTEM.INI).

File Structure

Standard Windows-style INI file with 10 sections:

1. [screen] — display resolution and palette settings
2. [system] — core engine paths, audio, physics, and HUD layout
3. [debug] — developer diagnostics and logging flags
4. [game] — gameplay physics thresholds and interaction radii
5. [cyrus] — player character movement and control parameters
6. [3dmanager] — 3D object cache and memory budget
7. [xngine] — renderer texture memory, clipping planes, and sky behavior
8. [camera] — camera rig offsets, distances, and glide factors for each mode
9. [dialog] — dialog menu layout and speech settings
10. [3dfx] — Glide/GOG-specific resolution and font scaling overrides

[screen]

Display mode and palette initialization settings.

[system]

Core engine paths, audio configuration, physics constants, HUD element positions, and subsystem enable flags.

world_ini and item_ini point to WORLD.INI and ITEM.INI respectively, which the engine loads for world and item definitions.

[debug]

Developer diagnostics, logging, and display flags. Most are disabled in the shipped build.

network_marker_file=g:\PROJECTS\REDGUARD\DEMO\NETWORK.MRK is a build-time artifact: a hardcoded developer machine path left in the shipped file.

[game]

Gameplay physics thresholds, fall damage, and interaction radii.

[cyrus]

Player character (Cyrus) movement, control, and camera-follow parameters.

[3dmanager]

3D object cache, memory budgets, and manager behavior.

[xngine]

Renderer memory budgets, clipping planes, perspective settings, and sky behavior.

[camera]

Camera rig configuration for all gameplay modes: normal follow, combat, hanging, rope, and debug. Coordinates and angles use engine units. Floating-point glide factors control camera lag.

[dialog]

Dialog menu layout, line limits, and speech settings.