How to play once the app is installed: controllers, keyboard, mouse, rumble, gyro and the settings panel (key 1).
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=cornersputs 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.txtnext tocontrols.txt(onoroff). - 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.txtbesidecontrols.txt:lock-72(or another listed rate),interp-<mode>oroff. Lock and interpolation share this one file and exclude each other. An explicitTOTK_MFX(including0) 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, 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.pybuilds it by default only on a Mac with 16 GB of memory or more;--no-native-4kleaves it out,--native-4kbuilds 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=screenmakes the largest 16:9 size of the main display (up to 3456×1944) the native choice. Native 5K (5120×2880 canvas, UI and scene) is also available in a 1.4.3 Mac app built with--native-5k: it reserves about 2.7 GiB more again, so it suits a Mac with 32 GB of memory or more (build_app.pywarns on a smaller one). - 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(or3440x1440) 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=1starts it on; 1.4.3 and Breath of the Wild);TOTK_ANISO=16also 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_ANISOdecides 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(offor the percent, such as150);TOTK_SSAO_STRENGTH/TOTK_SSAO_RADIUS(percent) decide first, andTOTK_SSAO=0keeps 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
ghwhen 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.txtnext tocontrols.txt; generic HID pads stay Switch-style. It does not change the button icons in the game's prompts (seemake_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_SCALEdecides first. WithTOTK_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 ingraphics-lod.txt(×100);TOTK_LOD_SCALEdecides 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 as300for 3×);TOTK_FAR_SCALEdecides 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_SCALEdecides 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(offor2048);TOTK_SHADOW_RES=2048(or0) 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. - 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); 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.
Playtime is kept per profile in playtime.json. It counts foreground time after shader warm-up (including menus), pauses in the background or during sleep, and does not depend on 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.
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.txtdoes 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_LANGoverrides it). - AZERTY is the first choice on a French Mac, QWERTY otherwise. The choice is kept in
keyboard-layout.txtnext tocontrols.txt. python -m unittest tests.test_text_keyboardchecks it without game files;games/totk/tests/text_keyboard/test.py --previewopens it to look at.
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; a layout changed in the settings panel is not drawn) 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.