# 操作与设置

[← 安装](install.zh-CN.md) · [English](controls.md)

装好 App 之后怎么玩：手柄、键盘、鼠标、震动、体感和设置面板（1 键）。

在 Mac 上，手柄的 Options/View/Create 键被分配给游戏动作或设置面板时，会请求直接接收输入，避免系统等待长按截图而造成延迟。取消这两处的分配后恢复系统手势处理。

Mac 上可在 **设置（1 键）→ 输入 → 后台手柄输入** 开启后台控制，默认关闭。开启后，点击另一个屏幕上的浏览器时，手柄仍可操控游戏；前台其他支持手柄的应用也可能同时响应。选择立即生效，保存在 `controls.txt` 旁边的 `controller-background.txt`（`on` / `off`），重启后保留。键盘和鼠标仍只在游戏窗口获得焦点时控制游戏，切换窗口会释放其按住状态。

在 Mac 上，macOS 能识别的手柄（如 DualSense、Xbox 手柄）会映射为 Switch Pro 手柄。PlayStation 和 Xbox 手柄的四个面键按位置映射，和游戏里的按键提示位置一致：右边是 A、下边是 B、上边是 X、左边是 Y（圆圈 / 叉 / 三角 / 方块；Xbox 的 B / A / Y / X）。任天堂手柄按标签映射。按 **6** 可以手动选手柄类型（Xbox、PlayStation 按位置，Switch 按标签）；类型为自动时，设置 `TOTK_FACE_BUTTONS=label` 可以让所有手柄都按标签映射。震动和体感需要手柄及 macOS 提供对应能力，并非所有手柄都有陀螺仪。macOS 不给震动能力的手柄（显示为通用 HID 手柄）仍然可以震：游戏会按手柄配置表，把震动直接写进它的 HID 设备（内置：8BitDo Ultimate 2 Wireless，固件 1.03 及以上）。要加别的手柄，在 `controls.txt` 旁边的 `rumble-profiles.txt` 里每个手柄写一行：`厂商号 产品号 报告ID 长度 低频偏移 高频偏移 [1]`（最后可选的 1 表示高频马达很弱，由低频马达承担较强的一边；十进制或 `0x` 十六进制；格式见 `games/totk/runtime/gamepad_feedback.m` 里配置表上方的注释；SDL 的 HIDAPI 驱动里能查到很多手柄的报告格式）。下面两行是按 SDL 的 HIDAPI 驱动推出来的，**没有在手柄上试过**（抄进 `rumble-profiles.txt` 试，能不能用请告诉我们）：8BitDo Pro 3 `0x2dc8 0x6009 0x05 5 1 2`，NVIDIA Shield V103 `0x0955 0x7210 0x01 7 2 4`。报告里带固定命令字节的手柄（Xbox 360、GameSir、飞智）暂时写不成配置行。`TOTK_RUMBLE_HID=0` 关闭这个功能；`TOTK_RUMBLE_HID_FLOOR`（0..255）和 `TOTK_RUMBLE_HID_HOLD_MS` 决定游戏里很弱很短的震动被加强多少、多维持多久。

**键盘和鼠标（Mac）：** 默认布局让左手留在键盘上、右手握鼠标（需打开鼠标模式，见下面“鼠标”）。按键指物理键位，按美式布局命名：

| 操作 | Switch | 按键 | 鼠标 |
|---|---|---|---|
| 移动 | 左摇杆 | W A S D | |
| 视角 | 右摇杆 | 方向键 | 移动鼠标 |
| 确认、对话、拾取 | A | E、Return | |
| 取消、冲刺 | B | Shift、Backspace | |
| 跳跃 | X | 空格 | |
| 攻击 | Y | G | 左键 |
| 弓（按住拉弓） | ZR | Option | 右键 |
| 锁定、举盾 | ZL | Q | 滚轮按下 |
| 能力（旷野之息：希卡石） | L | F | |
| 投掷 | R | R | |
| 蹲下 | 左摇杆按下 | Control、C | |
| 主视角 | 右摇杆按下 | V | |
| 菜单 | + | Esc、I | |
| 地图 | − | Tab、M | |
| 十字键 左 / 上 / 右 / 下 | 十字键 | 2 / 3 / 4 / 5 | |

拉弓（按住 ZR）时，攻击键改为射出：按住右键拉弓，点左键放箭。旋转究极手抓着的物体（王国之泪：R 加十字键）：按住 R 再按 2 / 3 / 4 / 5，打开鼠标模式时也可以按方向键：按住 R 期间方向键驱动十字键而不是视角（鼠标模式关闭时方向键仍然转视角，用来瞄准投掷）。**1** 键打开设置面板，不属于按键布局。任何一项都可以在设置面板的 **按键设置** 页里改；布局保存在 `controls.txt` 旁边的 `keyboard.txt`（`操作 = 输入 [第二个输入]`，由面板写入，删掉即恢复默认）。脚本输入（`TOTK_INPUT_SCRIPT`、`TOTK_INPUT_FILE`、自动读档）使用自己固定的布局（J 是 A、K 是 B、I 是 X、U 是 Y、Return 是 +、Tab 是 −、F T H G 是十字键），所以测试脚本在每台 Mac 上都按同样的键。

手柄布局（Mac）：默认按位置对应 Switch 的布局，每种手柄都是右边的面键为 A、下边为 B、上边为 X、左边为 Y（任天堂手柄按标签，结果相同；`TOTK_FACE_BUTTONS=label` 让 PlayStation、Xbox 手柄改为按标签）。要改任何按钮，在 `~/Library/Application Support/MacNativeGames/TOTK/controls.txt` 写 `实体按钮 = Switch 按钮` 的行；没写的按钮保持默认，`#` 开始注释，`none` 表示不用这个按钮。实体按钮按位置命名：`south` `east` `west` `north`（面键），`l1` `r1` `l2` `r2` `l3` `r3`，`menu`（Options / Menu），`view`（Create / View），`up` `down` `left` `right`（十字键），`touchpad`（DualSense / DualShock 4 的触控板按下，默认不用；`touchpad = minus` 打开普尔亚平板）；打开鼠标模式后还有 `mouse_left` `mouse_right` `mouse_middle` `mouse4` `mouse5`（这里默认都不用：鼠标按键属于键盘和鼠标布局，但写了鼠标行的仍会驱动对应的 Switch 按钮）。Switch 按钮：`a` `b` `x` `y` `l` `r` `zl` `zr` `plus` `minus` `lstick` `rstick` `up` `down` `left` `right`。默认布局和下面这个文件相同（按位置）：

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

要不按住就跑，可以让两行驱动奔跑键：`south = b tap`（像 GTA 一样连续点按下方面键，每次按下保持 400 毫秒）或 `l3 = b toggle`（按一下左摇杆再移动；摇杆回到中间时停止）。可选的模式写在 Switch 按钮后面：`hold`（默认，按住时保持）、`tap`、`toggle`，以及 `aim <开火键>`：按住时保持，但开火键也按下时松开。`l2 = zr aim r2` 用 L2 拉弓、R2 射出，L2 松开时 R2 才按自己那一行生效。Switch 的 B 键随情境变化：攀爬时按住 B 会松手，所以攀爬时如果 toggle 还开着，角色会掉下来。攀爬前先松开摇杆，或改用 `tap`。

启动器每次启动都会检查这个文件，有错时弹窗指出第一行错误。删除文件即恢复默认布局。

**震动（Mac，设置面板）：** 游戏的 HD 震动由手柄的触觉马达播放（macOS 提供触觉功能的手柄，如 DualSense），默认开启。设置面板（1 键）里有“震动”开关、“震动强度”（0.5× 到 4×）和“体感瞄准”开关：开关立即生效，强度从下一次震动起生效；游戏启动时没开的震动或体感，打开后从下次启动起生效，该行会写明。面板把选择保存在 `controls.txt` 旁边的三个单词文件里，每次启动沿用，和 `controller-type.txt`、`mouse.txt` 一样：`rumble.txt`（`on` 或 `off`）、`rumble-gain.txt`（震动强度，大于 0、最大 4 的数，默认 1：`2` 让游戏的震动加倍，超过满强度的部分按满强度播放）和 `gyro.txt`（`on` 或 `off`，见下面的体感瞄准）。也可以自己写这些文件，例如在 `~/Library/Application Support/MacNativeGames/TOTK`（旷野之息是 `BotW`）里建 `rumble.txt`，写上 `off`。设置了 `TOTK_RUMBLE`、`TOTK_RUMBLE_GAIN` 或 `TOTK_GYRO` 时，环境变量仍然优先于文件，面板里对应一行显示为灰色的当前值。Switch Pro 手柄和成对的 Joy-Con 改用手柄自己的 HID 报告震动（macOS 的触觉接口震不好它们；左右 Joy-Con 各震自己那一侧）；在 `rumble-hid.txt` 里写 `off`，或设 `TOTK_RUMBLE_HID=0`，它们就仍用系统触觉。文件里写了游戏不认识的内容时保持默认值并写进日志，不会让游戏无法启动。

**体感瞄准（Mac）：** 手柄的陀螺仪会作为 Switch Pro 手柄的体感传给游戏，默认开启（设置面板的“体感瞄准”开关、`gyro.txt` 写 `off` 或设 `TOTK_GYRO=0` 即关闭）。支持向 macOS 提供体感数据的手柄（DualSense、DualShock），以及 Switch 风格的 Pro 手柄（包括 Switch 模式下的 8BitDo），后者直接从手柄自己的 HID 报告读取体感、使用手柄出厂校准。蓝牙连接的 8BitDo Ultimate 2 Wireless（固件 1.03 及以上）macOS 不给它体感，游戏改从它的 HID 报告里读取（`games/totk/runtime/hid_imu.h` 里列着这类手柄）。Xbox 手柄没有陀螺仪；macOS 不认的普通 HID 手柄只有按键和摇杆。在游戏选项里打开体感操作，然后转动手柄瞄准（弓、究极手等）。`TOTK_GYRO_DEADZONE=<度/秒>` 设置小幅转动的死区；转动方向不对时用 `TOTK_GYRO_AXES` 重映射轴向（例如 `-x,y,-z`）。有的手柄静止时陀螺仪也有读数（准星会自己一直转，部分第三方 Pro 手柄就是这样），游戏会自动修正：手柄每静止放一秒，就测出零偏并扣掉（日志里有 `[gyro] bias learned at rest`），准星漂的时候把手柄放下一会儿即可。`TOTK_GYRO_BIAS=x,y,z`（度/秒，即那行日志打印的值）改为固定零偏，`TOTK_GYRO_BIAS=0` 关闭修正。iPhone / iPad 见下面的“手机体感与震动”。已在 Mac 上用王国之泪测试。

**DualSense 自适应扳机（Mac）：** 用 DualSense 时，林克拉弓期间 R2（ZR）会像弓弦一样越按越紧，箭射出或收弓的一刻立即放松；其他时候两个扳机都没有阻力，L2 从不加阻力。游戏不会把拉弓状态告诉手柄，所以运行时每 10 毫秒从游戏内存里读取一次（`runtime/bow_state.h`，只读；支持旷野之息 1.9.0 和王国之泪 1.4.3，其他版本不动扳机）。USB 和蓝牙都能用；蓝牙下拉弓刚开始约 30–45 毫秒还没有阻力。默认开启：设置面板（1 键）里的“DualSense 拉弓扳机”开关可以立即关闭或打开，选择保存在 `controls.txt` 旁边的 `dualsense-triggers.txt`（内容为 `off` 或 `on`，也可以自己写）。`TOTK_DUALSENSE_TRIGGERS=on` / `off` 优先于该文件，此时开关显示为灰色的当前值。打开菜单或暂停画面时 R2 也会立即放松（王国之泪在菜单下会保持拉弓状态，所以运行时还会读取游戏是否暂停了林克）；游戏读取中或在标题画面、设置面板或屏幕键盘占用手柄、应用在后台时同样没有阻力；这些结束后林克若仍在拉弓，弓弦阻力会恢复。持有阻力的 DualSense 断开时，另一个已连接的 DualSense 接手。`TOTK_TRIGGER_LOG=1` 记录扳机的模式和状态，以及 R2 加阻力或放松的原因。已在 Mac 上用两款游戏测试，DualSense 蓝牙连接。

**鼠标（Mac，设置面板）：** 在设置面板里打开或关闭“鼠标操作”，选择保存在 `controls.txt` 旁边的 `mouse.txt`，下次启动沿用。打开时只要游戏窗口在前台，窗口就锁住指针（隐藏，留在窗口里）；按 ⌘Tab 或打开设置面板就释放，给马取名这类文字输入时也会释放。移动鼠标转动视角：按 yuzu“鼠标平移”的思路（这里重新实现）驱动右摇杆，鼠标位移累加成摇杆偏转，每 10 毫秒交给游戏一次然后逐渐衰减，所以鼠标一直移动视角就一直转，停下后平滑停住。能力轮盘（王国之泪，按住 L，键盘上是 Q）例外：按住 L 期间摇杆停在鼠标指向的位置、不会回中，所以指向的能力一直保持选中，直到松开 L；轮盘打开和关闭时摇杆都会回到中心，期间鼠标不转视角也不转陀螺仪。同样的移动也会转动手柄的陀螺仪：在游戏选项里打开体感操作后，拉弓、究极手等瞄准直接跟着鼠标走；鼠标模式开着时陀螺仪只听鼠标的（关掉后恢复手柄的体感）。按键：左键攻击（Y），右键拉弓（ZR）、按住时点左键射出，滚轮按下锁定（ZL）；可以像其他按键一样在设置面板的 **按键设置** 页里改。**鼠标灵敏度**（设置面板的“输入”页）：1 到 100 的滑块，默认 50（移动 20 个点就是摇杆推满），立即生效，保存在 `mouse-sensitivity.txt`；它决定鼠标转动视角的快慢，和游戏自己的镜头速度分开。设了 `TOTK_MOUSE_SENSITIVITY`（1–100）时以它为准，滑块显示为灰色。其他设置：`TOTK_MOUSE_INVERT_Y=1` 上下反转，`TOTK_MOUSE_COUNTERWEIGHT`（默认 20：最小的移动也至少推动摇杆的 20%，越过游戏的死区），`TOTK_MOUSE_DECAY`（18）和 `TOTK_MOUSE_MIN_DECAY`（6）调整停下来的快慢，`TOTK_MOUSE_GYRO=0` 只用摇杆、不用陀螺仪。

**设置面板（Mac，1 键）：** 按 **1** 打开或关闭设置面板（Esc 或右上角 ✕ 也能关；按住面板空白处可以拖动，下次在同一位置打开）。用手柄时，**同时按下两个摇杆（L3 + R3）**（Xbox：LS + RS）打开或关闭面板；之后游戏收不到手柄输入，直到两个都松开。在**按键设置**页最后一行“打开 / 关闭设置面板”里可以改成一个键（比如触控板），保存在 `controls.txt` 旁边的 `controller-settings.txt`；这个键之后不再给游戏用，右键清除这一行或恢复手柄默认，就回到 L3 + R3。顶部的标签（手柄上用 L1 / R1）在五页之间切换：**画面**、**输入**、**画面效果**、**按键设置**、**更新**；下次打开显示上次的那一页。「更新」页里上下滚动文字，左右选按钮。面板里用十字键或左摇杆上下选行、左右改值，A（PlayStation 是 ×）确定，B（○）关闭。面板开着时键盘、鼠标和手柄都不会传给游戏；关掉后，松开手柄所有按键和摇杆，手柄就又回到游戏。App 的版本和打包时的提交号显示在面板左下角。每一项选了立刻生效。

画面：
- **性能信息：** 全部（窗口右上角的小框：FPS 和分辨率——先输出分辨率，括号里是游戏的内部 3D 分辨率，如 `FPS 60  1920x1080 (1920x1080)`——、着色器和渲染管线计数、负载一行（GPU 在前，是游戏自己占用 GPU 的比例；后面是 CPU 各核心）、累计前台游玩时间）、FPS 与游玩时间、关。`TOTK_HUD=corners` 改为画在画面四角。
- **帧率图：** 在叠加框下面画最近 30 秒的帧率曲线，默认关。选择保存在 `controls.txt` 旁边的 `fps-graph.txt`（`on` 或 `off`）。
- **锁帧：** 关、30、40、60、72、90、120 帧，帧率严格锁定（能整除显示器刷新率时按刷新节拍，否则按自己的时钟）。
  设置保存在 `controls.txt` 旁已有的 `graphics-frame.txt`：`lock-72`（或其他列出的帧率）、`interp-<档>` 或 `off`。锁帧与补帧共用该文件且互斥。显式设置 `TOTK_MFX`（包括 `0`）时，启动优先使用环境变量，锁帧行置灰。暂不分配锁帧快捷键。
- **补帧（MetalFX）：** 关、30+30、40+40、50+50、60+60（游戏锁在 30 / 40 / 50 / 60 帧，MetalFX 在每两帧之间补一帧；60+60 适合 120 Hz 屏幕）、不限帧。选了补帧会自动关掉锁帧，反过来也一样。
- **分辨率：** 720p、720p + MetalFX 放大（场景仍按 1280×720 渲染，放大到 1080p 窗口）、1080p、1080p + MetalFX 放大到窗口、2K（2560×1440，游戏画布和界面）、2K + MetalFX 放大（4K 屏）；1.4.3 和 1.2.1 还有一项**原生 4K**：3840×2160 的画布、界面和 3D 场景（1.2.1 和 1.4.3 一样，3D 场景在各个分辨率下都跟随画布，2026-11-01 以后打的 App 才有）。带它的 App 每次启动都按 4K 预留交换链和贴图堆（不管实际显示多大，都比 2K App 的 416 MiB 多约 1.4 GiB 内存），所以 `build_app.py` 只在 16 GB 及以上内存的 Mac 上默认带上；`--no-native-4k` 不带，`--native-4k` 在内存更小的 Mac 上也带。Apple M4 上原生 4K 在监视堡垒每帧 GPU 约 24 ms（约 41 帧）。首次开局是 1080p，选择会保留到下次启动。窗口模式下窗口立刻变成对应大小（屏幕放不下就缩小）。旷野之息（1.6.0 和 1.9.0）有 720p、1080p、1080p + MetalFX、2K、2K + MetalFX，以及带 4K 打的 App 里的原生 4K（规则相同：16 GB 及以上内存的 Mac 默认带），3D 场景跟随画布；它的堆在游戏代码里每次启动都按 4K 设好（1.6.0：渲染目标 912 MiB、内存堆 +864 MiB；1.9.0：GPU 堆 448 MiB、内存堆 +960 MiB）。1.9.0 设 `TOTK_OUTPUT_RES=screen` 时，“原生”一档是主显示器最大的 16:9 尺寸（最高 5120×2880，受屏幕原生尺寸限制）。 王国之泪 1.4.3 和旷野之息 1.6.0 / 1.9.0 Mac App 在构建机器有 32 GB 及以上内存时默认带上原生 5K（5120×2880 的画布、界面和场景），`--native-5k` / `--no-native-5k` 可手动覆盖；16 GB、24 GB 保持默认 4K。王国之泪带 5K 的 App 每次启动再多预留约 2.7 GiB 游戏内存，即使选择较低分辨率也一样。新增选项会保留上次选择，不会自动切到 5K。
- **画面比例：** 16:9、16:10、21:9、32:9（1.2.1、1.4.3、旷野之息 1.6.0 和 1.9.0）。相机两侧看到更多（16:10 时保持纵向视野；`TOTK_ASPECT_VERT=1`，1.4.3，实验性，改为上下看到更多，部分界面特效位置不对）；HUD、菜单和地图保持原比例、在中间 16:9；跟随世界物体的标记暂时不跟着移。窗口模式下窗口变成这个形状，全屏时画面保持这个比例、四周留黑边。`TOTK_ASPECT=2.39`（或 `3440x1440`）从这个比例开局，并加进列表。
- **边缘平滑（MetalFX 时间性）：** 3D 场景的时间性抗锯齿，首次启动时关闭，之后记住选择（`TOTK_TAA=1` 开局就开；1.4.3 和旷野之息）；`TOTK_ANISO=16` 另外打开 16 倍各向异性过滤。
- **各向异性过滤：** 关（游戏原样 1×）、2×、4×、8×、16×，让斜看的地面、墙面、植被更清楚。立即生效。保存在 `graphics-aniso.txt`；设了 `TOTK_ANISO` 时以它为准。
- **环境光遮蔽增强：** 默认关。1.5×、2×、3× 加深游戏在墙角、缝隙和物体着地处画的柔和阴影（环境光遮蔽，强度和范围一起放大；1.5× 是测过的档位）。只有王国之泪 1.2.1 / 1.4.3 和旷野之息 1.9.0。每个选择都立即生效；关就是游戏原样，画面不变。保存在 `ssao.txt`（`off` 或百分数，如 `150`）；设置了 `TOTK_SSAO_STRENGTH` / `TOTK_SSAO_RADIUS`（百分数）时以环境变量为准，`TOTK_SSAO=0` 保留游戏原来的着色器。
- “画面”页右下角两个按钮：**贡献着色器和管线** 把游戏遇到、公共清单里还没有的着色器和管线发出去（这台 Mac 登录了 GitHub 命令行 `gh` 时在后台直接提交；否则打开 GitHub 提交页，并在访达里显示文件，拖进去即可）；**给作者点赞** 打开 GitHub 项目页。

输入：
- **手柄类型：** 自动（会写出认出的手柄，如“自动（PlayStation）”）、Xbox、PlayStation、Switch。Xbox 和 PlayStation 按位置映射面键，Switch 按标签。记在 `controls.txt` 旁边的 `controller-type.txt`；通用 HID 手柄保持 Switch 式。游戏里提示的按键图标不跟着变（见 `make_button_icons.py`）。
- **DualSense 拉弓扳机（R2）：** 开 / 关（见上面“DualSense 自适应扳机”；旷野之息 1.9.0 和王国之泪 1.4.3）。
- **鼠标操作：** 鼠标模式开 / 关，以及 **鼠标灵敏度**，1 到 100 的滑块（见上面“鼠标”）。
- **震动、震动强度（0.5× 到 4×）和体感瞄准：** 见上面“震动”和“体感瞄准”。

画面效果（没写游戏的是王国之泪 1.4.3；除非另有说明，每项立即生效）：
- **视野（FOV）：** 游戏相机自身视野的 0.8× 到 1.5×（拉弓、望远镜的缩放按比例跟着变）。保存在 `graphics-fov.txt`（×100）；设了 `TOTK_FOV_SCALE` 时以它为准。开了 `TOTK_ASPECT_VERT=1`（Vert+）时视野保持游戏原样。
- **模型细节距离（LOD）：** 1×（游戏原样）、2×、4×、10×、20×、50×、100×，或 **始终最高精度**（每个模型一直用它在近处的那一级，保存为 `max`）。模型在某个距离用的精度，等于原来在 1/K 距离处的精度，远处的树、塔、岩石更晚变粗（M4 上草地里 10× 每帧多约 0.2 ms GPU）。保存在 `graphics-lod.txt`（×100）；设了 `TOTK_LOD_SCALE` 时以它为准。
- **渲染距离：** 相机远裁剪面的 1×（游戏原样）到 10×。游戏原本的 25000 已经覆盖整张地图，所以调大可能看不出更多东西。保存在 `graphics-far.txt`（百分数，如 3× 存为 `300`）；设了 `TOTK_FAR_SCALE` 时以它为准。
- **阴影分辨率：** 关（没有太阳阴影）、1×（游戏原样，每级 800×800）、2×、3×、4×：阴影边缘更清楚，GPU 时间和显存略增（4× 是四张 3200×3200）。保存在 `graphics-shadow.txt`（×100）；“关”和其他效果开关存在一起。设了 `TOTK_SHADOW_SCALE` 时以它为准。
- **阴影分辨率（旷野之息 1.9.0）：** 默认游戏原样。选 2048 时太阳阴影贴图每级为 2048×2048，而不是主机模式下的 896×896（游戏较小的四档都改成 2048，即它自己的上限）：阴影边缘更清晰，透过树叶的光斑更小、更清楚。只有 Mac 上的旷野之息 1.9.0。游戏在启动时确定贴图大小，所以选择从下次启动生效。它多用游戏渲染目标内存约 24 MiB；这部分内存还剩多少没有测过。保存在 `shadows.txt`（`off` 或 `2048`）；设置了 `TOTK_SHADOW_RES=2048`（或 `0`）时以环境变量为准。
- **视野（旷野之息 1.9.0）：** 主相机自身纵向视野的 1× 到 1.5×，立即生效；1× 是游戏原样。已在 Mac 上实际试过：即时生效、画面更宽且没有拉伸，1.5× 时在初始台地的一处开阔场景里画面边缘没有缺东西。设计上和 1.4.3 那一项一样，缩放跟着按比例变；缩放、超宽屏和过场还没有在游戏里确认。如果那里的游戏代码不是预期的 1.9.0 代码，视野保持游戏原样，这一项显示这个版本没有；游戏照常启动。只有 Mac。和 1.4.3 一样保存在 `graphics-fov.txt`（×100）；设了 `TOTK_FOV_SCALE` 时以它为准。
- **FXAA 抗锯齿：** 开（游戏原样）/ 关：关掉后 3D 画面保持色调映射后的样子，边缘更清楚，也会有锯齿。保存在 `graphics-fxaa.txt`。
- **抗锯齿方式（Mac、王国之泪 1.4.3）：** 关 / FXAA / SMAA。独立的**抗锯齿质量**一行跟随所选方式：FXAA 可选原版（游戏的 Console 版本）或 Quality（NVIDIA FXAA 3.11 Quality 预设 39）；SMAA 1x 可选 Low / Medium / High / Ultra。关闭抗锯齿时隐藏质量行。两种方式分别记住自己的质量，重新启动后也保留。默认仍是游戏原版 FXAA；替代算法在放大与 UI 之前处理，不移动几何、不积累历史帧。SMAA 预设的水平/垂直搜索上限分别为 4 / 8 / 16 / 32，High 和 Ultra 还有对角线与拐角检测；这些数字不是全屏处理的重复次数。SMAA 固定为 400% 边缘敏感度（参考阈值的四分之一）和 100% 混合比例。保存在 `graphics-aa-method.txt`、`graphics-fxaa-quality.txt` 和 `graphics-smaa-quality.txt`。没有保存方式时保留已有 `graphics-fxaa.txt` 设置。这些空间算法不能消除运动中所有细小物体的闪烁，HDR 组合仍需实际游玩对比。窗口较矮时效果页可滚动，手柄导航也会保持当前行可见。
- **景深：** 开（游戏原样）/ 关：关掉后镜头不再接受任何景深请求，过场和事件不再把背景虚化（剧情照常进行）。保存在 `graphics-dof.txt`。
- **锐化：** 关、25%、50%、75%、100%（对 3D 画面做 FSR 1 RCAS，之后画的 UI 不受影响），FXAA 开关都可以用。保存在 `graphics-sharpen.txt`。
- **环境光遮蔽、草、体积雾、雾效：** 开关，默认都开。关掉分别去掉墙角的柔和阴影、野外的草、空气中光线步进算出的体积光雾、叠在远处的雾气层。保存在 `graphics-effects.txt`（记关掉的那些）。找到更多效果后会继续加。

更新：当前版本，以及“已是最新版”或每个新提交的说明（见 [install.zh-CN.md](install.zh-CN.md)）；能替你更新时有**更新**按钮，点了会关闭游戏、更新 App 并重新打开；不能时说明原因，请你自己更新代码、重新编译。

性能信息在同一行显示本次游玩时间和累计游玩时间，均以小时和分钟显示。本次时间每次启动归零，仅累计时间按用户配置保存在 `playtime.json`。着色器预热完成后开始累计游戏窗口处于前台的时间（包括菜单），切到后台或休眠时暂停，关闭性能信息显示也会继续计时。

性能信息、锁帧或补帧、分辨率、画面比例和边缘平滑的选择保存在 `controls.txt` 旁，下次启动恢复。分辨率和画面比例会等该版本的补丁准备好后再恢复，且只应用支持的选项。显式设置的 `TOTK_MFX`、`TOTK_TAA`、`TOTK_ASPECT`、`TOTK_MFX_OUTPUT`、`TOTK_MFX_UPSCALE` 和非自动的 `TOTK_OUTPUT_RES` 优先于保存的选择。

按键设置：画出 Mac 键盘和鼠标，以及手柄（顶部的切换选择看哪一个），每个按键或按钮上直接写着它的功能。正在使用的按键按类别着色（移动和视角、战斗、动作、菜单和十字键），1 键（这个面板）单独着色，没用的保持灰色。手柄图跟随手柄类型：Xbox 和 Switch 左摇杆在十字键上方，PlayStation 十字键在上方并画出触控板；按钮名称也随之变化。点图上的按键、鼠标按键（滚轮按下和侧键也可以）或手柄按钮（点它的说明文字也行），在弹出的菜单里选它的功能，或选 **无**。按键换了功能就离开原来的功能；目标功能已有两个按键时，新的替换第二个。不会互换，所以图下方会列出没有任何按键或按钮的功能。用手柄时：上下在键盘 / 手柄切换、手柄的各个按钮和下面的按钮之间移动，左右改选中按钮的功能。**恢复默认键鼠按键** 或 **恢复默认手柄按键** 回到默认（删除 `keyboard.txt` 或 `controls.txt`）。图示需要更宽的面板（约 960 × 530 点），只在这一页这样显示；**以列表显示** 改回原来的列表（每个操作两个键鼠格子加手柄按钮：点格子再按新的输入；已被占用的会互换；右键清除），窗口太小放不下图示时也显示列表。

面板刚打开时什么都不显示为选中：用手柄在面板里操作后才出现手柄的高亮框，点一下鼠标它就消失。

2–7 键不再是快捷键（默认键盘布局里 2–5 是十字键）。iPhone / iPad 使用触屏控件或兼容手柄，没有设置面板。触屏按 Switch 手柄排布：左上 L、ZL，右上 R、ZR，中间 − 和 +，左边十字键，右边 A、B、X、Y。十字键在左摇杆上方，A、B、X、Y 在右摇杆上方，L3、R3（按下摇杆）在左下角和右下角。在左半屏避开按钮的地方按住拖动是左摇杆，在右半屏是转镜头（右摇杆）；摇杆以手指按下的位置为中心。接上手柄时触屏控件自动隐藏：碰一下屏幕就会显示，可以照常使用，手指离开 3 秒后再次隐藏。

**手机体感与震动：** 没有连接手柄时，手机的 CoreMotion 传感器作为游戏的六轴设备：虚拟摇杆照常移动、转视角，在游戏选项里打开体感操作后，倾斜手机即可瞄准弓或究极手。游戏震动交给手机的 Taptic Engine，左右两路混合成一路，并用感知曲线和短保持让小幅震动也能被感觉到（`TOTK_PHONE_HAPTICS_GAIN`，默认 1.5）。系统“设置”App › App › 本游戏中有“手機體感”和“手機震動”两个独立开关，默认开启，修改后重新启动游戏生效。接上手柄后手机自动让位、停止，断开后恢复；进后台停止，并随左右横屏方向调整体感轴向。`TOTK_PHONE_GYRO=0` / `TOTK_PHONE_HAPTICS=0` 仍可通过 `devicectl` 覆盖对应设置；`TOTK_GYRO=0` / `TOTK_RUMBLE=0` 仍分别关闭全部体感 / 震动。iPad 等没有触觉马达的设备不播放手机震动。

**超宽屏界面布局（可选，1.4.3）：** 选了宽画面比例时 HUD 和菜单留在中间 16:9。想让 HUD 贴到 21:9 或 32:9 屏幕的四角，可以用你自己的游戏文件按屏幕比例生成布局再启动：`.venv/bin/python scripts/make_romfs_patches.py --version v143 --aspect 3440x1440`（写到 `extracted/v143/romfs-patches-3440x1440`；`--hud center` 让 HUD 留在中间）和 `scripts/make_output_res_overlay.py 3440x1440 --version v143`，然后用 `TOTK_OUTPUT_RES=3440x1440 TOTK_ASPECT=3440x1440 TOTK_UI_SQUEEZE=0 TOTK_ROMFS_PATCHES=extracted/v143/romfs-patches-3440x1440` 启动（在工作目录里）。布局在启动时读取，所以这一局一直是宽屏，不配合面板里的画面比例使用。每个要改的界面面板都按名字查找，写入前核对游戏原版的值。

菜单栏左侧、应用菜单之后以游戏自己的菜单显示实时帧率（“60 FPS”，补帧显示生成帧时为“50+50 FPS”），与窗口里的性能信息显示什么无关；全屏时随菜单栏隐藏。`TOTK_MENUBAR_FPS=0` 不在菜单栏显示；`TOTK_TITLE_FPS=1` 时窗口标题末尾也显示同样的帧率（“… Ver. 1.4.3 — 60 FPS”）。

原生 2K 将游戏合成画布和 UI 改为 2560×1440，3D 场景仍由游戏独立的渲染比例控制，并非强制所有内部通道以 1440p 渲染。手动 MetalFX 在较小窗口中也可使用，输出放大会跟随实际窗口尺寸，包括 4K。

语言：游戏和启动器自身的文字（启动画面、着色器预热进度、提示叠层、键盘输入提示）跟随 Mac 的系统语言。启动器文字在中文系统上显示中文，其他语言显示英文。地区变体和主机一样：美洲以外的英语（en-GB、en-AU 等）选英式英语，温度显示摄氏度（美式英语显示华氏度）；加拿大的法语选加拿大法语，美洲的西班牙语选拉美西班牙语；1.4.3 版本中，巴西葡萄牙语会选择游戏官方的 pt-BR 文本。简体和繁体中文按文字（zh-Hans / zh-Hant）区分，没有文字标记时按地区区分（台湾、香港、澳门为繁体）。只想让本游戏使用另一种语言时，可在“系统设置 › 通用 › 语言与地区 › 应用程序”中为它选择，或设置它的首选语言，例如 `defaults write org.macnativegames.totk AppleLanguages -array pt-BR`（`defaults delete org.macnativegames.totk AppleLanguages` 可撤销）。如需指定，可用 `TOTK_LANG` 设置游戏语言（例如 `open --env TOTK_LANG=zh-Hans "Tears of the Kingdom.app"`），用 `TOTK_UI_LANG=zh` / `en` 设置启动器文字。

## 截图

手柄的截图键保存游戏画面本身：任天堂手柄 D-pad 下方的方块键（读手柄的 HID 报告；Home 键仍归 macOS）、以及 macOS 上 DualSense、DualShock 4、Xbox 手柄的 Share 键。按一次保存一张。macOS 原本把 Share 键留给自己的截图手势，游戏会申请关闭该手势；但若在“系统设置 › 游戏中心”里为该键单独绑定了快捷键，它仍归系统，此时按键不会截图。保存的是游戏画面：启动文字、帧率框与设置面板不在其中。

- **iPhone / iPad：** 保存到系统相册，相簿为 **Tears of the Kingdom**（或 **Breath of the Wild**）。首次保存时系统会请求“添加照片”权限；拒绝则无法保存，提示会说明原因。
- **桌面端（macOS、Windows、Linux）：** 保存到文件夹，默认桌面。设置面板 **输入** 页最后一行 **截图保存目录** 打开系统文件夹选择窗口；选择时即检查（只读磁盘、其他账户的文件夹会被拒绝并说明原因），选择结果保存在 `controls.txt` 旁的 `screenshot-dir.txt`。启动时的 `TOTK_SCREENSHOT_DIR` 仍优先；在面板中选定后，本次运行立即改用它。

文件名为 `Tears of the Kingdom 2026-10-30 at 14.05.32.png`，同一秒内的第二张加 ` (2)`、` (3)`……。画面底部会显示保存位置或未保存的原因：目录不存在、所选路径不是文件夹、没有写入权限、路径过长、空间不足；手机端为无照片权限或画面尺寸超出上限。

## 文字输入（Mac）

游戏要你输入文字（给马取名）时，窗口变暗，出现一个屏幕键盘和上方的输入框。王国之泪和旷野之息都用它，不改游戏代码。可以照常用 Mac 键盘打字（能选中、粘贴、用输入法；回车确认，Esc 取消），也可以点键盘上的键，或者用手柄：

| 操作 | PlayStation | Xbox | Switch |
|---|---|---|---|
| 在键之间移动 | 十字键 / 左摇杆 | 十字键 / 左摇杆 | 十字键 / 左摇杆 |
| 输入选中的键 | × | A | A |
| 取消 | ○ | B | B |
| 删除 | □ | X | Y |
| 空格 | △ | Y | X |
| 大小写 | L3 | 按下左摇杆 | 按下左摇杆 |
| AZERTY / QWERTY | R3 | 按下右摇杆 | 按下右摇杆 |
| 移动光标 | L1 / R1 | LB / RB | L / R |
| 字母 / 符号 | L2 | LT | ZL |
| 确认 | R2 / Options | RT / Menu | ZR / + |

- 键上标着对应的手柄按键，按手柄类型（自动或设置面板里选的）、按位置显示；改过 `controls.txt` 也不影响。
- 键盘打开时手柄用来打字，不操作游戏；松开所有按键和摇杆后才交还给游戏。
- 键盘页里有拉丁字母、法语重音字母、数字和标点；其他文字用 Mac 的输入法。
- 输入内容遵守游戏的限制：长度和不允许的字符。
- 键盘上的文字按 Mac 的语言显示中文、法语或英语（`TOTK_UI_LANG` 可改）。
- 法语系统默认 AZERTY，其他默认 QWERTY；选择保存在 `controls.txt` 旁边的 `keyboard-layout.txt`。
- 不需要游戏文件就能检查：`python -m unittest tests.test_text_keyboard`；`games/totk/tests/text_keyboard/test.py --preview` 打开它看效果。

## 按键图标

`python3.14 games/totk/scripts/make_button_icons.py <模组文件夹> --app <Tears of the Kingdom.app> --style keyboard`（或 `--style xbox`）生成一个模组，把游戏按键提示里的 Switch 图标换成默认的键盘和鼠标布局（A B X Y 对应 E、Shift、空格、鼠标左键，W A S D、方向键等；在设置面板里改过的布局不会画出来）或 Xbox 按键（按 Switch 位置排列的 B A Y X、LB/RB、LT/RT、Menu/View）。它用你自己的 RomFS 重绘每种语言字体包里的图标字体（项目里不含任何游戏内容），所以每种游戏语言（包括韩语和中文）都会换成新图标，并写好 manifest，同时把游戏的资源大小表调大以容纳变大的字体（不调的话游戏启动时就会停止）；文件夹里已有的文件会保留。用旧版脚本生成的模组只覆盖其他语言，请加 `--replace` 重新生成。需要 Python 3.14 和 `python3.14 -m pip install fonttools`。文件夹里已有字体包（别的模组的，或者上次生成的）时会停下，加 `--replace` 才覆盖，换风格也要加它。Xbox 图标对应默认的按位置映射；设了 `TOTK_FACE_BUTTONS=label` 或在 `controls.txt` 里改过面键时会对不上。删除模组里的 `Font` 文件夹和 `System/Resource/ResourceSizeTable.*` 后运行 `make_mod_manifest.py` 即可恢复。以固定图片显示的提示（部分教程动画）仍是 Switch 图标。