IFO Format (Module Info Blueprint)

Description: The Module Info (.ifo) is the absolute root metadata file for any environment. It dictates global module behavior, handling everything from the starting spawn location, to the local calendar and time-of-day progression, to script execution for global module events.

At a Glance

Data Model Structure

Rakata maps a Module Info into the rakata_generics::Ifo struct. The struct’s Rustdocs document every field’s binary schema and GFF mapping; the table below is the high-level anatomy.

rakata-lint validates these fields against the engine constraints documented below.

Engine Audits & Decompilation

The following documents the engine’s exact load sequence and field requirements for .ifo files mapped from swkotor.exe.

(Documented from Ghidra decompilation of swkotor.exe. Load path: CSWSModule::LoadModuleStart (0x004c9050). Save-side writers referenced below: SaveModuleFinish (0x004ca680) – which calls SaveModuleIFOStart (0x004c7050), the function that actually writes Mod_ID/Mod_Creator_ID/Mod_Version – SavePlayers (0x004c7870), SaveLimboCreatures (0x004c5bb0).)

Module Identity & Structural Rosters

These fields are written on every module save regardless of save-vs-fresh state – they aren’t part of the save-only state covered further down.

Mod_ID is inert, and the length split is incidental

A vanilla module’s own .ifo (as shipped inside a .mod archive) carries a 16-byte Mod_ID. Every save-game’s bundled module.ifo carries 32 bytes. This isn’t two encodings of one concept, or a save-only extension of the field with meaningful extra data – it’s an artifact of how the engine reads and re-writes an opaque blob it never interprets.

LoadModuleStart reads Mod_ID into a fixed 32-byte destination inside the module object, using a read call capped at 32 bytes regardless of how long the field actually is. A shorter field, like a vanilla module’s 16 bytes, only overwrites the first 16 bytes of that destination – the read does not zero-pad the rest. The destination buffer itself is allocated without any zero-initialization, so whatever the remaining 16 bytes held at allocation time (uninitialized heap memory) is what stays there. Mod_Creator_ID and Mod_Version live immediately adjacent to Mod_ID in this same allocation, purely as a memory-layout convenience; they are distinct GFF fields, not part of Mod_ID itself.

On save, the writer always emits exactly 32 bytes from that same in-memory buffer, unconditionally, regardless of how many of those bytes came from the original file versus leftover heap contents. That is the entire explanation for the observed split: a vanilla .ifo’s 16-byte Mod_ID, once loaded and saved even once, becomes a 32-byte field whose upper half is incidental garbage, not a second logical sub-field with any meaning.

Nothing else in the engine ever reads Mod_ID back out. There is no comparison against the target module’s own file, no hash check, no “does this save belong to this module” validation anywhere – confirmed by an exhaustive check of every reference to the field and the buffer it’s read into. It’s pure write-only round-trip data. Because it’s inert, a tool rewriting module info does not need to preserve its bytes for correctness. But matching the engine’s own behavior exactly means treating it as a genuinely variable-length blob on read, and not attempting to reconstruct a fixed 32-byte shape on write – the engine’s own 32-byte output for a resaved vanilla module is a side effect of an uninitialized buffer, not a format requirement.

Global State Configurations

Time & Cycle Management

Note

Day/Night Cycle Computations The engine continuously computes localized day/night phases explicitly against Mod_DawnHour, Mod_DuskHour, and the current_hour. This dynamically updates an internal state flag denoting: 1=Day, 2=Night, 3=Dawn, 4=Dusk.

Warning

Mod_MinPerHour/Mod_DawnHour/Mod_DuskHour doc comments in rakata’s own code are wrong. crates/rakata-generics/src/ifo.rs currently claims these three default to 2, 6, and 18 respectively. None of that is true against the binary – all three read with a literal default of 0, confirmed directly. The code’s actual behavior (.unwrap_or(0) and the Default impl) already matches the engine; only the doc-comment prose is stale and should be corrected to stop asserting values the implementation doesn’t use.

Global Event Scripts

Each event is a single ResRef field naming a compiled script (.ncs) the engine fires when that event occurs. K1 defines 15 module events:

• Asymmetric I/O (equipping). Mod_OnEquipItem is read during module startup (LoadModuleStart), but SaveModuleIFOStart never writes it back out, so a save-game round-trip silently drops it. In the binary its label sits apart from the other fourteen (which are stored contiguously), matching the one-off handling.
• Absent-field default, all 15. Every script hook, Mod_OnEquipItem included, follows one uniform pattern: read with a locally-constructed empty resref as the default and unconditionally stamped into the module’s script table, no presence check consulted afterward. Mod_OnEquipItem’s asymmetry above is entirely a write-side omission – on the read side it’s handled identically to its 14 siblings.

Note

NWM = NeverWinter Module. Mod_IsNWMFile marks a module as a .nwm-type module, a format the Odyssey engine inherited from BioWare’s Aurora engine (the one behind Neverwinter Nights). When the flag is set, the engine pairs it with Mod_NWMResName and skips re-saving the area ARE static into the module’s save ERF. The skip is narrow: SaveModuleFinish gates the ARE static write behind is_nwm_file == 0, while the GIT is written unconditionally in SaveModuleInProgress. So an NWM save still gets its dynamic GIT, just not a re-copied static ARE .

Safe-State Injection (Save Games Only)

Certain blocks of data inside the .ifo are deliberately evaluated only when the engine is mounting a module directly from a loaded .sav archive block.

Note

No list in this format drops a partially-specified entry. Across Mod_Area_list, Mod_Expan_List, Mod_CutSceneList, Mod_PlayerList, and Mod_Tokens, a struct entry missing one or more of its fields is always kept – each missing field is independently defaulted to a literal (never carried over from a prior entry or a constructed value), and the entry itself is still appended. The only thing that can abort mid-list is a heap-allocation failure, which is an out-of-memory condition that terminates the entire LoadModuleStart call, not a per-entry skip.

More Confirmed-Dead NWN Residue: Mod_VO_ID, Expansion_Pack, Mod_GVar_List

A corpus scan across 117 real module.ifo files (vanilla and save-bundled) turned up three more fields alongside the already-documented Mod_Hak/Mod_IsNWMFile legacy residue, none of which the engine reads or writes anywhere. Confirmed by the same decisive test used elsewhere in this codebase: none of the three field-name strings exist anywhere in swkotor.exe at all, which settles it outright – GFF field access here is string-literal lookup, so a label the binary never spells out can’t be read by LoadModuleStart or written by SaveModuleIFOStart, full stop. There’s no read call site to trace and no absent-field default to give, because there’s no read at all in any of the three cases.

• Mod_VO_ID (CExoString) is the most notable of the three: it carries a value in 98 of the 117 files scanned, the highest live-value density of any unmodeled field found in this codebase’s completeness audits, yet the engine never reads it under any code path. It shares the exact fate of .uti’s already-confirmed-dead VO_ID field: both look like an authoring-side voice-over production lookup key, and neither has a runtime consumer in K1. Model it as dead/toolset-only rather than a live field with a meaningful default.
• Expansion_Pack (WORD) is present in every file and always 0. This is NWN/Aurora expansion-selector residue, consistent with the Mod_IsNWMFile/Mod_Hak precedents on this same format – a real, unrelated Expansion_ID/Expansion_Name pair exists in the binary (used by Mod_Expan_List, already modeled), but Expansion_Pack itself is a different, unread label.
• Mod_GVar_List (List) is present in every file and always empty. K1’s actual campaign-global mechanism lives exclusively in the save-scoped GLOBALVARS.res (GVT ), a completely separate system with no code path connecting it back to this module-scoped field. Mod_GVar_List is NWN module-format residue that happens to share vocabulary with the real mechanism, nothing more.

Implemented Linter Rules (Rakata-Lint)

Phase 1 (intra-resource, no context)

Implemented under rakata_lint::rules::ifo.

1. IFO-001 (Direction Fallback): Warns when Mod_Entry_Dir_X and Mod_Entry_Dir_Y are both 0.0. The engine substitutes a hard fallback heading of (1.0, 0.0) only when Mod_Entry_Dir_Y is absent from the GFF; a value that is present but (0.0, 0.0) is left as a degenerate heading with no facing.
2. IFO-002 (XP Dead-Scaling): Warns when Mod_XPScale == 0. Caveat: a Ghidra trace of K1 shows the engine parses Mod_XPScale but never applies it to awarded XP (the field is inert in swkotor.exe), so a zero has no in-engine effect in K1. The rule only matters if the value is meaningful to another tool.
3. IFO-003 (Eternal Day/Night Bounds): Warns when Mod_DawnHour == Mod_DuskHour. When the two are equal the engine skips the entire dawn/dusk/night computation and locks the phase to 1 (Day), so the module is stuck in perpetual daylight.
4. IFO-004 (Void Area Initialization): Errors when Mod_Area_list is empty; directly faults the load cycle.
5. IFO-005 (Dangling NWM Structure): Warns when Mod_IsNWMFile=true without Mod_NWMResName; evaluates to an unstable execution state.

Phase 2 (resource existence, requires LintContext)

Implemented under rakata_lint::rules::ifo_range.

6. IFO-006 (Resref Existence): Warns when Mod_Entry_Area (.are), any Mod_Area_list[i].Area_Name (.are), or any of the 15 Mod_On* script hooks (.ncs) does not resolve in the configured resource sources.

Pending

• Mod_StartMovie (.bik): No ResourceTypeCode variant for the Bink movie format yet.
• Mod_CutSceneList[i].CutScene_Name: Engine resolution is .dlg or .bik depending on context (audit deferred).