controls.md

Controls and settings

← Install · 中文

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

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. Mac keyboard mappings use physical key positions corresponding to a US layout:

Key	Switch		Key	Switch
W A S D	left stick		arrow keys	right stick
J	A		K, Space	B
I	X (jump)		U	Y (attack)
Q / E	L / R		Option / Shift	ZL / ZR
F T H G	d-pad left / up / right / down		Z / C	left / right stick press
Return	+ (menu)		Tab, Esc	− (map)

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 (the settings panel), mouse_left mouse_right mouse_middle mouse4 mouse5 (the side buttons, unused by default). 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
mouse_left = y
mouse_right = zr aim mouse_left
mouse_middle = zl

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.

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 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. 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. Known limit: Tears of the Kingdom keeps the bow drawn while its menu is open, so R2 keeps resisting there until the menu closes. TOTK_TRIGGER_LOG=1 logs the triggers' mode and status. 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 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, middle targets (ZL); change them in controls.txt like any controller button. Settings: TOTK_MOUSE_SENSITIVITY 1–100 (50: 20 points of movement is a full stick deflection), 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, hold L2 + R2 + L3 for a second (Xbox: LT + RT + LS; Switch: ZL + ZR + left stick click) to open or close it. It takes a second because the same buttons are ZL + ZR + L3 in the game, pressed together for a moment while sneaking with the bow. 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. Each choice applies at once:

• 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, then the CPU cores; and the commit the app was built from), FPS only, 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 or 60 fps, paced exactly (by display refreshes where the rate divides the display's, by its own clock otherwise).
• Frame interpolation (MetalFX): off, 30+30, 40+40, 50+50 (the game held at 30 / 40 / 50 fps, 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). The game starts at 1080p; 1.4.3 keeps the choice for the next start in ~/Library/Application Support/MacNativeGames/TOTK/picture-mode.txt. In a window, the window takes that size at once (as far as the screen holds it). Breath of the Wild 1.9.0 has 1080p and MetalFX only.
• 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 at start (TOTK_TAA=1 starts it on; 1.4.3 and Breath of the Wild); TOTK_ANISO=16 also turns on 16x anisotropic filtering.
• 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 (see Mouse above).
• Rumble, Rumble strength (0.5× to 4×) and Gyro aiming: see Rumble and Gyro aiming above.
• Two buttons at the bottom: 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.

Keys 2–7 are no shortcuts any more. 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 connected, 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 connected controller takes over and stops the phone services; disconnecting hands them back. The 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.

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

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 Mac keyboard keys (J K I U for A B X Y, W A S D, the arrow keys and so on) 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.