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.description, dol_file, patches_data.widescreen_hack)

src/open_prime_rando/dol_patching/echoes/dol_patches.py

@@ -500,3 +500,50 @@ 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(version_description: str, dol_file: DolFile, enabled: bool):
+    """
+    Apply widescreen render hack to render the game in 16:9
+    """
+    # Ported from gamemasterplc's 16:9 gecko code for NTSC-U
+    match version_description:
+        case "Gamecube NTSC":
+            culling_replacement = 0x8030256C
+            culling_insertion = 0x80418E8C
+            viewport_replacement = 0x8036D684
+            viewport_insertion = 0x80003748
+        case "Gamecube PAL":
+            culling_replacement = 0x803029E0
+            culling_insertion = 0x803C6C30
+            viewport_replacement = 0x8036DAA0
+            viewport_insertion = 0x803B1D60
+        case _:
+            raise NotImplementedError
+
+    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/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,30 @@
+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 FRMEf files to adjust HUD/Visor widgets to better fit a 16:9 screen aspect ratio
+    """
+    if editor.does_asset_exists(0xEEF43AA1) and editor.does_asset_exists(0xF7EC0850):
+        detectedversion = "ntscu"
+    elif editor.does_asset_exists(0xB5CF0C19) and editor.does_asset_exists(0xD9D58FA5):
+        detectedversion = "pal"
+    else:
+        raise NotImplementedError
+
+    for assetversion, assets in WIDESCREEN_HUD_ASSETS.items():
+        if detectedversion == assetversion:
+            widescreen_assets = custom_asset_path().joinpath("widescreen_hud", detectedversion)
+            for asset_id, filename in assets.items():
+                asset = widescreen_assets.joinpath(filename)
+                if not asset.exists():
+                    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,17 @@
+# https://github.com/Nystrata/EchoesWidescreenHUD/wiki#gguisyspak
+from retro_data_structures.base_resource import AssetId
+
+WIDESCREEN_HUD_ASSETS: dict[str, dict[AssetId, str]] = {
+    "ntscu": {
+        0xE6F37215: "FRME_Helmet.FRME",
+        0x88738D60: "FRME_SamusHud1Ball.FRME",
+        0xEEF43AA1: "FRME_SamusHud1Combat.FRME",
+        0xF7EC0850: "FRME_ScanHudFlat_0.FRME",
+    },
+    "pal": {
+        0xE6F37215: "FRME_Helmet.FRME",
+        0x88738D60: "FRME_SamusHud1Ball.FRME",
+        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()