OblivionRemasteredPerformanceFix

Imported from LTSharpe/OblivionRemasteredPerformanceFix (AGENTS.md). Install upstream with npx skills add LTSharpe/OblivionRemasteredPerformanceFix. Copyright stays with the author.

AGENTS.md

Orientation for coding agents (Claude Code, Codex, Cursor, ...) and for people. It is short on purpose: read it first, then open only the doc or source file you need. Plain-language overview: README.md. How to contribute: CONTRIBUTING.md. Repository: https://github.com/LTSharpe/OblivionRemasteredPerformanceFix.

What this repo is

• OblivionPerfFix: one small DLL for Oblivion Remastered (Unreal Engine 5.3, Steam build 19115871). It loads as version.dll next to the game exe (a proxy that forwards to System32\version.dll) or as an OBSE64 plugin, finds the code each fix needs by byte pattern, checks it, and changes it in memory. Every fix does the same work more cheaply: same image, same gameplay. Two exceptions are timing only, in the game's own order: NpcCreationPacing builds far-away, unseen characters a few frames later; CellBufferPacedEvict unloads the cells behind the player a few frames later. A fix whose code does not match switches itself off and logs why.
• A benchmark suite (PowerShell, C# compiled at run time, a UE4SS Lua mod) that starts the game hidden and muted, runs fixed scenes unattended and compares runs. Only needed to measure, not to use the fix.

Layout

Build, test, install

Needs Windows, Visual Studio 2022 or later with the C++ x64 tools (the free Build Tools are enough; build.ps1 finds any edition with vswhere, or set $env:OPF_VCVARS to a vcvars64.bat), PowerShell 5.1+, and Python 3 (standard library only) for tools/*.py.

src\OblivionPerfFix\build.ps1              # -> src\OblivionPerfFix\build\OblivionPerfFix.dll (+ .pdb)
src\OblivionPerfFix\build.ps1 -SelfTest    # also builds and runs the self-test against the installed Steam exe
src\OblivionPerfFix\build.ps1 -SelfTest -Exe <path\to\exe> -OutDir <scratch>   # another exe (e.g. a new game build)
python tools\find_patterns.py              # every byte pattern in src/: matches in the installed exe vs the tested build
tools\GamePaths.ps1                        # where the game, its exe and its config/saves are on this PC

• Self-test output: one PASS/FAIL line per check, then the fixes' own log lines; exit code 1 on any failure. Checks named ... at exe+0x... pin build 19115871 and fail on any other build by design; the "found / applied / hooked" checks are what matter. A fix that is not found gets one FAIL <fix> line ("not installed") and its remaining checks are skipped.
• Install a build: game closed, copy build\OblivionPerfFix.dll to <game>\OblivionRemastered\Binaries\Win64\version.dll and the ini next to it (or tools\Install-PerfFix.ps1). Uninstall = delete both. The DLL writes OblivionPerfFix.log next to itself: the version, the exe's TimeDateStamp, then the fixes' lines, each tagged.

How each fix finds its code

1. Search a byte pattern (hex with ?? wildcards, written in the fix file with the disassembly it expects) in the exe's .text; most must match exactly once.
2. Decode what the match points to (RipTarget for RIP-relative calls and data), check offsets, call targets, vtable slots and struct layouts against what the fix relies on.
3. Only then patch: a few code bytes, a vtable or import slot, a console variable's value, or a call redirected to a stub in free memory within ±2 GB of the code. Anything unexpected: log [tag] ...: fix disabled / not installed / not found and leave the game's code alone. Most fixes re-read the ini every second and can be switched live.

Fix index

The ini key is a fix's stable name (docs and source comments use it). Evidence per fix in docs/research.md, plain words in docs/how-it-works.md, both in this order. All on by default except the diagnostic.

[General] StatsIntervalSeconds writes per-fix counters to the log (default every 60 s). The log keeps the last two sessions as OblivionPerfFix.1.log / .2.log and stops at 8 MB per session (crash report excepted).

Adapting it

A game update broke a fix (the log says not found / disabled for a tag): follow docs/porting.md. Short version: find_patterns.py shows which patterns changed; open that fix file, read the expected disassembly in its comments, find the same code in the new exe, update the pattern and checks, run the self-test, then a benchmark A/B and an image comparison. Run python tools\find_patterns.py --save tools\pattern-baseline.tsv on the build you tested.

Another PC: the fix has no paths and no per-PC settings; helper-thread counts follow the logical processors the game may use, and the helper-heavy fixes stay off below 8 of them (hidden key ParallelMinProcessors). For the benchmark: tools\Setup-Bench.ps1 (pinned UE4SS and PresentMon, SHA-256 checked; UE4SS is in the game folder only while a benchmark game runs), game and Documents paths from tools\GamePaths.ps1 (override with $env:OBLIVION_GAME_DIR / $env:OBLIVION_SAVED_DIR), display/quality profiles in bench/profiles.json (small is the quiet default; native uses the monitor's resolution). tools\Bench-Report.ps1 = stock vs fix, shareable report.

Xbox / PC Game Pass: the DLL accepts OblivionRemastered-WinGDK-Shipping.exe (experimental, untested); it is a separate compile, so expect some patterns to differ. The benchmark is Steam-only.

Rules

• Identical output. A fix may only skip or reorder work when the result is bit-identical ("skip only when nothing changed"), or when the UE 5.3 source shows it is equivalent. No setting that changes the image or the gameplay; the world must never run while the player can't see or act longer than in the stock game. Timing changes like NpcCreationPacing's or CellBufferPacedEvict's need the same bounds (a few frames, the game's order, off-screen only) and an off switch.
• Fail safe. Pattern search plus checks before every write; a clean off with one log line when anything differs; a new ini key gets a safe default; the self-test must pass. Bump OPF_VERSION (core/common.h) and the OBSE64 pluginVersion (core/main.cpp), and add a CHANGELOG.md entry.
• Prove it. Image comparison (tools\Compare-Benchmark.ps1, visual pass) for anything that could touch the picture; benchmark A-B-A for speed (run-to-run noise is about ±10%; trust per-thread ms more than fps).
• Licences. No game files, and no game bytes beyond short search patterns. No Unreal Engine source text: names, offsets and descriptions in your own words are fine, copied engine code or comments are not (python tools\Audit-UESource.py --ue <your UE checkout> src docs checks for copied runs of text).
• Benchmark etiquette. Runs keep the game window hidden and muted. Never minimise the game (it crashes); start the game for measurements only through tools\Run-Benchmark.ps1, which also restores your settings and saves afterwards.

Saving tokens

• tests/selftest.cpp and the larger fix files are long: grep for the fix's Check( lines or its log tag instead of reading them whole. Logs: grep the tag. Benchmark runs: read report.md, not result.json.
• Run tools\Run-Benchmark.ps1 in the background and poll tools\Bench-Status.ps1; its last line is BENCH-RESULT ....