PBZ Stutter Fixes 1.1.2
=======================

Fixes stutters in Phantom Blade Zero and makes loading a little faster. Each fix was measured in
game, with and without it, on the same route, fight or menu.

1. Ray tracing stall when new areas load
   With ray tracing on, the game freezes for 0.2-1.1 s as you travel into a new area, while it
   rebuilds its ray tracing pipeline. The fix lets it keep using the current pipeline until the
   new one is ready. Measured: worst frame 110-132 ms -> 18-44 ms (the stall happened in 12 of 12
   runs without the fix, 0 of 4 with it).

2. Combat freezes from Frame Generation
   The game switches DLSS Frame Generation off and back on by itself during fights. Each time it
   comes back on, its GPU resources are rebuilt: a 200 ms freeze. The fix keeps them alive while
   frame generation is off. Measured: worst frame in combat 200-208 ms -> 26-27 ms.

3. Reflex dropping in combat
   When the game turns Frame Generation off, it turns NVIDIA Reflex off too, so input latency
   jumps while you fight. The fix keeps Reflex on. Measured: latency in those moments
   49-51 ms -> about 30 ms. If your game never turns Reflex on (no Frame Generation or VSync),
   the fix leaves it off.

4. Faster loading
   While loading, the game asks Windows about the monitor's display modes about 4,800 times.
   Repeat answers now come from memory: 165 ms -> 10 ms per load.

5. Pauses when closing menus and at autosaves (new in 1.1.0)
   The game's menus run on JavaScript. On PC, closing the menu, map or shrine menu, and every
   autosave, stop the game for a full JavaScript garbage collection. The fix uses the game's own
   gentler settings instead (the PS5 version skips these collections entirely). Measured: worst
   frame after closing the menu 20-22 ms -> 15-16 ms, and no garbage collection during
   autosaves. Autosaves still cost 2-3 slightly long frames (24-30 ms) from the save itself.

Fixes 2 and 3 do nothing without NVIDIA DLSS Frame Generation / Reflex. Fix 1 does nothing with
ray tracing off.


Requirements
------------
- Phantom Blade Zero on Steam. Tested on build 26367565.
- UE4SS for Phantom Blade Zero (OFFICIAL UE4SS for PBZ, Nexus mod 13). Tested with UE4SS 3.0.1.


Install
-------
1. Install UE4SS first and check it works.
2. Extract the zip into the game folder, the one that contains "platform"
   (for example C:\Program Files (x86)\Steam\steamapps\common\PBZ).
3. You should now have PBZ\platform\steam\ue4ss\Mods\PBZStutterFixes\enabled.txt.


Uninstall
---------
Delete the folder PBZ\platform\steam\ue4ss\Mods\PBZStutterFixes.
No game file, save or Engine.ini is changed.


Settings
--------
Open PBZStutterFixes.ini in that folder with a text editor. Every fix can be switched off there.
Each line is explained in the file. Changes apply on the next game start.

Your own console variables go under [CVars], one per line: a number, or true/false.
Lines the mod can't read are skipped and listed in the log.

PBZStutterFixes.log in the same folder shows what the mod did (which settings it applied) and
lists every frame over 40 ms with a summary every 30 s.


How it works
------------
Fixes 1-3 and 5 are engine settings. The game changes its settings at runtime for every area and
cutscene with its own top priority, so an Engine.ini can't hold them. The mod writes them the
same way the game does and checks them again every few frames. Fix 4 hooks one Windows function
(EnumDisplaySettingsW) inside the game. Nothing is written to disk except the mod's own log.


Compatibility
-------------
- Ultra+ has its own ray tracing stutter fix and freezes the game's settings profiles. Use one or
  the other for ray tracing; running both is untested.
- Reflex Unlocked / Reflex Always Enabled do the same thing as fix 3. Running them together is
  harmless but unnecessary.
- If a game update changes the code the mod relies on, it says so in its log and leaves the
  settings alone instead of guessing.


Tested
------
- RTX 4090, Ryzen 7 9800X3D, Windows 11, 5120x1440, max settings, ray tracing on, DLSS with
  Frame Generation and Ray Reconstruction.
- A fixed 45 s traversal route (16 runs), a combat scenario with five enemy types (7 runs), the
  route with ray tracing off, and loading screens.
- 1.1.0: ray tracing off, 50% resolution scale; 24 pause-menu closes and 8 autosaves during
  fights, with and without fix 5; ground-level routes in two regions (no traversal stutter found).
- 1.1.1: [CVars] lines with true/false, spaces, comments and unreadable values, checked in game.
- 1.1.2: Reflex with frame generation on (kept on once the game turns it on) and off (left off).

Not tested
----------
- AMD and Intel GPUs (fixes 2 and 3 are NVIDIA-only anyway).
- Bosses, cutscenes, and long play sessions (including the game's JavaScript memory over hours
  with fix 5).
- Running together with Ultra+.

Source code and measurements: see the mod page.
