Iron’s Spells: Incantation

Iron’s Spells: Incantation

说出法术名称，即可施放。

Incantation 会直接调用你的麦克风，通过离线语音识别器（Vosk）处理音频，并施放你刚刚说出的 Iron’s Spells ‘n Spellbooks 法术。无需训练语音模型，语音模型会在首次启动时自动安装。

工作原理

Incantation 会直接调用你的麦克风——无需语音聊天模组——并将音频传给 Vosk 识别器。识别器的语法由已安装模组实际注册的法术名称生成。封闭语法只能通过 [unk] 令识别失败，但它往往会选择最接近的法术名称，而不是这个标记——因此，0.10.6 加入了相应的防护措施：只有当匹配语音的时长足以合理地对应这个短语时，才会触发施法；而你在 perSpellMinConfidence 中列出的法术，则必须等到整段语音说完且达到各自的置信度阈值后才会触发。

施法还会根据你实际装备的物品进行限制：Curios 槽位中的法术书、手持的灌注武器，或身穿的灌注盔甲。说出你没有的法术名称不会产生任何效果。如果服务器希望允许玩家使用手持的法术书施法，可以设置 castMode = ANY_SPELLBOOK。

语音识别完全在你的设备上运行。无需账号、没有遥测，麦克风音频绝不会传输、录制或写入磁盘。Incantation 唯一会联网的情况，是首次启动时下载语音模型；如果不希望它自动下载，可设置 autoDownloadModel = false，然后自行安装模型。

何时监听

**默认情况下，只有当你手持、穿戴或在 Curios 槽位中装备法术书、法杖、灌注武器或灌注盔甲时，麦克风才会开启。**收起或卸下物品后，麦克风就会关闭。无需按键绑定。

这意味着收起法术书时聊天绝不会触发施法；如果你和朋友使用同一个麦克风进行语音聊天，这一点尤其重要。**但如果你一直把法术书放在 Curios 槽位里，实际效果就接近 ALWAYS_ON**——所以如果你会在战斗中和朋友聊天，请使用 HOLD_KEY_AND_ITEM。仅仅携带法术书并不代表你想施法；此模式还要求按住一个按键，因此只有在你主动操作时，语音才会传给识别器。

根据需要设置 gatingMode：

| 模式 | 麦克风开启条件 |
|—|—|
| HOLD_ITEM | 手持、穿戴或在 Curios 槽位中装备法术媒介时 （默认） |
| HOLD_KEY_AND_ITEM | 按住施法键且装备法术媒介时 |
| HOLD_KEY | 按住施法键时 |
| ALWAYS_ON | 只要身处世界中——完全无需手持物品 |

这些模式限制的是音频采集，而非语音识别：除 ALWAYS_ON 外，识别器都不会接收到音频，麦克风也会实际关闭，而不只是忽略输入。游戏失去焦点或暂停时，麦克风也会关闭。

HUD 上的麦克风状态标记会让你一眼看清当前状态——麦克风关闭时指示点较暗，开启时会亮起，实际检测到语音时则会闪动；旁边还会显示实时音量条。

功能

• 念出任意已索引的法术——支持 Iron’s Spells、其所有附属，以及任何通过 Iron’s API 注册法术的模组。
• 仅限已装备施法 （默认开启）——只有法术确实带在身上时才会施放。其他情况会在离开客户端之前就被拒绝。
• 支持灌注武器与护甲——手持灌注剑或法杖，或穿戴灌注胸甲，念出它所携带的法术，即可通过与右键相同的机制施放。
• HUD 小组件——角落锚定的小组件，显示实时麦克风指示器和电平表，以及上次施放、最近施放历史、排队中的法术、未命中提示、最后听到的短语，还有“你是不是想说……？”的别名建议。
• 原版进度——语音施法里程碑（1、10、50、200、1000 次）和连击施法会以标准进度提示的形式出现。
• 法术列表界面——浏览注册表暴露的每一个法术及其 Vosk 监听的确切短语，还有每个法术的施放次数和学派筛选。
• 语音法典——个人统计（施放最多的法术、每日连续天数、延迟中位数）。
• 测试竞技场——安全的练习模式，记录 本会 施放什么，但不会真正施放任何东西。适合调整别名或学习难念法术的发音。
• 首次启动时的欢迎向导——引导你完成麦克风 + 模型 + 首次施放。
• 别名与自定义短语——把模型能发音的词语绑定到任意法术 id。
• 用你自己的语言游玩——西班牙语、俄语和法语语音模型只需改一行配置（modelId），并且 config/voicespells/phrasebook.json 会随每个已安装法术生成，带有一个可编辑的 override 字段，因此你可以在一个文件里翻译整个法术列表，而不必逐个添加别名。你的覆盖内容会在更新后保留，新安装的法术会自动追加。

模型只是一半。 识别器只监听其模型认识的词，所以
法术短语也必须翻译——用俄语模型去听英文法术名，什么也听不到
。仓库的 contrib/ 文件夹里有一份由
社区贡献的西班牙语短语手册，已翻译好可直接使用。俄语那份是空白模板：294 个条目，
每个覆盖字段都是空的，因为过去用来填充它的机器翻译版本从未
对着麦克风说过，而错误的短语会被信任，空白的短语则会请求填写。
因此俄语识别需要先填好那个文件。/voicespells vocab 会告诉你
已加载的模型实际能念出你的哪些短语。

德语尚不可用，并非缺少模型：Iron’s Spells 没有附带德语
翻译，所以没有德语法术名可作为起点。它需要一份手写的短语
包。如果你说德语并且愿意写一份，请联系我们。

• 配装快捷方式——说一个词，从列表中施放第一个可施放的法术（会考虑冷却 + 法力）。
• 语音命令——说 no 来清除施法队列中等待的法术，或说 yes 来接受“你是不是想说……？”的别名建议（请先启用 handsFreeConfirm）。
• 奖励开口 （服务端，默认关闭）——语音施法可以恢复得更快、打得更狠，或两者兼有：voiceCooldownPercent 缩放冷却，voiceLevelBonus 增加法术等级，而额外等级按法术的普通法力消耗收费，而非更高的那档。如果你想，可以用 playerAdvantages 按玩家单独设置：

  playerAdvantages = [
      "Steve=cooldown:50,level:2",   # Steve casts faster and harder
      "!Alex",                       # Alex plays by ordinary Iron's Spells rules
  ]

开箱即用，默认设置就是原版 Iron’s Spells，没有任何改动。开启
voiceVolumeScaling后，加成必须靠努力争取：你的物品本身施法时的等级——
法术书、注魔物品或卷轴，包含亲和加成（FREE 模式下为 1 级）——
始终是下限，而一次施法在基础上额外增加多少 voiceLevelBonus，取决于你
说得有多大声：耳语不增加，正常说话声约增加一半，提高嗓门则全部增加——
四舍五入到整数等级，并以你自己校准后的说话声为基准判定。

• 仅限咒语模式 （服务端，默认关闭）——要求法术必须被念出。FIRST_CAST会让玩家必须先语音施放一次某个法术，之后才能点击施放，因此学会咒语即可解锁该法术；ALWAYS则表示法术只能通过语音施放。
• 服务端控制项——按玩家设置的白名单、黑名单、速率限制、附近广播、施法日志。

需求

• Minecraft 1.21.1（NeoForge 21.1.x）或 1.20.1（Forge 47.x）
• iron431 的 Iron’s Spells ‘n Spellbooks
• Curios API——推荐安装，而且它本来就是 Iron’s Spells 的前置依赖
• 一个麦克风
• 无需语音聊天模组。Incantation 会自行捕获麦克风，并且如果你用 Simple Voice Chat 和朋友聊天，也能与之共存。

安装

1. 把 Incantation 的 jar 放进你的 mods/ 文件夹，与 Iron’s Spells 放在一起。
2. 启动游戏。首次运行时，Incantation 会为你下载 vosk-model-small-en-us-0.15（约 40 MB）到 config/voicespells/。
3. 进入世界，装备一本法术书（手持或放在 Curios 栏位），然后念出它携带的某个法术。

想自己安装模型？设置 autoDownloadModel = false，从
alphacephei.com/vosk/models获取一个模型，并将其 内容解压到
config/voicespells/model/，最终得到 config/voicespells/model/am/、
config/voicespells/model/conf/等。

对于棘手的法术名称（Traveloptics、Cataclysm，以及任何发音不寻常的名称），在
config/voicespells-client.toml中映射一个别名：

customPhrases = [ "dark beam=traveloptics:abyssal_blast" ]

然后使用 More… → Reload grammar now——无需重启。

配置

大多数设置可在游戏内通过 Mods → Iron’s Spells: Incantation → Config 访问。

• Recognition 选项卡——门控模式、仅限已装备限制、模糊容差、子串匹配、去重窗口、调试监视器。
• HUD 选项卡——角落、偏移、不透明度。
• More 菜单——欢迎向导、Voice Codex、Diagnostics、Test Arena、重新加载语法、配置导出/导入、校准麦克风。

客户端命令：/voicespells devices 列出游戏能看到的每个捕获设备以及当前选中了哪一个
——如果麦克风看起来没反应，从这里开始排查。

服务端设置（config/voicespells-server.toml）：施法模式（CURIO_SPELLBOOK / ANY_SPELLBOOK
/ FREE）、按玩家设置的白名单、黑名单、速率限制、附近广播半径。

故障排除

• 说话没反应——先检查触发模式。默认情况下，只有法术书、法杖、灌注武器或灌注护甲拿在手上、穿在身上，或放在 Curios 饰品栏里时，麦克风才会开启。HUD 上的麦克风圆点会提示你：暗淡表示关闭。
• 聊天栏显示“Vosk model not found”（或诊断界面显示 Vosk model: FAIL）——config/voicespells/model/ 下没有模型。重新检查目录结构：am/、conf/、graph/ 应直接位于该路径下。
• 麦克风像是没反应——运行 /voicespells devices 看看游戏能检测到什么，如果默认设备不是你想要的那个，就设置 captureDevice。
• 识别感觉有点慢——打开“更多”→校准麦克风，然后念几个法术名称。或者用 诊断界面逐项验证前置条件。
• 测试竞技场不施法——这是有意设计的。它会记录本应发生的施法，让你可以安全练习。

许可证

MIT。

致谢

• Vosk——Alpha Cephei（Apache 2.0）
• Iron’s Spells ‘n Spellbooks——iron431
• 西班牙语短语手册——NeoTargetStudios（Spidercat0926），在九个法术模组中翻译了近 300 个法术名称，并为模组本身提供了帮助