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,16 @@ class StartingBeamVisorAddresses:
     reset_visor: int
 
 
+@dataclasses.dataclass(frozen=True)
+class WidescreenRenderAddresses:
+    # culling_value_address: int
+    culling_original_instruction_address: int
+    culling_custom_frustum_value_offset: int
+    frustum_original_instruction_address: int
+    frustum_insertion_instructions_address: int
+    frustum_custom_frustum_value_offset: int
+
+
 _PREFERENCES_ORDER = (
     "sound_mode",
     "screen_brightness",
@@ -388,6 +398,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 +511,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(widescreen_render_symbols: WidescreenRenderAddresses, dol_file: DolFile, enabled: bool):
+    """
+    Apply widescreen render hack to render the game in 16:9
+    """
+    # Ported from gamemasterplc's 16:9 Aspect Ratio Fix NTSC-U Gecko Code
+    culling_original_instruction_address = widescreen_render_symbols.culling_original_instruction_address
+    culling_custom_frustum_value_offset = widescreen_render_symbols.culling_custom_frustum_value_offset
+    frustum_original_instruction_address = widescreen_render_symbols.frustum_original_instruction_address
+    frustum_insertion_instructions_address = widescreen_render_symbols.frustum_insertion_instructions_address
+    frustum_custom_frustum_value_offset = widescreen_render_symbols.frustum_custom_frustum_value_offset
+
+    if enabled:
+        # Expand frustum culling to prevent things popping in/out at the sides of screen
+        dol_file.write_instructions(
+            culling_original_instruction_address,
+            [
+                lfs(f26, culling_custom_frustum_value_offset, r2)  # Load 2.0f from custom offset
+            ],
+        )
+
+        # Expand frustum view cone to render more horizontally by patching C_MTXFrustum
+        dol_file.write_instructions(
+            frustum_original_instruction_address,
+            [
+                b(
+                    frustum_insertion_instructions_address, relative=False
+                )  # Replace with branch to frustum_function_insertion
+            ],
+        )
+        dol_file.write_instructions(
+            frustum_insertion_instructions_address,
+            [
+                lfs(f19, frustum_custom_frustum_value_offset, r2),  # Load 1.3333334f from custom offset
+                fmuls(f9, f19, f9),
+                fdivs(f11, f10, f9),
+                b(frustum_original_instruction_address + 0x4),  # Return from branch
+            ],
+        )
+
+    else:
+        # TODO Remove when RDV is updated to no longer cache patched DOL files
+        # Restore vanilla behavior when widescreen hack is disabled
+        dol_file.write(culling_original_instruction_address, [0xFF, 0x40, 0x10, 0x90])  # Restore original instruction
+        dol_file.write(frustum_original_instruction_address, [0xED, 0x6A, 0x48, 0x24])  # Restore original instruction
+        dol_file.write(frustum_insertion_instructions_address, (b"\0" * 0x10))  # Remove inserted code

src/open_prime_rando/dol_patching/echoes/dol_versions.py

@@ -13,6 +13,7 @@
     MapDoorTypeAddresses,
     SafeZoneAddresses,
     StartingBeamVisorAddresses,
+    WidescreenRenderAddresses,
 )
 
 ALL_VERSIONS = [
@@ -85,6 +86,13 @@
             map_icon_jumptable=0x803B3638,
         ),
         double_damage_vfx=0x80017F28,
+        widescreen_render=WidescreenRenderAddresses(
+            culling_original_instruction_address=0x8030256C,
+            culling_custom_frustum_value_offset=-0x3490,  # assume r2 = 0x804223c0
+            frustum_original_instruction_address=0x8036D684,
+            frustum_insertion_instructions_address=0x80418E88,
+            frustum_custom_frustum_value_offset=-0x4400,  # assume r2 = 0x804223c0
+        ),
     ),
     EchoesDolVersion(
         game=Game.ECHOES,
@@ -155,5 +163,12 @@
             map_icon_jumptable=0x803B4A80,
         ),
         double_damage_vfx=0x80017FC4,
+        widescreen_render=WidescreenRenderAddresses(
+            culling_original_instruction_address=0x803029E0,
+            culling_custom_frustum_value_offset=-0x34B8,  # assume r2 = 0x804236c0
+            frustum_original_instruction_address=0x8036DAA0,
+            frustum_insertion_instructions_address=0x803B1D60,
+            frustum_custom_frustum_value_offset=-0x4420,  # assume r2 = 0x804236c0
+        ),
     ),
 ]

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
+    """
+    widescreen_assets = custom_asset_path().joinpath("widescreen_hud")
+    for asset_id, filename in WIDESCREEN_HUD_ASSETS.items():
+        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()