# Controls and settings

[← Install](install.md) · [中文](controls.zh-CN.md)

How to play once the app is installed: controllers, keyboard, mouse, rumble, gyro and the settings panel (key 1).

On Mac, a controller's Options/View/Create button requests direct input while assigned to the game or the settings panel, avoiding the system's long-press screenshot delay. Unassigning it from both restores system gesture handling.

On Mac, **Settings (key 1) → Input → Controller input in background** enables controller input while another app has focus, including a browser on another display. It is off by default. A foreground app that supports controllers may also respond to the same input. The choice applies immediately and is saved in `controller-background.txt` (`on` / `off`) next to `controls.txt` for the next launch. Keyboard and mouse input still belongs to the focused game window; switching away releases their held inputs.

On Mac, controllers recognized by macOS (such as DualSense and Xbox controllers) are mapped to a Switch Pro Controller. PlayStation and Xbox face buttons map by position, so each one sits where the game's prompt shows it: the right button is A, the bottom B, the top X and the left Y (Circle / Cross / Triangle / Square; Xbox B / A / Y / X). Nintendo controllers map by label. Key **6** picks the controller type by hand (Xbox or PlayStation: by position, Switch: by label); `TOTK_FACE_BUTTONS=label` maps every controller by label while the type is auto. Rumble and motion require the corresponding features to be exposed by the controller and macOS; not every controller has a gyroscope. A controller to which macOS gives no haptics (it shows up as a generic HID pad) can still rumble: the game then writes the rumble to its HID device from a table of controller profiles (built in: the 8BitDo Ultimate 2 Wireless, firmware 1.03 and later). To add another controller, put one line per controller in `rumble-profiles.txt` next to `controls.txt`: `vendor product report_id length low_offset high_offset [1]` (the optional last 1 says the high motor is the weak one, so the low motor carries the stronger side; decimal or `0x` hex; see the comment above the table in `games/totk/runtime/gamepad_feedback.m`; SDL's HIDAPI drivers show the report of many controllers). Lines worked out from SDL's HIDAPI drivers but **not tried on the controllers** (copy one into `rumble-profiles.txt` and tell us if it works): 8BitDo Pro 3 `0x2dc8 0x6009 0x05 5 1 2` and NVIDIA Shield V103 `0x0955 0x7210 0x01 7 2 4`. Controllers whose report holds fixed command bytes (Xbox 360, GameSir, Flydigi) cannot be written as a profile yet. `TOTK_RUMBLE_HID=0` turns this off; `TOTK_RUMBLE_HID_FLOOR` (0..255) and `TOTK_RUMBLE_HID_HOLD_MS` set how strong and how long the game's faint pulses are made.

**Keyboard and mouse (Mac):** the default layout keeps the left hand on the keyboard and the right hand on the mouse (with mouse mode on, see Mouse below). Keys are physical positions, named after a US layout:

| Action | Switch | Keys | Mouse |
|---|---|---|---|
| Move | left stick | W A S D | |
| Camera | right stick | arrow keys | moving the mouse |
| Confirm, talk, pick up | A | E, Return | |
| Cancel, sprint | B | Shift, Backspace | |
| Jump | X | Space | |
| Attack | Y | G | left button |
| Bow (hold to draw) | ZR | Option | right button |
| Lock on, shield | ZL | Q | wheel click |
| Ability (Breath of the Wild: rune) | L | F | |
| Throw | R | R | |
| Crouch | left stick press | Control, C | |
| Look (first person) | right stick press | V | |
| Menu | + | Esc, I | |
| Map | − | Tab, M | |
| D-pad left / up / right / down | d-pad | 2 / 3 / 4 / 5 | |

While the bow is drawn (ZR held), the attack input shoots instead: hold the right button to draw, click the left one to loose the arrow. To rotate what Ultrahand holds (Tears of the Kingdom: R with the d-pad), hold R and press 2 / 3 / 4 / 5, or, with mouse mode on, the arrow keys: while R is held they drive the d-pad instead of the camera (with mouse mode off they keep turning the camera, which aims a throw). Key **1** opens the settings panel and is not part of the layout. Change any of it in the settings panel's **Key bindings** page (below); it is kept in `keyboard.txt` next to `controls.txt` (`action = input [second input]`, written by the panel; delete it for the default). Scripted input (`TOTK_INPUT_SCRIPT`, `TOTK_INPUT_FILE`, auto-load) keeps a fixed layout of its own (J A, K B, I X, U Y, Return +, Tab −, F T H G the d-pad), so test scripts mean the same keys on every Mac.

Controller layout (Mac): by default the face buttons follow the Switch layout by position: the right button is A, the bottom B, the top X and the left Y on every controller (Nintendo controllers by their labels, which are the same; `TOTK_FACE_BUTTONS=label` maps PlayStation and Xbox controllers by label instead). To change any button, put lines `physical = Switch [mode]` in `~/Library/Application Support/MacNativeGames/TOTK/controls.txt`; lines not given keep the default, `#` starts a comment and `none` leaves a button unused. Physical buttons are named by position: `south` `east` `west` `north` (face buttons), `l1` `r1` `l2` `r2` `l3` `r3`, `menu` (Options / Menu), `view` (Create / View), `up` `down` `left` `right` (d-pad) and `touchpad` (the touchpad click of a DualSense or DualShock 4, unused by default: `touchpad = minus` opens the Purah Pad); with mouse mode on, `mouse_left` `mouse_right` `mouse_middle` `mouse4` `mouse5` (unused here by default: the mouse buttons belong to the keyboard and mouse layout, but a mouse line still drives its Switch button). Switch buttons: `a` `b` `x` `y` `l` `r` `zl` `zr` `plus` `minus` `lstick` `rstick` `up` `down` `left` `right`. The optional mode says how long the Switch button is held: `hold` (default) while the physical button is down, `tap` for 400 ms after each press, and `toggle` on and off at each press, cleared when the left stick returns to center after moving, and `aim <fire button>` while the button is down except while the fire button is also down: `l2 = zr aim r2` draws the bow with L2 and shoots with R2, and R2's own line applies only while L2 is up. The default is the same as this file, which maps by position:

```
east = a
south = b
north = x
west = y
```

To run without holding a button, two lines can drive the run button: `south = b tap` (tap the bottom button again and again, as in GTA) or `l3 = b toggle` (click the stick once and move; it stops when the stick returns to center). The Switch's B is contextual: while climbing, a held B lets go of the wall, so a toggle that is still on when you climb drops the player. Release the stick before climbing, or use `tap`.

The launcher checks the file at every start and names the first bad line in an alert. Delete the file for the default layout. The settings panel's **Key bindings** page writes this file too (only the buttons that differ from the default; comments written by hand are not kept), and its **Reset controller** button deletes it.

**Rumble (Mac, the settings panel):** the game's HD rumble plays on the controller's haptics (for controllers macOS gives haptics, such as the DualSense), on by default. The settings panel (key 1) has a Rumble switch, a Rumble strength menu (0.5× to 4×) and a Gyro aiming switch. A switch acts at once and the strength applies to the next rumble. Turning rumble or gyro on when the game started without it takes effect from the next launch, which the row says. The panel keeps the choices in three one-word files next to `controls.txt`, like `controller-type.txt` and `mouse.txt`: `rumble.txt` (`on` or `off`), `rumble-gain.txt` (the strength, a number above 0 and at most 4, default 1: `2` plays the game's rumble twice as strong, and anything past full strength plays at full strength) and `gyro.txt` (`on` or `off`, see Gyro aiming below). The files can also be written by hand, for example `off` in `rumble.txt` in `~/Library/Application Support/MacNativeGames/TOTK` (`BotW` for Breath of the Wild). `TOTK_RUMBLE`, `TOTK_RUMBLE_GAIN` and `TOTK_GYRO` still win over the files when they are set, and the panel then shows their value greyed out. A Switch Pro Controller or a paired set of Joy-Con rumbles through its own HID reports instead (macOS's haptics do not vibrate them properly; each Joy-Con plays its own side); `off` in `rumble-hid.txt`, or `TOTK_RUMBLE_HID=0`, keeps the haptics for them. A file with a word the game does not know keeps the default and says so in the log; it never stops the game.

**Gyro aiming (Mac):** a controller's motion sensor reaches the game as the Switch Pro Controller's, on by default (the settings panel's Gyro aiming switch, `gyro.txt` saying `off`, or `TOTK_GYRO=0` turns it off). It works with controllers that report motion to macOS (DualSense, DualShock) and with Switch-style Pro Controllers, including 8BitDo pads in Switch mode, whose motion is read from their own HID reports with their factory calibration. The 8BitDo Ultimate 2 Wireless over Bluetooth (firmware 1.03 or later), which macOS adopts without any motion, is read from its HID reports too (`games/totk/runtime/hid_imu.h` lists such controllers). Xbox controllers have no gyroscope, and the generic HID pads macOS does not adopt give buttons and sticks only. Turn on motion controls in the game's options, then aim (a bow, Ultrahand) by turning the controller. `TOTK_GYRO_DEADZONE=<deg/s>` sets the dead zone for small movements, `TOTK_GYRO_AXES` remaps the axes (for example `-x,y,-z`) if a controller turns the wrong way. A controller whose gyro is off at rest (the aim keeps turning on its own, as with some third-party Pro Controllers) is corrected by itself: whenever it lies still for a second, its bias is measured and taken off (the log says `[gyro] bias learned at rest`); put it down for a moment if the aim drifts. `TOTK_GYRO_BIAS=x,y,z` (deg/s, the values that log line prints) fixes the bias instead, and `TOTK_GYRO_BIAS=0` turns the correction off. On iPhone and iPad, see "Touch gyro and haptics" below. Tested on Mac with Tears of the Kingdom.

**DualSense adaptive triggers (Mac):** with a DualSense, R2 (ZR) resists like a bowstring while Link draws the bow, more the further it is pressed, and is slack again the moment the arrow flies or the draw ends; at any other time both triggers are slack, and L2 never resists. The game tells a controller nothing about the bow, so the runtime reads it from the game's memory every 10 ms (`runtime/bow_state.h`, read only; Breath of the Wild 1.9.0 and Tears of the Kingdom 1.4.3, other versions leave the triggers alone). It works over USB and Bluetooth; over Bluetooth the very start of the pull is slack for some 30–45 ms. On by default: the settings panel's (key 1) DualSense bow trigger switch turns it off and on at once and keeps the choice in `dualsense-triggers.txt` next to `controls.txt` (`off` or `on`, which can also be written by hand). `TOTK_DUALSENSE_TRIGGERS=on` / `off` overrides it, and the switch then shows that value greyed out. R2 also lets go at once when a menu or the pause screen opens (Tears of the Kingdom keeps the bow drawn under its menus, so the runtime also reads whether the game has paused Link), while the game loads or shows the title screen, while the settings panel or the on-screen keyboard has the controller, and while the app is in the background; if Link is still drawing afterwards, the bowstring comes back. When the DualSense that had it disconnects, another connected DualSense takes it over. `TOTK_TRIGGER_LOG=1` logs the triggers' mode and status, and why R2 resists or lets go. Tested on Mac with both games, DualSense over Bluetooth.

**Mouse (Mac, the settings panel):** the settings panel's Mouse switch turns mouse mode on and off; the choice is kept for the next launch in `mouse.txt` next to `controls.txt`. While it is on and the game window is in front, the window holds the pointer (hidden, kept in the window); Command-Tab or the settings panel lets it go, and so does a text entry such as naming a horse. Moving the mouse turns the camera: it drives the right stick the way yuzu's "mouse panning" does (written anew here): movement adds to a stick deflection that a 10 ms tick shows to the game and then lets decay, so the camera keeps turning while the mouse moves and settles when it stops. The ability wheel (Tears of the Kingdom, L held: Q on the keyboard) is the exception: while L is held the stick stays where the mouse points it instead of settling back, so the ability it points at stays picked until L is let go; the stick is centred when the wheel opens and again when it closes, and meanwhile the mouse turns neither the camera nor the gyro. The same movement also turns the controller's gyro, so with motion controls on in the game's options, aiming a bow or Ultrahand follows the mouse directly; while mouse mode is on the mouse has the gyro to itself (a controller's motion comes back when it is off). Buttons: left attacks (Y), right draws the bow (ZR) and a left click while it is held shoots, the wheel click locks on (ZL); change them in the settings panel's **Key bindings** page like any key. **Mouse sensitivity** (the settings panel's Input page): a slider from 1 to 100, default 50 (20 points of movement is a full stick deflection), applied at once and kept in `mouse-sensitivity.txt`; it sets how fast the mouse turns the camera, separately from the game's own camera speed. `TOTK_MOUSE_SENSITIVITY` (1–100) decides over the slider, which then shows its value greyed out. Other settings: `TOTK_MOUSE_INVERT_Y=1`, `TOTK_MOUSE_COUNTERWEIGHT` (20: the smallest movement turns at least 20 % of the stick, past the game's dead zone), `TOTK_MOUSE_DECAY` (18) and `TOTK_MOUSE_MIN_DECAY` (6) for how fast the turn settles, `TOTK_MOUSE_GYRO=0` for the stick only.

**Settings panel (Mac, key 1):** key **1** opens and closes the settings panel (Esc or its ✕ close it too; drag its background to move it, and it opens there next time). With a controller, **press both sticks in together (L3 + R3)** (Xbox: LS + RS) to open or close it; from there the game gets no controller input until both are let go. The **Key bindings** page's last row, *Open / close this panel*, can give this to one button instead (the touchpad, say), kept in `controller-settings.txt` next to `controls.txt`; that button then drives nothing in the game, and clearing the row (right-click) or the controller reset brings back L3 + R3. The tabs at the top (or L1 / R1 on a controller) switch between five pages: **Display**, **Input**, **Effects**, **Key bindings** and **Update**; the page shown last opens again. On the Update page up / down scroll the text and left / right pick a button. In the panel the d-pad or left stick moves up and down the rows and left / right changes a value; A (× on PlayStation) picks, B (○) closes. While it is open neither the keyboard and mouse nor a controller reach the game; after it closes, the controller plays again once its buttons and sticks are released. The app's version and the commit it was built from are in the panel's bottom-left corner. Each choice applies at once.

Display:
- **Overlay:** all (the box in the window's top-right corner: FPS with the output and, in brackets, the game's internal 3D resolution, e.g. `FPS 60  1920x1080 (1920x1080)`; shader and render pipeline counts; the load line, GPU first (the game's own share of the GPU), then the CPU cores; accumulated foreground playtime), FPS + playtime, or off. `TOTK_HUD=corners` puts the readings in the picture's corners instead.
- **FPS graph:** a graph of the last 30 seconds' frame rate under the overlay box, off at start. The choice is kept in `fps-graph.txt` next to `controls.txt` (`on` or `off`).
- **Frame lock:** off, 30, 40, 60, 72, 90 or 120 fps, paced exactly (by display refreshes where the rate divides the display's, by its own clock otherwise).
  The choice uses the existing `graphics-frame.txt` beside `controls.txt`: `lock-72` (or another listed rate), `interp-<mode>` or `off`. Lock and interpolation share this one file and exclude each other. An explicit `TOTK_MFX` (including `0`) takes priority at startup and greys out the lock row. No frame-lock shortcut is assigned.
- **Frame interpolation (MetalFX):** off, 30+30, 40+40, 50+50, 60+60 (the game held at 30 / 40 / 50 / 60 fps; 60+60 suits a 120 Hz display, MetalFX makes a frame between each two) or unlimited. Picking frame interpolation turns the frame lock off and the other way round.
- **Resolution:** 720p, 720p + MetalFX upscaling to a 1080p window (the scene still renders at 1280×720; for Macs that cannot hold 1080p), 1080p, 1080p + MetalFX upscaling to the window, 2K (2560×1440, the game's canvas and UI) or 2K + MetalFX upscaling (for 4K screens); 1.4.3 and 1.2.1 also offer **native 4K**: a 3840×2160 canvas, UI and 3D scene (on 1.2.1 the 3D scene follows the canvas at every resolution, as on 1.4.3, in an app built since 2026-11-01). An app built with it reserves its swapchain and texture heaps for 4K at every start (about 1.4 GiB more memory than a 2K app's 416 MiB, whatever is shown), so `build_app.py` builds it by default only on a Mac with 16 GB of memory or more; `--no-native-4k` leaves it out, `--native-4k` builds it on a smaller Mac. On an Apple M4 native 4K took the GPU about 24 ms a frame at Lookout Landing (about 41 fps). The game starts at 1080p until a choice is saved. In a window, the window takes that size at once (as far as the screen holds it). Breath of the Wild (1.6.0 and 1.9.0) has 720p, 1080p, 1080p + MetalFX, 2K, 2K + MetalFX and, in an app built with it (the same rule: by default on a Mac with 16 GB or more), native 4K, its 3D scene at the canvas size; its heaps are sized for 4K in the game code at every start (1.6.0: render targets 912 MiB, memory heap +864 MiB; 1.9.0: GPU heap 448 MiB, memory heap +960 MiB). On 1.9.0, `TOTK_OUTPUT_RES=screen` makes the largest 16:9 size of the main display (up to 5120×2880, limited by the display’s native size) the native choice. Native 5K (5120×2880 canvas, UI and scene) is included in a Tears of the Kingdom 1.4.3 or Breath of the Wild 1.6.0 / 1.9.0 Mac app by default on a build Mac with 32 GB of memory or more; `--native-5k` / `--no-native-5k` override this. A 16 GB or 24 GB Mac keeps the 4K default. A Tears of the Kingdom 5K app reserves about 2.7 GiB more again at every start, even with a lower resolution selected. Adding the option keeps the saved selection; it does not select 5K automatically.
- **Aspect ratio:** 16:9, 16:10, 21:9 or 32:9 (1.2.1 and 1.4.3, Breath of the Wild 1.6.0 and 1.9.0). The camera sees more at the sides (or, at 16:10, keeps its vertical view; `TOTK_ASPECT_VERT=1`, 1.4.3, experimental, sees more above and below instead, with some UI effects in the wrong place); the HUD, menus and map keep their shape in the middle 16:9; markers that follow objects in the world are not moved yet. In a window the window takes the shape; in full screen the picture keeps it, with black bars. `TOTK_ASPECT=2.39` (or `3440x1440`) starts on that ratio and adds it to the list.
- **Edge smoothing (MetalFX Temporal):** temporal anti-aliasing of the 3D scene, off until enabled (`TOTK_TAA=1` starts it on; 1.4.3 and Breath of the Wild); `TOTK_ANISO=16` also turns on 16x anisotropic filtering.
- **Anisotropic filtering:** off (the game's 1×), 2×, 4×, 8× or 16× for the ground, walls and foliage seen at a slant. Applies at once. Kept in `graphics-aniso.txt`; `TOTK_ANISO` decides first.
- **Stronger ambient occlusion:** off by default. 1.5×, 2× or 3× deepens the soft shade the game puts in corners, crevices and where things meet the ground (its ambient occlusion: strength and radius both scaled; 1.5× is the tested level). Tears of the Kingdom 1.2.1 / 1.4.3 and Breath of the Wild 1.9.0 only. Every choice acts at once; off is the game's own shading, unchanged. Kept in `ssao.txt` (`off` or the percent, such as `150`); `TOTK_SSAO_STRENGTH` / `TOTK_SSAO_RADIUS` (percent) decide first, and `TOTK_SSAO=0` keeps the game's own shaders.
- At the bottom right of the Display page, two buttons: **Contribute shaders and pipelines** sends the ones your game met that the shared list lacks (with the GitHub CLI `gh` when it is signed in, in the background; otherwise the GitHub form opens and Finder shows the file to drag in), and **Star the project** opens the GitHub page.

Input:
- **Controller type:** auto (it says what it took the controller for, such as "Auto (PlayStation)"), Xbox, PlayStation or Switch. Xbox and PlayStation map the face buttons by position, Switch by label. Kept in `controller-type.txt` next to `controls.txt`; generic HID pads stay Switch-style. It does not change the button icons in the game's prompts (see `make_button_icons.py`).
- **DualSense bow trigger (R2):** on / off (see DualSense adaptive triggers above; Breath of the Wild 1.9.0 and Tears of the Kingdom 1.4.3).
- **Mouse:** mouse mode on / off, and **Mouse sensitivity**, a slider from 1 to 100 (see Mouse above).
- **Rumble, Rumble strength (0.5× to 4×) and Gyro aiming:** see Rumble and Gyro aiming above.

Effects (Tears of the Kingdom 1.4.3 where a row names no game; each choice acts at once unless it says otherwise):
- **Field of view (FOV):** 0.8× to 1.5× of the game camera's own (its bow and scope zooms scale with it). Kept in `graphics-fov.txt` (×100); `TOTK_FOV_SCALE` decides first. With `TOTK_ASPECT_VERT=1` (Vert+) the FOV stays the game's.
- **Model detail distance (LOD):** 1× (the game's own), 2×, 4×, 10×, 20×, 50×, 100× or **Always the finest** (every model keeps the level it has up close; kept as `max`). A model keeps the detail it would have at 1/K of the distance, so distant trees, towers and rocks stay detailed longer (10× cost about 0.2 ms of GPU time a frame in a field on an M4). Kept in `graphics-lod.txt` (×100); `TOTK_LOD_SCALE` decides first.
- **Render distance:** 1× (the game's own) to 10× the camera's far plane. The game's own (25 000) already spans the whole map, so more shows little or nothing more. Kept in `graphics-far.txt` (percent, such as `300` for 3×); `TOTK_FAR_SCALE` decides first.
- **Shadow resolution:** off (no sun shadows), 1× (the game's own 800 × 800 per cascade), 2×, 3× or 4×: sharper shadow edges at a little more GPU time and memory (4×: four 3200 × 3200 maps). Kept in `graphics-shadow.txt` (×100); off is kept with the effects. `TOTK_SHADOW_SCALE` decides first.
- **Shadow resolution (Breath of the Wild 1.9.0):** as the game has it by default. 2048 gives the sun's shadow map 2048×2048 per cascade instead of the 896×896 docked play uses (the game's four smaller levels all go to 2048, its own maximum): sharper shadow edges, and the light through leaves in small, defined spots. Breath of the Wild 1.9.0 on the Mac only. The game sizes the map when it starts, so the choice takes effect from the next launch. It takes about 24 MiB more of the game's render-target memory; how much of that memory is free is not measured. Kept in `shadows.txt` (`off` or `2048`); `TOTK_SHADOW_RES=2048` (or `0`) decides first.
- **Field of view (Breath of the Wild 1.9.0):** 1× to 1.5× of the main camera's own vertical field of view, changing at once; 1× is the game's own. Tried in play on the Mac: the live change, a wider picture with nothing stretched, and at 1.5× nothing missing at the edges of the view in an open scene on the Great Plateau. Meant to work like 1.4.3's row, its zooms scaling with it; the zooms, ultrawide and cutscenes are not yet confirmed in play. If the game's code at that place is not the expected 1.9.0 code, the field of view stays the game's and the row says the version does not have it; the game still starts. Mac only. Kept in `graphics-fov.txt` (×100), as for 1.4.3; `TOTK_FOV_SCALE` decides first.
- **FXAA anti-aliasing:** on (the game's own) or off: off leaves the 3D picture as the game's tone mapping made it, sharper edges with their stair steps. Kept in `graphics-fxaa.txt`.
- **Anti-aliasing method (TOTK 1.4.3, Mac):** Off / FXAA / SMAA. A separate **Anti-aliasing quality** row follows the method: FXAA has Original (the game's Console variant) / Quality (NVIDIA FXAA 3.11 Quality preset 39); SMAA 1x has Low / Medium / High / Ultra. The quality row is hidden when the method is Off. Each method remembers its own quality, including across launches. The default remains the game's original FXAA; replacements run before upscaling and the UI, without jitter or history frames. SMAA's reference presets use 4 / 8 / 16 / 32 orthogonal search steps; High and Ultra also search diagonals and preserve corners. These are search limits, not repeated full-screen passes. SMAA always uses 400% edge sensitivity (one quarter of the preset's reference threshold) and 100% blend. Saved in `graphics-aa-method.txt`, `graphics-fxaa-quality.txt` and `graphics-smaa-quality.txt`. The existing `graphics-fxaa.txt` preference is preserved when no method is saved. These spatial methods cannot remove all shimmering of subpixel detail in motion. HDR interaction still needs gameplay comparison. Effects pages scroll in short windows, including when navigated with a controller.
- **Depth of field:** on (the game's own) or off: off keeps the camera from taking any depth-of-field request, so cutscenes and events no longer blur the background (they play on as before). Kept in `graphics-dof.txt`.
- **Sharpening:** off, 25 %, 50 %, 75 % or 100 % (FSR 1 RCAS on the 3D picture; the UI drawn after it is not touched), with or without FXAA. Kept in `graphics-sharpen.txt`.
- **Ambient occlusion, Grass, Volumetric fog, Fog:** switches, all on by default. Off leaves out the soft corner shade, the field grass, the ray-marched light in the air, or the layers of haze added over the distance. Kept in `graphics-effects.txt` (the ones that are off). More effects come as they are found.

Update: the version, and either that it is the newest or each newer commit's message (see [install.md](install.md#update-the-app)); when it can be updated for you, an **Update** button that closes the game, updates the app and opens it again; when not, why, and that you update the code and build again yourself.

The overlay shows Session (foreground playtime since this launch, reset on restart) and Total on one line, both in hours and minutes. Only the total is kept per profile in `playtime.json`. Both counters count foreground time after shader warm-up (including menus), pause in the background or during sleep, and run independently of whether the overlay is shown.

The overlay, frame lock or interpolation, resolution, aspect ratio and edge smoothing choices are saved beside `controls.txt` and restored on the next launch. A resolution or aspect ratio is restored once that game's patch is ready, if the choice is available. Explicit `TOTK_MFX`, `TOTK_TAA`, `TOTK_ASPECT`, `TOTK_MFX_OUTPUT`, `TOTK_MFX_UPSCALE`, and a non-automatic `TOTK_OUTPUT_RES` take precedence for that launch.

Key bindings: drawings of a Mac keyboard with the mouse, and of a controller (the switch at the top picks which), with what each key or button does written on it. Keys and buttons in use are coloured by kind (moving and camera, combat, actions, menus and d-pad), key 1 (this panel) has its own colour and unused ones stay grey. The controller drawing follows the controller type: Xbox and Switch put the left stick above the d-pad, PlayStation the d-pad above it with the touchpad; the button names follow it too. Click a key, mouse button (the wheel click and the side buttons too) or controller button, on the drawing or its label, and pick what it does from the menu, or **None**. A key that gets an action leaves the one it had; when the action already has two keys, the new one replaces the second. Nothing swaps, so a line under the drawing lists the actions no key or button drives. With a controller: up / down moves through the keyboard / controller switch, the controller's buttons and the buttons below; left / right changes the picked button's action. **Reset keyboard & mouse** or **Reset controller** goes back to the defaults (deleting `keyboard.txt` or `controls.txt`). The drawings need a wider panel (about 960 × 530 points), which the panel takes on this page only; **Show as list** shows the earlier list instead (two keyboard and mouse boxes and the controller's button per action: click a box, then press the new input; an input in use swaps places; right-click clears), and a window too small for the drawings gets the list.

Nothing in the panel looks picked when it opens: the controller's highlight appears once a controller moves in the panel, and a mouse click hides it again.

Keys 2–7 are no shortcuts any more (2–5 are the d-pad in the default keyboard layout). iPhone/iPad uses touch controls or a compatible game controller and has no settings panel. The touch layout follows a Switch controller: L and ZL at the top left, R and ZR at the top right, − and + between them, the d-pad on the left and A, B, X, Y on the right. The d-pad sits above the left stick and A, B, X, Y above the right stick, and L3 and R3 (stick presses) are in the bottom corners. Touch the left half away from the buttons and drag for the left stick, the right half for the camera (right stick); each stick is centred where your finger goes down. With a game controller connected the touch controls are hidden: touch the screen to show and use them, and they hide again 3 seconds after you lift your fingers.

**Touch gyro and haptics:** with no controller, or one that reports no motion, CoreMotion supplies the game’s six-axis device: the virtual sticks still move and turn the camera, and tilting the phone aims a bow or Ultrahand once motion controls are enabled in the game. Rumble goes to the phone’s Taptic Engine, mixing left and right into one actuator with a perceptual curve and a short hold so small hits are felt (`TOTK_PHONE_HAPTICS_GAIN`, default 1.5). In the system Settings app › Apps › this game, **Phone gyro** and **Phone haptics** are separate switches, both on by default; relaunch the game after changing them. A controller that reports its own motion takes the aiming over; touching the screen hands it back to the phone, and operating that controller’s sticks, triggers or buttons gives it to the controller again. A controller without a gyro never takes it over: the phone keeps aiming. The phone’s sensor runs only while it aims (it stops while a controller’s gyro aims); the phone services stop in the background and motion follows both landscape orientations. `TOTK_PHONE_GYRO=0` / `TOTK_PHONE_HAPTICS=0` still override the corresponding setting through `devicectl`; `TOTK_GYRO=0` / `TOTK_RUMBLE=0` still disable all motion / rumble. Devices without a haptic actuator, such as iPads, do not play phone haptics.

**Ultrawide layouts (optional, 1.4.3):** with a wide aspect ratio the HUD and menus stay in the middle 16:9. To put the HUD in the corners of a 21:9 or 32:9 display instead, make layouts for its shape from your own game files and start with them: `.venv/bin/python scripts/make_romfs_patches.py --version v143 --aspect 3440x1440` (writes `extracted/v143/romfs-patches-3440x1440`; `--hud center` keeps the HUD in the middle) and `scripts/make_output_res_overlay.py 3440x1440 --version v143`, then `TOTK_OUTPUT_RES=3440x1440 TOTK_ASPECT=3440x1440 TOTK_UI_SQUEEZE=0 TOTK_ROMFS_PATCHES=extracted/v143/romfs-patches-3440x1440` (in the work folder). The layouts are read at start, so such a session stays wide; the panel's aspect ratio is not meant for it. Every edited pane is found by name and checked against the value the game ships before it is written.

The menu bar shows the live frame rate as the game's own menu, on the left after the app menu ("60 FPS", or "50+50 FPS" while frame interpolation adds generated frames), whatever the overlay shows in the window; in full screen it is hidden with the menu bar. `TOTK_MENUBAR_FPS=0` leaves the menu bar alone; `TOTK_TITLE_FPS=1` also ends the window's title in the same readout ("… Ver. 1.4.3 — 60 FPS").

Native 2K changes the game's composition canvas and UI to 2560×1440. The 3D scene still follows the game's separate render scaling; this does not force every internal render target to 1440p. The manual MetalFX mode also works in smaller windows and scales to the actual output size, including 4K.

Language: the game and the launcher's own text (startup screen, shader warm-up progress, overlays, keyboard prompt) follow the Mac's language. The launcher text is Chinese on a Chinese Mac and English otherwise. Regional variants follow the console: English outside the Americas (en-GB, en-AU, ...) selects British English, which shows temperatures in Celsius (American English shows Fahrenheit), French in Canada selects Canadian French, Spanish in the Americas Latin American Spanish, and in a 1.4.3 build Brazilian Portuguese selects the game's official pt-BR text. Simplified and Traditional Chinese are told apart by the script (zh-Hans / zh-Hant) or, without one, by the region (Taiwan, Hong Kong and Macau are Traditional). To give only this game another language, choose it in System Settings › General › Language & Region › Applications, or set its preferred language, for example `defaults write org.macnativegames.totk AppleLanguages -array pt-BR` (`defaults delete org.macnativegames.totk AppleLanguages` removes it). To override, launch with `TOTK_LANG` for the game (for example `open --env TOTK_LANG=en-US "Tears of the Kingdom.app"`) or `TOTK_UI_LANG=zh` / `en` for the launcher text.

## Screenshots

The controller's capture button saves a picture of the game's own frame: the square button below the D-pad on a Nintendo controller (read from the controller's HID reports; the Home button stays macOS's own), and macOS's Share button on a DualSense, a DualShock 4 or an Xbox controller. One press, one picture. macOS keeps a Share button for its own screenshot gesture until a game asks otherwise; the game asks, so the button reaches it -- but a shortcut you bound to the button yourself (System Settings › Game Center) keeps it, and then the button takes no picture. The picture is the game picture: the boot screen's text, the FPS box and the settings panel are not in it.

- **iPhone and iPad:** the picture is saved to the system photo library, in the album **Tears of the Kingdom** (or **Breath of the Wild**). Photos asks once for permission to add pictures; refusing it saves nothing, and the note says so.
- **Desktop (macOS, Windows, Linux):** the picture is saved to a folder, the Desktop unless you choose another one. The **Input** page's last row, **Screenshot folder**, opens the system folder chooser; the folder is checked as you pick it (read-only disks and other accounts' folders are refused there, with the reason), and the choice is kept in `screenshot-dir.txt` next to `controls.txt`. A launch's `TOTK_SCREENSHOT_DIR` still decides first; a folder picked in the panel replaces it for that launch too.

A file is named `Tears of the Kingdom 2026-10-30 at 14.05.32.png`, with ` (2)`, ` (3)` … for a second picture in the same second. A line at the bottom of the screen says where the picture went, or why it did not: the folder is gone, not a folder, has no write permission, the path is too long, there is no room, or -- on a phone -- Photos has no permission or the picture is too large.

## Text entry (Mac)

When the game asks for text (naming a horse), the window dims and shows an on-screen keyboard above a text field. Both Tears of the Kingdom and Breath of the Wild use it; no game code is patched. Type on the Mac keyboard as usual (selection, paste and input methods work; Return confirms, Escape cancels), click the keys, or use a controller:

| Action | PlayStation | Xbox | Switch |
|---|---|---|---|
| Move between keys | D-pad / left stick | D-pad / left stick | D-pad / left stick |
| Type the selected key | × | A | A |
| Cancel | ○ | B | B |
| Delete | □ | X | Y |
| Space | △ | Y | X |
| Upper / lower case | L3 | left stick click | left stick click |
| AZERTY / QWERTY | R3 | right stick click | right stick click |
| Move the text cursor | L1 / R1 | LB / RB | L / R |
| Letters / symbols | L2 | LT | ZL |
| Confirm | R2 / Options | RT / Menu | ZR / + |

- The keys show their controller button. The labels follow the controller type (auto or the settings panel's choice), by position, so a remapped `controls.txt` does not get in the way.
- While the keyboard is open the controller types instead of playing; the game gets it back once every button and stick is released.
- The pages hold Latin letters, French accents, digits and punctuation. Other scripts come from the Mac's input methods.
- The text follows the game's limits: its length and the characters it does not allow.
- The keyboard's labels are in Chinese, French or English, following the Mac's language (`TOTK_UI_LANG` overrides it).
- AZERTY is the first choice on a French Mac, QWERTY otherwise. The choice is kept in `keyboard-layout.txt` next to `controls.txt`.
- `python -m unittest tests.test_text_keyboard` checks it without game files; `games/totk/tests/text_keyboard/test.py --preview` opens it to look at.

## Button icons

**Tears of the Kingdom 1.4.3 on Mac:** Settings (key **1**) → Input → **Button prompts**
offers Auto, Keyboard / mouse, Xbox, PlayStation and Switch. Prompts follow the
configured bindings, and binding/style changes apply while playing. Auto follows
the device most recently used. Tutorial images are unchanged. See
[live button prompts](live-button-prompts.md) for coverage and implementation.

`python3.14 games/totk/scripts/make_button_icons.py <mods folder> --app <Tears of the Kingdom.app> --style keyboard` (or `--style xbox`) writes a mod that draws the default keyboard and mouse layout (E, Shift, Space and LMB for A B X Y, W A S D, the arrow keys and so on; add `--bindings <keyboard.txt>` for custom bindings, and `--no-mouse` to use keyboard alternatives) or Xbox buttons (B A Y X in the Switch positions, LB/RB, LT/RT, Menu/View) in the game's button prompts. It redraws the icon font in each language's font archive from your own RomFS (nothing of the game is in the project), so the icons change in every game language, Korean and Chinese included, and writes the manifest, with the game's resource size table grown to fit the larger fonts (without it the game stops at start); files already in the folder are kept. A mod made by an earlier version of the script covers the other languages only: make it again with `--replace`. Needs Python 3.14 and `python3.14 -m pip install fonttools`. If the folder already has a font archive (another mod's, or an earlier run) it stops; `--replace` overwrites it, which is also how to switch styles. The Xbox icons match the default face-button mapping (by position); with `TOTK_FACE_BUTTONS=label` or face buttons changed in `controls.txt` they do not. remove the `Font` folder and `System/Resource/ResourceSizeTable.*` from the mod and run `make_mod_manifest.py` to go back. Prompts drawn as fixed images (some tutorial animations) keep the Switch icons.