跳到主要内容

视觉小说使用指南

这篇指南面向视觉小说、Galgame、ADV 等以对话框阅读为主的场景。它会基于 Mask 当前的真实实现，说明如何把 聚焦、OCR 区域、双遮罩区域、自动触发、自动翻页和坐标校准串成一套稳定可用的工作流。

如果你还没有完成基础配置，请先阅读：使用方法（快速上手）

1. 适用场景与前提​

这份指南最适合下面几类环境：

  • 在 macOS 原生窗口中运行的视觉小说
  • 在 CrossOver / Whisky 中运行的 Windows 视觉小说
  • 需要长期连续阅读对话、选项和系统提示的场景

开始前，建议你先确认：

  • 已授予必要权限，尤其是屏幕录制权限
  • 已配置可用的模型提供商与 API Key
  • 能先完成一次最小样本测试翻译

2. 推荐工作流​

建议按下面的顺序配置，而不是一开始把所有功能都打开：

  1. 点击 聚焦，先绑定目标游戏窗口。
  2. 点击 OCR 区域，先框出主对话栏。
  3. 如果游戏有选项分支，再补充选项区域。
  4. 需要遮罩显示时，再设置 双遮罩区域。
  5. 根据你的习惯选择 自动截图范围。
  6. 最后再按需启用 画面变化检测、全局点击触发、自动翻页 和 坐标校准。

可以把它理解成两档配置：

  • 最低可用配置：聚焦 + OCR 区域，然后手动点一次 翻译一次
  • 进阶稳定配置：再加入 双遮罩区域、检测区域、自动翻页区域和必要的坐标校准

3. 先选择窗口​

聚焦 会打开一个窗口列表。你选中的窗口会成为后续 OCR、VLM、区域预览和自动翻页的绑定目标。

这一步非常重要，因为 Mask 当前并不是直接对“当前最前面的任意窗口”工作，而是显式绑定到一个 windowID。

你可以这样理解它的作用：

  • 翻译一次 会从这个窗口截图
  • VLM 翻译 会从这个窗口截图
  • 区域编辑器里的预览背景，也来自这个窗口

如果没有先选择窗口，相关流程会被拦住，并提示你先回到主面板点击 聚焦。

使用建议：

  • 启动游戏并进入有文字的画面后，再去 聚焦
  • 如果你切换了游戏进程、重开了窗口，或从启动器进入了另一个窗口，最好重新确认绑定是否仍然正确
  • 如果区域编辑器背景一直是空白或灰色，先检查是不是绑定到了错误窗口

4. 划定 OCR 区域​

OCR 区域 并不只是一个单独的框。当前实现支持：

  • 1 个主对话栏区域
  • 0 到多个选项区域

这意味着它既能处理普通对话，也能把选项分支从主对话里拆出来。

主对话栏怎么框​

建议只框住真正承载台词的区域，不要把下面这些内容一起收进去：

  • 角色立绘
  • 特效字幕
  • 闪烁 UI
  • 操作按钮

这样做的原因很直接：OCR 噪声会更少，触发检测也更稳定。

选项区域怎么用​

如果游戏会在对话之外单独弹出多项选择，建议为选项单独加区域。

区域编辑器当前支持这些操作：

  • 新增选项区域
  • 删除当前选项
  • 给每个选项区域命名
  • 调整选项区域顺序

交互方式是：

  • 在空白处拖拽，可以创建新的框
  • 拖动框本体，可以整体移动
  • 拖动边缘和角上的控制点，可以缩放矩形

如果你的目标是“把主对话和选项分开翻译”，这一步就是核心配置。

5. 双遮罩区域​

双遮罩区域 控制的是译文显示在哪里，不是 OCR 实际识别哪里。

这两个概念要分开理解：

  • OCR 区域 决定读哪里
  • 双遮罩区域 决定译文盖在哪里

普通单区域 OCR 下，你可以只配置一个主遮罩，或者暂时不用遮罩。

但如果你已经启用了多区域 OCR，也就是除了主对话栏之外还配置了选项区域，那么当前实现要求遮罩数量必须是 2 个：

  • 1 个主对话遮罩
  • 1 个选项遮罩

否则翻译流程会直接拒绝执行。

实际使用时，推荐这样映射：

  • 主对话遮罩对应游戏的对话框位置
  • 选项遮罩对应选项栏位置

这样可以避免主对话译文和选项译文混在同一块区域里。

6. 自动截图范围与触发策略​

自动截图范围 会影响自动触发时，Mask 到底截多大一块内容去翻译。

当前主要有两种语义：

仅 OCR 区域​

自动触发时，只截图当前的主 OCR 区域。

适合：

  • 对话框位置长期稳定
  • 你只关心台词本身
  • 想尽量减少无关 UI 和画面元素带来的干扰

注意：如果你把自动截图范围设成这个模式，但还没有设置主 OCR 区域，自动链路会直接报错。

整窗​

自动触发时，对当前绑定窗口做整窗截图。

适合：

  • 对话位置变化较多
  • 你希望模型获得更多画面上下文
  • 某些场景下想结合更大范围判断内容

画面变化检测区域​

画面变化检测区域 只决定“哪里用来判断是否发生了新变化”，它不等于真正送去翻译的截图范围。

这在视觉小说里很有用，因为很多游戏会有：

  • 角色眨眼
  • 立绘轻微移动
  • 粒子特效
  • 菜单按钮闪烁

如果你把检测区域收紧到对话框附近，就能显著减少误触发。

单击检测区域​

单击检测区域 用于限制“启用全局点击触发后，点击哪里才值得继续检测”。

比较适合的场景是：

  • 你只想在点击对话框或翻页热区后再检查新文本
  • 不希望随便点击别的 UI 也触发一次检测

对视觉小说来说，一个很稳妥的默认思路是：

  • 检测区域尽量贴近对话框
  • 单击检测区域尽量贴近翻页或阅读交互区

7. 自动翻页与坐标校准​

如果当前运行环境支持自动翻页注入，就会出现 自动翻页区域。

需要额外注意：因 Apple 的权限限制，Mac App Store 版本暂不支持自动翻页功能。如果你使用的是商店版，可以先按本文的其他流程完成窗口绑定、OCR 区域、检测区域和遮罩配置，再用手动翻译或其他触发方式阅读。

它表示自动点击时的目标位置，通常应该放在：

  • “下一句”
  • “下一页”
  • 用于推进文本的热区

推荐做法：

  1. 先把自动翻页区域框在真实可点击热区上。
  2. 如果游戏翻页后还有淡入、残影或过渡动画，再增加翻页缓冲时间。
  3. 再决定是否开启“自动翻页后触发翻译”。

这能减少“刚翻页就截图，结果截到半动画帧”的情况。

什么时候需要坐标校准​

坐标校准 主要是为 CrossOver / Whisky 准备的。

如果你遇到下面这些问题，就可以考虑校准：

  • 看起来框对了，但实际点击位置总是偏一点
  • 自动翻页点击落不到正确热区
  • 框选区域和实际截图位置有系统性错位

建议顺序是：

  1. 先可视化设置好自动翻页区域
  2. 再进入 坐标校准
  3. 微调 offsetX、offsetY、scaleX、scaleY

如果你的环境本来就没有坐标偏移，则不需要动这部分。

8. 临时截图与 VLM​

临时截图翻译​

临时截图翻译更适合偶发场景，例如：

  • 某段系统提示不在主对话框里
  • 某个菜单或弹窗只想临时翻译一次
  • 你不想改动当前 OCR 主工作流

它和长期绑定的 OCR 主框选流程不是一回事，更适合作为补充工具。

VLM 翻译​

VLM 翻译 更偏向整窗场景理解增强，而不是日常对话 OCR 的替代品。

对视觉小说来说，更合适的理解方式是：

  • 日常连续阅读：优先用 OCR 工作流
  • 复杂画面、特殊排版、需要额外上下文时：再试 VLM

当前实现里，手动触发的 VLM 翻译 走的是整窗截图，不受 自动截图范围 的设置影响。

9. 三套常见配置建议​

配置 A：基础对话模式​

适合只想稳定读主对话的场景。

  • 聚焦 绑定游戏窗口
  • OCR 区域 只框主对话栏
  • 启用 画面变化检测
  • 视需要启用单个主遮罩

注意事项：

  • 这是最稳的入门方案
  • 如果误触发较多，先收紧检测区域

配置 B：选项分离模式​

适合有分支选项、并且希望选项单独显示译文的游戏。

  • 主对话栏作为主 OCR 区域
  • 为各个选项加独立 OCR 区域
  • 配置 双遮罩区域
  • 保证遮罩数量正好是 2

注意事项：

  • 当前实现要求多区域 OCR 时必须是 主对话遮罩 + 选项遮罩
  • 如果遮罩数不对，翻译会被拒绝执行

配置 C：自动推进模式​

适合希望尽量少手动干预、连续推进文本的场景。

  • 设置 自动翻页区域
  • 启用 自动翻页
  • 按需启用 自动翻页后触发翻译
  • 如果存在坐标偏移，再做 坐标校准

注意事项：

  • 先保证翻页点击位置准确，再谈全自动
  • 如果翻页后截图经常抓到过渡帧，优先提高翻页缓冲时间

10. 何时先排查配置，而不是换模型​

如果效果不稳定，不一定是模型问题，先检查这些更有效：

  • 窗口是否重新绑定过
  • OCR 主区域是否框得过大
  • 检测区域是否把立绘和特效也纳入了
  • 多区域 OCR 时是否已经配置了 2 个遮罩
  • 自动翻页点击点是否真的落在可推进热区

很多视觉小说场景下，配置是否贴合画面结构，比单纯换更强的模型更重要。