Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .github/release-games.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,16 @@
"game_version": "1.2.1",
"build_id": "FF773E90972D544EB79406EAA65396D53C43EFB9",
"layout_count": 129
},
"botw": {
"folder": "the-legend-of-zelda-breath-of-the-wild",
"name": "The Legend of Zelda: Breath of the Wild",
"mod_folder": "Native 4x3 Aspect Ratio",
"zip_stem": "BOTW-4x3-Native",
"title_id": "01007EF00011E000",
"game_version": "1.6.0",
"build_id": "8E9978D50BDD20B4C8395A106C27FFDE",
"layout_count": 4
}
}
}
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ scripts/check_repo.py Blocks game data, keys and decompiler dumps (pre-
docs/DEVELOPMENT.md Dated log of how the mod got here
```

Games: [`super-mario-bros-wonder/`](super-mario-bros-wonder/) (1.2.1).
Games: [`super-mario-bros-wonder/`](super-mario-bros-wonder/) (1.2.1), [`the-legend-of-zelda-breath-of-the-wild/`](the-legend-of-zelda-breath-of-the-wild/) (1.6.0).

## Rules

Expand All @@ -48,7 +48,7 @@ Run before committing a mod change and before every release:
```
python scripts/check_repo.py # game data / keys / dumps (also the pre-commit hook)
python scripts/release.py check <prefix> <version> # release rules: changelog, build ID, allowlist, archive count
# plus the game's own verifiers, listed in its AGENTS.md (SMBW: tools/verify.py and tools/verify_pchtxt.py)
# plus the game's own verifiers, listed in its AGENTS.md (SMBW: tools/verify.py and tools/verify_pchtxt.py; BotW: tools/verify.py)
```

No package manager, build system, linter or type checker: Python scripts run directly. `scripts/` needs only Python 3.8+ (CI uses the runner's 3.12). Game tools may need more (SMBW: Python 3.14 plus `capstone` and `lz4`).
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ Native 4:3 aspect-ratio mods for Nintendo Switch games. "Native" means the game
| Game | Needs game version | Download | Install steps |
| --- | --- | --- | --- |
| Super Mario Bros. Wonder | 1.2.1 | <!-- download:smbw -->[Download v1.2.0](https://github.com/PyroDonkey/switch-4x3-mods/releases/download/smbw-v1.2.0/SMBW-4x3-Native-v1.2.0-for-game-1.2.1.zip)<!-- /download:smbw --> | [Install](super-mario-bros-wonder/README.md#install) |
| The Legend of Zelda: Breath of the Wild | 1.6.0 | <!-- download:botw -->Coming soon<!-- /download:botw --> | [Install](the-legend-of-zelda-breath-of-the-wild/README.md#install) |

Tested on Switch emulators on Windows and Android (Retroid Pocket Nova). Each mod only works with the game version listed, so update your game first. To install, follow the install guide linked for your game in the table above; it also covers updating and troubleshooting.

Expand Down
6 changes: 5 additions & 1 deletion docs/aspect-ratio-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -420,7 +420,11 @@ BOTW 1.6.0 (title ID 01007EF00011E000) on an Eden-family emulator at 4:3, built

**An aspect patch alone is not a 4:3 mod.** With only the code patch, the 3D view is correct but the HUD is laid out for 1280×720 and stretched: the minimap measured about 152 px wide by 202 px tall at the same window height where 16:9 gives a 204 px circle. The layout work is what restores round gauges, undistorted icons and the menu fixes above.

**Game code reads scale on list containers.** In the pause menu, the Adventure Log → Memories list drew row 6 on top of row 5 at 4:3 only. The cause was the 0.75 root-child scale on one container (and the part it holds) whose scale the list code reads. Moving the 0.75 onto its child, or into the part's own layout, did not help; leaving that subtree at stock scale, position and size did. Page containers that the code rewrites still take the factor on their children, but a pane the list code reads has to stay stock, at the cost of that page not being squeezed. A check that the pane stays at stock guards it.
**Game code reads scale on list containers.** In the pause menu, the Adventure Log → Memories list drew row 6 on top of row 5 at 4:3 only. The cause was the 0.75 root-child scale on one container (and the part it holds) whose scale the list code reads. Moving the 0.75 onto its child, or into the part's own layout, did not help; leaving that subtree at stock scale, position and size did. Page containers that the code rewrites still take the factor on their children, but a pane the list code reads has to stay stock. A check that the pane stays at stock guards it. Leaving the page unsqueezed made its text 75% wide and cut long descriptions off, so the factor then went one level lower again: onto the direct root children of the page's part layouts (the detail panel and tabs, and the list's five row slots, whose spacing becomes 52.5 instead of 70). The list containers themselves stay stock, and the list scrolls correctly past row 5. When a container must stay stock, try the panes inside its parts before giving up on the squeeze.

**Keep each capture source the same size as its use.** On the Sheikah map, the earlier fix grew the capture use panes (and the scissor) to the 4:3 height but left their sources at stock. The terrain then drew 1.33× too tall (grid cells 77.5 × 103 px instead of square) and drifted against the correctly placed names and icons whenever the map scrolled. Stock keeps every source and its use at the same size in every pose (720 for the full map, 192 for the mini-map); giving the sources the same 960 fixed it. This pair doesn't follow from the capture note above alone, so when a source/use pair is resized, resize both and check a square reference (a grid) in game.

**Bounds boxes the code reads by name.** The map's "Link is off screen" bubble is clamped to, and only shown outside, a pane named `N_PosSize_00` sized to the 16:9 view minus a margin (1200 × 590). At 4:3 the view is 960 units tall, so the bubble appeared while Link was visible and sat on the wrong edge. Growing the box by the same 240 (margins kept) fixed it. Look for such size-only panes (often named `*Size*` or `*Area*`) whenever an element appears or disappears at the wrong distance from the screen edge.

**Find in-game bugs by reverting layouts in halves.** When the cause is unknown, ship test mods that contain only the changed archive, with every layout in a group left at stock, and let the player test one at a time: all pause layouts stock, then half, then single layouts, then single panes. Each answer halves the search; this one took eight rounds. Keep the code patch fixed while testing, and give each test its own throwaway folder in the emulator's load directory, deleted afterwards.

Expand Down
70 changes: 70 additions & 0 deletions the-legend-of-zelda-breath-of-the-wild/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# Agent instructions: The Legend of Zelda: Breath of the Wild 4:3

Read the root [`../AGENTS.md`](../AGENTS.md) first. This file is the **source of truth for the current state** of the BotW mod; [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) is the dated log of how it got here (its values may be superseded). The general method is in [`../docs/aspect-ratio-guide.md`](../docs/aspect-ratio-guide.md); its "Second reference" section describes this mod.

## Game and target

- Title ID `01007EF00011E000`, **version 1.6.0 only**, build ID `8E9978D50BDD20B4C8395A106C27FFDE`. Tested with both DLC packs installed; without DLC is untested.
- Tested on Eden (yuzu family) on Windows with Graphics > Aspect Ratio > **Force 4:3**. Android and console are untested.
- Mod folder: `mod/Native 4x3 Aspect Ratio/` = `exefs/1.6.0.pchtxt` (exact 4/3, copied from `tools/hand-edited/exefs/1.6.0.pchtxt`) + `romfs/Layout/BootUp.sblarc`, `romfs/Layout/Horse.sblarc`, `romfs/Pack/Bootup.pack` (holds `Layout/Common.sblarc`, almost every UI layout), `romfs/Pack/Title.pack` + `README.txt` (no install steps, only the link to `README.md#install`). Named "Nova Aspect Ratio 4x3 Native" in the maintainer's earlier test builds and "Aspect Ratio 4x3 Native" briefly before v1.0.0; don't rename it again.
- Installed for testing at `%APPDATA%\eden\load\01007EF00011E000\<mod folder>`. Sync with the game closed: `robocopy "mod\Native 4x3 Aspect Ratio" "%APPDATA%\eden\load\01007EF00011E000\Native 4x3 Aspect Ratio" /MIR`. Make sure only one 4:3 folder is ticked in Eden's add-ons (older test folders contain the same archives).
- Releases: tag prefix `botw` (`.github/release-games.json`); procedure in the root AGENTS.md "Releasing". `layout_count` there is the number of files under `romfs/` (4).

## Local inputs (outside the repo)

| Input | Where it comes from | Used by |
| --- | --- | --- |
| romfs 1.6.0 (base + update merged) | `<workspace>\dump\01007EF00011E000\romfs`, extracted from the maintainer's own base and v1.6.0 update NSPs. It contains the DLC-era layouts, so it is not the 1.0.0 base alone | `build.py`, `verify.py` |
| `exefs/main` 1.6.0 | `<workspace>\work\exefs\main` (build ID above) | patch research; `mkpatch.py` (capstone) |

## Build and verify

Python 3.14; stdlib only for build and verify (`-I` is fine). `mkpatch.py` needs `capstone` (run without `-I`).

```
# <out_dir>: a new empty folder outside the repo, with Layout\ and Pack\ subfolders (the build does not create them)
python -I tools/build.py "<workspace>/dump/01007EF00011E000/romfs" <out_dir>
# verify check 20 compares the HUD enlargement against a build with it off:
BOTW_HUD_SCALE=1.0 python -I tools/build.py "<workspace>/dump/01007EF00011E000/romfs" <hud1_dir>
BOTW_HUD_BASE=<hud1_dir> python -I tools/verify.py "<workspace>/dump/01007EF00011E000/romfs" <out_dir> # must print FAILS: 0
# then copy the 4 archives from <out_dir> into mod/Native 4x3 Aspect Ratio/romfs/ (not build_report.json), and
# tools/hand-edited/exefs/1.6.0.pchtxt into its exefs/
python scripts/check_repo.py
python scripts/release.py check botw <version>
```

Environment switches (defaults are the shipped build): `BOTW_ROOT_MODE=children|root`, `BOTW_HUD_SCALE` (1.3333333; 1.0 = off), `BOTW_CURSOR_KEEP` (`Cursor_00`), `BOTW_GANBARI_FIX` (1; 0 = stamina wheel fix off). verify.py reads `build_report.json` from `<out_dir>`, so verify the build folder, not the mod folder.

## Current state (2026-11-10, v1.0.0 prepared, not released)

Code patch: `exefs/1.6.0.pchtxt` replaces the three aspect instructions used by the community 1.6.0 patch (`0x00E0AD68`, `0x015C2148`, `0x01271870`) with `LDR S0` of a literal `3FAAAAAB` (4/3) planted in zero padding after a nearby `ret`. Played and checked.

Layouts (children mode: RootPane untouched because the game overwrites its scale; each direct child of RootPane gets ScaleY and TransY x0.75; panes the code rescales by name, `CODE_SCALE_PANES`, take the factor on their children):

| Area | Rule (curated.py) | Status |
| --- | --- | --- |
| Edge shifts, fills, Title art and glow, loading screens, PauseMenuBG bands | rounds 1-3 | played and checked |
| D-pad icon list edge masks | `CAPTURE_APPLY_INVARIANT`, `SRC_H_SCALE` | played and checked |
| Menu cursor corners | `CURSOR_ROOT_KEEP` (Cursor_00 stock) | played and checked |
| System message pill end caps | `FORCE_SHIFT` MessageSp_00, `SHIFT_FOLLOW` | played and checked |
| HUD at 16:9 size | `HUD_SCALE`, `HUD_PANES` | played and checked |
| Adventure Log page | `NO_SCALE_SUBTREES` N_InOutQuest_02 stock; `PART_SQUASH_Y` (PaPauseQuest_00 panel and tabs, PaPageChallenge5_00 row slots) | played and checked (quest list, description, Memories past row 5); long-list scroll, CLEAR stamp, Memories pictures not yet |
| Sheikah map terrain | `SIZEH_RETARGET` AppMap_00 incl. capture sources N_Capture_00-04 (`MAP_CAPTURE_PAIRS`) | played and checked (grid square, names on terrain) |
| Map player locator | `PART_GROW_H` PaMapPlayer_00 N_PosSize_00 590 -> 830 | played and checked |
| Stamina wheel | `PART_SY` (squash inside the part), `HOST_SY_FACTOR` | played and checked (combined build) |
| Speaker name plate | `FORCE_SHIFT` Message_00 N_NameS_00 + N_Capture_00 | played and checked (combined build) |

The combined build (all rows above, the v1.0.0 mod folder) was played and checked on 2026-11-10: stamina wheel, name plate, Adventure Log and map.

Not yet played: shrine/Divine Beast maps (`AppMapDungeon_00` has the same capture-source/use pattern as the world map and may show the same terrain stretch), tool screen, end credits, a missing menu arrow noted in an early round (cause unknown).

verify.py checks: 0 (no unchanged or stray archive in the output), 1-2 (structure, every changed byte logged), 4-10 (rules re-derived from the originals), 11 (capture use sizes), 12 (Cursor_00 byte-identical), 13-17 (rounds 2-5), 18-19 (pause page containers, Adventure Log subtree stock), 20 (HUD enlargement vs `BOTW_HUD_BASE`), 21 (stamina wheel), 22 (Adventure Log squash).

## Gotchas

- **The game overwrites RootPane scale** (and the scale of panes named in `CODE_SCALE_PANES`), so a root-scale mod is lost at run time. That is why children mode exists.
- **Code reads some pane sizes and scales by name.** The Adventure Log list breaks if its containers (`N_InOutQuest_02`, `Pa_Quest_00`, `N_Cut_00`) are scaled; the map locator clamps to `N_PosSize_00`'s size; the stamina wheel hosts get their ScaleX/ScaleY overwritten by code. Squash below such panes, or grow the box, instead of scaling them.
- **Map captures: keep each source the same size as its use.** Stock keeps them equal in every pose (720 full map, 192 mini-map). With only the uses at 960 the terrain was 1.33x too tall and drifted against names and icons; matching the sources fixed it in game. The guide's capture model (a plain source copies its local size) does not by itself explain this pair; the equal-size rule is what was tested.
- **Bootup.pack is the whole pack** (fonts and other data with it); LayeredFS replaces whole files, which the game-files policy allows for changed archives. Never ship an archive the build did not change (verify check 0).
- **Eden locks layout files while a game runs**, and code patches load only at boot: close the game before syncing. Eden tracks add-ons by folder name, so after a rename tick the new folder and untick old ones.
- The optional map-view exefs patch (`map_view_960`, 720 -> 960 view height at `0x1AFE4`) from round 3 was never enabled or needed; it is not shipped.
16 changes: 16 additions & 0 deletions the-legend-of-zelda-breath-of-the-wild/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Changelog: The Legend of Zelda: Breath of the Wild 4:3

Newest first. Each release's section becomes its GitHub release notes.

## v1.0.0

For game v1.6.0.

First release.

- The 3D view renders at exactly 4:3.
- HUD, menus, loading screens, title screen, dialog boxes and the Sheikah Slate map are re-laid out for the 4:3 screen: elements sit at the real screen edges, full-screen layers cover the whole screen, and nothing is stretched.
- The gameplay HUD (hearts, Divine Beast gauges, weapon and shield icons, sensor, noise meter, temperature and clock) is shown at the same size as on 16:9, and the stamina wheel keeps its round shape.
- Adventure Log: quest text, the quest list and Memories have the correct shape, and long quest descriptions are no longer cut off.
- Map: terrain, place names and icons stay lined up while you move and zoom, and the marker pointing to Link only appears when he is off screen.
- The speaker's name plate sits on its dialog box.
1 change: 1 addition & 0 deletions the-legend-of-zelda-breath-of-the-wild/CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
@AGENTS.md
Loading