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/