Widescreen HUD Hack Patch for Echoes

src/open_prime_rando/dol_patching/echoes/dol_patcher.py

@@ -20,6 +20,7 @@ class EchoesDolPatchesData:
     unvisited_room_names: bool
     teleporter_sounds: bool
     dangerous_energy_tank: bool
+    widescreen_hack: bool
 
     @classmethod
     def from_json(cls, data: dict):
@@ -33,6 +34,7 @@ def from_json(cls, data: dict):
             unvisited_room_names=data["unvisited_room_names"],
             teleporter_sounds=data["teleporter_sounds"],
             dangerous_energy_tank=data["dangerous_energy_tank"],
+            widescreen_hack=data["widescreen_hack"],
         )
 
 
@@ -67,4 +69,6 @@ def apply_patches(dol_file: DolFile, patches_data: EchoesDolPatchesData):
             version.safe_zone, version.sda2_base, patches_data.safe_zone_heal_per_second, dol_file
         )
         dol_patches.apply_starting_visor_patch(version.starting_beam_visor, patches_data.default_items, dol_file)
+
         dol_patches.apply_map_door_changes(version.map_door_types, dol_file)
+        dol_patches.apply_widescreen_hack(version.widescreen_render, dol_file, patches_data.widescreen_hack)

src/open_prime_rando/dol_patching/echoes/dol_patches.py

@@ -74,6 +74,14 @@ class StartingBeamVisorAddresses:
     reset_visor: int
 
 
+@dataclasses.dataclass(frozen=True)
+class WidescreenRenderAddresses:
+    culling_replacement: int
+    culling_insertion: int
+    viewport_replacement: int
+    viewport_insertion: int
+
+
 _PREFERENCES_ORDER = (
     "sound_mode",
     "screen_brightness",
@@ -388,6 +396,7 @@ class EchoesDolVersion(BasePrimeDolVersion):
     powerup_should_persist: int
     map_door_types: MapDoorTypeAddresses
     double_damage_vfx: int
+    widescreen_render: WidescreenRenderAddresses
 
 
 def apply_fixes(version: EchoesDolVersion, dol_file: DolFile):
@@ -500,3 +509,40 @@ def apply_map_door_changes(door_symbols: MapDoorTypeAddresses, dol_file: DolFile
 
     dol_file.symbols["CTweakAutoMapper::GetDoorColor::DoorColorArray"] = door_color_array
     dol_file.write("CTweakAutoMapper::GetDoorColor::DoorColorArray", DoorMapIcon.get_surface_colors_as_bytes())
+
+
+def apply_widescreen_hack(widescreen_render_symbols: WidescreenRenderAddresses, dol_file: DolFile, enabled: bool):
+    """
+    Apply widescreen render hack to render the game in 16:9
+    """
+    culling_replacement = widescreen_render_symbols.culling_replacement
+    culling_insertion = widescreen_render_symbols.culling_insertion
+    viewport_replacement = widescreen_render_symbols.viewport_replacement
+    viewport_insertion = widescreen_render_symbols.viewport_insertion
+
+    if enabled:
+        dol_file.write_instructions(culling_replacement, [bl(culling_insertion, relative=False)])
+        dol_file.write_instructions(culling_insertion, [lis(r14, 0x4000), stw(r14, 0, r2), lfs(f26, 0, r2), blr()])
+
+        dol_file.write_instructions(viewport_replacement, [b(viewport_insertion, relative=False)])
+        dol_file.write_instructions(
+            viewport_insertion,
+            [
+                lis(r14, 0x3FAA),
+                ori(r14, r14, 0xAAAB),
+                stw(r14, 0, r2),
+                lfs(f19, 0, r2),
+                fmuls(f9, f19, 0, f9),
+                fdivs(f11, f10, f9, 0),
+                b(viewport_replacement + 0x4, relative=False),
+            ],
+        )
+
+        return
+
+    # Restore vanilla behavior when widescreen hack is disabled
+    # To be removed when RDV is updated to no longer cache patched DOL files
+    dol_file.write(culling_replacement, [0xFF, 0x40, 0x10, 0x90])
+    dol_file.write(culling_insertion, (b"\0" * 16))
+    dol_file.write(viewport_replacement, [0xED, 0x6A, 0x48, 0x24])
+    dol_file.write(viewport_insertion, (b"\0" * 28))

src/open_prime_rando/dol_patching/echoes/dol_versions.py

@@ -13,6 +13,7 @@
     MapDoorTypeAddresses,
     SafeZoneAddresses,
     StartingBeamVisorAddresses,
+    WidescreenRenderAddresses,
 )
 
 ALL_VERSIONS = [
@@ -85,6 +86,12 @@
             map_icon_jumptable=0x803B3638,
         ),
         double_damage_vfx=0x80017F28,
+        widescreen_render=WidescreenRenderAddresses(
+            culling_replacement=0x8030256C,
+            culling_insertion=0x80418E8C,
+            viewport_replacement=0x8036D684,
+            viewport_insertion=0x80003748,
+        ),
     ),
     EchoesDolVersion(
         game=Game.ECHOES,
@@ -155,5 +162,11 @@
             map_icon_jumptable=0x803B4A80,
         ),
         double_damage_vfx=0x80017FC4,
+        widescreen_render=WidescreenRenderAddresses(
+            culling_replacement=0x803029E0,
+            culling_insertion=0x803C6C30,
+            viewport_replacement=0x8036DAA0,
+            viewport_insertion=0x803B1D60,
+        ),
     ),
 ]

src/open_prime_rando/echoes/schema.json

@@ -73,6 +73,11 @@
             "description": "Set elevators to be activated on room load",
             "default": false
         },
+        "widescreen_hud": {
+            "type": "boolean",
+            "description": "Enable 16:9 widescreen HUD patch",
+            "default": false
+        },
         "cosmetics": {
             "type": "object",
             "properties": {

src/open_prime_rando/echoes/widescreen_hud/__init__.py

@@ -0,0 +1,18 @@
+from retro_data_structures.base_resource import RawResource
+
+from open_prime_rando.echoes.custom_assets import custom_asset_path
+from open_prime_rando.echoes.widescreen_hud.asset_map import WIDESCREEN_HUD_ASSETS
+from open_prime_rando.patcher_editor import PatcherEditor
+
+
+def apply_widescreen_hud(editor: PatcherEditor):
+    """
+    Replaces certain FRME files to adjust HUD/Visor widgets to better fit a 16:9 screen aspect ratio
+    """
+    for asset_id, filename in WIDESCREEN_HUD_ASSETS.items():
+        widescreen_assets = custom_asset_path().joinpath("widescreen_hud")
+        asset = widescreen_assets.joinpath(filename)
+        if not editor.does_asset_exists(asset_id):
+            continue
+        res = RawResource(type="FRME", data=asset.read_bytes())
+        editor.replace_asset(asset_id, res)

src/open_prime_rando/echoes/widescreen_hud/asset_map.py

@@ -0,0 +1,14 @@
+# https://github.com/Nystrata/EchoesWidescreenHUD/wiki#gguisyspak
+from retro_data_structures.base_resource import AssetId
+
+WIDESCREEN_HUD_ASSETS: dict[AssetId, str] = {
+    # Common
+    0xE6F37215: "FRME_Helmet.FRME",
+    0x88738D60: "FRME_SamusHud1Ball.FRME",
+    # NTSC-U
+    0xEEF43AA1: "FRME_SamusHud1Combat.FRME",
+    0xF7EC0850: "FRME_ScanHudFlat_0.FRME",
+    # PAL
+    0xB5CF0C19: "FRME_SamusHud1Combat_0.FRME",
+    0xD9D58FA5: "FRME_ScanHudFlat_1.FRME",
+}

src/open_prime_rando/echoes_patcher.py

@@ -16,6 +16,7 @@
 from open_prime_rando.echoes.inverted import apply_inverted
 from open_prime_rando.echoes.small_randomizations import apply_small_randomizations
 from open_prime_rando.echoes.suit_cosmetics import apply_custom_suits
+from open_prime_rando.echoes.widescreen_hud import apply_widescreen_hud
 from open_prime_rando.patcher_editor import PatcherEditor
 from open_prime_rando.validator_with_default import DefaultValidatingDraft7Validator
 
@@ -192,6 +193,9 @@ def patch_paks(
 
     apply_custom_suits(editor, configuration["cosmetics"]["suits"])
 
+    if configuration["widescreen_hud"]:
+        apply_widescreen_hud(editor)
+
     # Save our changes
     editor.flush_modified_assets()