XnGine Framework

Reverse engineering and mod support for classic Bethesda-era XnGine titles

Personal reverse engineering project | MO2 plugin framework | Ongoing toward 1.0

Overview

XnGine Framework is a C++ MO2 plugin suite that combines reverse engineering, binary format tooling, and runtime patch orchestration for classic Bethesda XnGine games. The implementation is split between a shared core (src/xngine) and per-game plugin modules (src/games/arena, src/games/battlespire, src/games/daggerfall, and src/games/redguard).

The project is not a thin launcher wrapper. It implements format readers/writers, save integration, mod-data validation, patch discovery, patch application, and defensive diagnostics so legacy game content can be managed through MO2's virtualized workflow without destructive base-install edits.

Technical Stack and Build System

• C++20 codebase with CMake 3.16+ build configuration
• Qt6 (Core/Gui/Widgets) for MO2-facing plugin integration surfaces
• MO2 uibase SDK integration through configurable CMake paths
• vcpkg-managed dependencies including zlib and lz4
• Windows-focused toolchain (Visual Studio Build Tools + Ninja) for plugin build/deploy loops

Historical Significance

This project targets Bethesda's in-house XnGine generation from the mid-to-late 1990s, including games like Daggerfall (1996), Battlespire (1997), and Redguard (1998). That period predates Bethesda's early-2000s transition toward NetImmerse/Gamebryo-era technology (Morrowind released in 2002).

There is also conceptual continuity with later Bethesda tooling. For example, BSA archive usage appears in this earlier era, and archive-centric content packaging remained important in later Bethesda mod ecosystems. While engine internals changed significantly over time, several mod-relevant content-delivery ideas persisted.

Reverse Engineering Focus

The reverse engineering objective is format-level operational coverage: identify mod-relevant formats, decode undocumented structures, and convert that knowledge into parser behavior that survives real mod packages.

• Cross-game format cataloging (shared + game-specific containers, resources, and patch artifacts)
• Binary parser implementation for core formats such as BSA variants, WLD/TBL/RSC-related assets, and game-specific save data
• Compatibility-first parsing strategy with explicit unsupported-format diagnostics instead of silent acceptance
• Validation against real-world mod payloads and observed in-game behavior, not only synthetic test fixtures

Supported games currently include titles such as Arena, Battlespire, Daggerfall, and Redguard, with the broader long-term objective remaining full coverage of mod-relevant formats across the XnGine ecosystem.

Core Architecture and Game Modules

The shared core exposes reusable features for save discovery, mod-data checking, archive operations, and patch tooling. Game modules register specialized behavior on top of that foundation (game IDs, executable layouts, save naming conventions, extension handling, and content signatures).

• GameXngine base behavior: install detection, save scanning, and common archive helpers
• XngineBSAFormat tooling: archive read/write, variant detection, directory unpack, manifest-driven pack
• XngineModDataChecker/XngineModDataContent: conservative safety checks plus per-game content classification
• Per-game registration of features like XngineSaveGameInfo, local-save wiring, and unmanaged-mod handling

Patch Pipeline and Runtime Safety

Patching is implemented as controlled runtime staging. Instead of mutating the base install, patch outputs are generated into temporary MO2-managed output paths, then cleaned up after run completion.

• Patch-family support includes .xdelta, .xdelta3, .vcdiff, .ips, .bps, .ups, and .ppf
• JSON byte-patch catalogs are validated before use (offset parsing, expected/replacement byte checks)
• Patch target candidate ordering uses heuristic scoring (basename, known executable naming, layout hints)
• xdelta tool discovery supports configured paths plus MO2/plugin, modding-root, environment, and PATH fallbacks
• Failure paths are explicit, with actionable warnings when tool discovery or patch application cannot complete

Format Operations and Archive Engineering

Archive handling is implemented as a first-class subsystem, not a one-off utility. BSA workflows include both unpack and pack paths, archive trait customization, known-archive index mapping, and optional manifest files to preserve deterministic archive construction rules.

• BSA read/write error paths validate header/footer layout and index-type constraints
• Known-archive mappings drive safer automatic index-type selection for repack operations
• Extraction can emit manifest metadata for deterministic rebuild and auditability
• Archive extractor features are wired into game modules for game-aware unpack/pack behavior

Mod Intake, Validation, and Defensive Checks

Mod intake logic is intentionally defensive. The pipeline detects patch payloads, classic archive payloads, and risky installer-style payloads (batch/executable/self-extracting patterns) before they are treated as safe content.

• Patch payload detection includes extension checks and named patch-catalog conventions
• Unity-side compatibility signals are handled via explicit payload detection (for limited compatibility modes)
• Installer/extractor keyword heuristics reduce accidental execution-oriented mod ingestion
• Content categorization tags patch instructions, file overrides, audio, textures, config, scripts, and text content

Current State (Toward 1.0)

Current work is in late-stage MVP hardening. Core architecture and major patch flows are implemented across Arena, Daggerfall, Battlespire, and Redguard, with most remaining effort focused on compatibility regression depth, edge-case hardening, and release-stability validation.

Based on the current progress baseline, Arena and Daggerfall are near complete for defined 1.0 MVP scope, Battlespire is in late polish, and Redguard remains the main remaining depth area for format and stability parity.

Architecture: Reverse Engineering to Runtime Patching

Reverse engineered format knowledge is translated directly into runtime patch workflows. Rather than editing installed game files, patched outputs are generated at launch into a temporary hidden mod and removed on game close.

This allows legacy file formats to function within MO2's VFS model while preserving install integrity and supporting normal mod-manager operations like adding, removing, and reordering mods.

• No direct base-game file modification required for patch workflows
• Runtime-generated outputs based on parser and patch pipeline logic
• Consistent behavior with MO2 load-order and virtualized conflict resolution
• Safer testing and cleaner rollback for heavily modded setups

Why The Reverse Engineering Matters

For legacy engines, tooling quality is limited by format understanding. Without reliable reverse engineering, mod management becomes manual, brittle, and difficult to reproduce.

This project improves that foundation by turning undocumented or weakly documented format behavior into usable, testable tooling that fits modern mod workflows.

Remaining 1.0 Milestones

• Cross-game compatibility verification: run curated real-world mod packs through repeatable install/enable/disable/uninstall cycles
• Redguard hardening: close remaining stability and format-depth gaps to match other game modules
• Regression harness expansion: improve scripted replay coverage for patch and save edge cases
• Operational resilience: continue reducing environment-level blockers such as plugin DLL lock deploy interruptions

Completing these items will move the framework from advanced implementation to a release-ready 1.0 baseline with stronger reproducibility and safer long-term maintenance.

Technical Documentation

This project includes direct engineering documentation and implementation references. These are the primary technical sources I use for architecture decisions, compatibility tracking, and reverse-engineering validation.

Primary Documentation

• README.md - project scope, supported games, and high-level structure
• BUILDING.md - build/deploy setup and tooling requirements
• classic_es_file_formats.md - cross-game format catalog and core-vs-game format analysis
• XNGINE_PROGRESS_2026-03-03.md - 1.0 MVP criteria, per-game status, and hardening roadmap

Core Implementation References

• src/xngine/gamexngine.cpp - shared plugin base behavior, save scanning, and archive helper flow
• src/xngine/xnginebsaformat.cpp - BSA read/write, variant detection, unpack/pack pipeline
• src/xngine/xngineexepatch.cpp - patch ingestion, byte-patch validation, and xdelta-family orchestration
• src/xngine/xnginemoddatachecker.h and src/xngine/xnginemoddatacontent.h - baseline mod validation and content classification model

Game-Specific Technical References

• src/games/daggerfall/gamedaggerfall.cpp - Daggerfall game integration and patch pipeline wiring
• src/games/daggerfall/daggerfallsmoddatacontent.cpp - patch payload detection and compatibility gating
• src/games/redguard/gameredguard.cpp - Redguard executable/layout detection and profile integration
• src/games/redguard/redguardsavegame.cpp - low-level Redguard save parsing and validation rules

Repository

View on GitHub