GD656FrontVoice

概述

GD656FrontVoice 是一款 Minecraft 模组，可为多人服务器添加动态战斗语音台词系统。系统会播放阵营专属语音提示——中国（CN）、美国（US）和俄罗斯（RU）——并在战斗事件发生时触发，例如受到伤害、投掷手榴弹、装填、击杀敌人、受到枪火压制等。

上次更新：2026年7月25日。部分功能可能尚未完整记录，或仍可能发生变更。

兼容性

• 强烈建议使用 TACZ（Timeless and Classics Zero）1.1.7-hotfix 或更高版本——大多数战斗事件触发条件依赖 TACZ 的事件系统和枪械类型 API；
• 与 LR Tactical 软兼容——可检测可投掷实体以触发手榴弹警报和投掷提示，并检测燃烧效果；
• 与 GD656Conquest 软兼容——可解析阵营/队伍信息，用于路由语音包；
• 目前仅支持 Minecraft 1.20.1 Forge。

服务器安装

此模组分为客户端和服务器端功能。要完整使用所有功能，双方都必须安装。

仅服务器端功能：

| 功能 | 说明 |
|——|——|
| 战斗事件检测 | 监听 TACZ 枪械开火、装填、击杀事件，以及原版伤害/死亡事件 |
| 压制火力区域系统 | 子弹从玩家附近飞过时累积压制层数，并在达到阈值时触发语音提示 |
| 弹丸近失检测 | 追踪狙击枪子弹和 RPG 火箭弹，在弹丸从玩家附近飞过时发出警告 |
| 手榴弹警报扫描 | 每刻扫描附近的敌对投掷物，并警告受到威胁的玩家 |
| 弹药耗尽轮询 | 每刻检查玩家手持的 TACZ 枪械弹药状态 |
| 燃烧检测 | 检测玩家是否着火（原版效果或 LR Tactical 可燃效果） |
| 手榴弹投掷检测 | 检测玩家是否开始准备投掷手榴弹/燃烧瓶/烟雾弹 |
| 阵营感知语音路由 | 为每位玩家确定要使用的语音包（CN/US/RU） |
| 音频数据包广播 | 向目标客户端发送 ClientboundPlayAudioPacket |

仅客户端功能：

| 功能 | 说明 |
|——|——|
| 语音提示播放 | 接收数据包，通过 CueRouter 解析语音提示并播放声音 |
| 第一人称/第三人称路由 | 为自己播放本地（非空间定位）声音，为其他玩家播放空间定位声音 |
| 音频限流 | 限制每位玩家及每种类型同时播放的声音数量，以防止刷屏 |
| 配置与命令系统 | 用于调试和管理配置的 /gdfv 客户端命令 |
| 阵营视角覆盖 | 客户端的盟友/敌人检测可覆盖服务器分配的语音包 |

简而言之：服务器检测并触发所有语音事件；客户端负责播放、路由和限流。网络流量极少（仅使用一种自描述数据包类型：ClientboundPlayAudioPacket）。

配置与命令

所有参数都可以通过 Forge 模组配置界面或游戏内命令进行调整：

/gdfv debug summary              Show audio manifest statistics
/gdfv debug list [filter]        List registered sound events
/gdfv debug play local <sound_event> [volume] [pitch]
/gdfv debug play position <sound_event> <pos> [volume] [pitch] [distance]
/gdfv debug play entity <sound_event> <entity> [volume] [pitch] [distance]
/gdfv debug play cue <voice_cue> <camp> <entity> [volume]
/gdfv config reload              Hot-reload configuration files

命令需要权限等级 2（服务器管理员）。配置更改会立即生效；支持通过基于反射的配置重载实现运行时热重载。

主要配置选项

服务器（通用）配置：

| 配置项 | 默认值 | 描述 |
|——|——|——|
| audio.serverEnabled | true | 是否启用服务器音频广播的总开关 |
| audio.serverMasterVolume | 1.0 | 全局音量倍率（0.0–4.0） |

客户端配置：

| 配置项 | 默认值 | 描述 |
|——|——|——|
| audio.enabled | true | 是否启用客户端播放的总开关 |
| audio.friendlyVoicePack | CN | 友方玩家使用的语音包（未安装或忽略 Conquest 时） |
| audio.enemyVoicePack | US | 敌方玩家使用的语音包（未安装或忽略 Conquest 时） |
| audio.detectEnemyByVanillaTeam | true | 使用原版队伍（isAlliedTo）检测敌方玩家；无需 Conquest 即可生效 |
| audio.ignoreConquestCamp | false | 忽略 Conquest 阵营分配，改用友方/敌方配置 |
| audio.fallbackThirdPersonForLocal | true | 缺少第一人称音效时，改用第三人称音效 |
| audio.masterVolume | 1.0 | 客户端主音量（0.0–4.0） |
| audio.firstPersonVolume | 1.0 | 第一人称音效的额外音量倍率（0.0–4.0） |
| audio.thirdPersonVolume | 1.0 | 第三人称音效的额外音量倍率（0.0–4.0） |
| audio.maxSimultaneousSingleTpSound | 2 | 同一类型的第三人称音效同时播放上限 |
| audio.maxSimultaneousTpPlayersFriendly | 3 | 同时发出第三人称音效的友方玩家上限 |
| audio.maxSimultaneousTpPlayersEnemy | 3 | 同时发出第三人称音效的敌方玩家上限 |
| audio.maxThirdPersonDistance | 48.0 | 第三人称音效的最远可听距离（方块） |

---

功能

事件驱动的语音提示

服务器上的特定游戏内事件会触发以下语音提示：

| 语音提示 | 触发条件 | 播放方式 |
|——|——|——|
| DEATH | 玩家死亡（LivingDeathEvent），且不是旁观者 | 分层播放：第一人称死亡音效 + 对自身播放音效；第三人称对附近队友播放友军死亡反应 |
| EXPLOSION_CLOSE | 玩家受到爆炸伤害但存活（生命值 > 0） | 对自身播放第一人称音效，1 秒冷却 |
| LOW_HEALTH_PANIC | 玩家生命值降至 5.0 以下（半颗心 × 5） | 对自身播放第一人称音效，每次低血量状态仅触发一次 |
| HEAVY_HURT | 玩家受到 TACZ 子弹伤害（非狙击枪、非 RPG、非爆炸）并存活 | 对自身播放第一人称音效，10 秒冷却；若同一 tick 触发了更高优先级的提示则被抑制 |
| BURNING | 玩家处于着火状态（原版）或拥有 LR Tactical lrtactical:flammable 效果 | 分层第一人称播放：尖叫 + 火焰 + 火花，每次燃烧状态仅触发一次 |
| REQUEST_AMMO | 玩家手持的 TACZ 枪械弹匣弹药为零、枪管弹药为零，且背包中没有匹配的弹药 | 对自身播放第一人称音效，每次空弹状态仅触发一次；空弹时每 1 秒重新检测，有弹时每 3 秒检测 |
| GRENADE_ALERT | 敌方 LR Tactical 爆炸手雷位于 5 格半径内 | 对自身播放第一人称音效，每 5 tick 扫描一次；排除自己的手雷 |
| THROW_GRENADE | 玩家开始拉引信准备投掷 LR Tactical 爆炸手雷或燃烧瓶（按住右键） | 第三人称广播给追踪范围内的玩家 |
| THROW_SMOKE | 玩家开始拉引信准备投掷 LR Tactical 烟雾弹（按住右键） | 第三人称广播给追踪范围内的玩家 |
| RELOADING | 玩家换弹 TACZ 枪械（GunReloadEvent） | 第三人称广播给追踪范围内的玩家，1 秒冷却 |
| SUPPRESSED | 1 秒内累积 6 层以上来自非机枪火力的压制层数（见 压制火力走廊） | 对目标播放第一人称音效，4 秒冷却 |
| MACHINE_GUN_ALERT | 1 秒内累积 6 层以上来自机枪火力的压制层数 | 对目标播放第一人称音效，4 秒冷却 |
| SUPPRESSING_HOSTILE | 射手在 1 秒内对敌人累积 9 层以上压制层数 | 对射手播放第一人称音效，4 秒冷却，受 1 秒攻击性提示间隔限制 |
| SNIPER_ALERT | 狙击子弹从玩家 5 格范围内掠过，或玩家首次被狙击枪命中 | 对目标播放第一人称音效，3 秒冷却 |
| RPG_ALERT | RPG 火箭从玩家 10 格范围内掠过，或玩家首次被 RPG 命中 | 对目标播放第一人称音效，3 秒冷却 |
| KILL_ENEMY | 玩家用 TACZ 枪械击杀敌人（非爆头，或附近无队友可触发精彩击杀） | 对击杀者播放第一人称音效 |
| NICE_SHOT | 玩家取得爆头击杀，且 5 格范围内有友军观察者 | 对附近友军观察者播放第三人称音效 |
| FRIENDLY_FIRE | 玩家击杀队友，且 2 格范围内有友军观察者 | 对附近友军观察者播放第三人称音效，4 秒冷却 |
| TEAMMATE_DOWNED | 附近有队友被击杀 | 对附近友军广播第三人称音效（通过 GDCQ 死亡延迟触发） |

压制火力走廊

当玩家使用 TACZ 枪械开火时，服务器会计算一个火力走廊——以射手眼睛位置为起点、沿视线方向向前延伸 24 格、半径 1.6 格的圆柱体区域。该走廊内每一个敌对、存活、非旁观者的玩家都会获得一层压制层数。

• 每个目标的压制层数从首次叠加起 20 ticks（1 秒）后过期
• 6 层：对目标触发 SUPPRESSED（若所有层数均来自 MG，则触发 MACHINE_GUN_ALERT）
• 9 层：此外，对射手触发 SUPPRESSING_HOSTILE
• 冷却机制可防止重复触发：目标的受压制提示冷却 4 秒，射手的压制敌人提示冷却 4 秒；激进提示之间还设有 1 秒间隔限制

弹体近失检测

当 TACZ 子弹实体生成时（EntityJoinLevelEvent），服务器开始追踪这些弹体。每个 tick，追踪中的弹体会按枪械类型进行分类：

• 狙击枪子弹（枪械类型 sniper）：近距离掠过半径为 5 格
• RPG 火箭弹（枪械类型 rpg）：近距离掠过半径为 10 格

对于每个弹体，系统会通过线段与膨胀后方框的相交检测，检查弹体上一位置与当前位置之间的移动线段是否经过附近敌对玩家的碰撞箱。狙击枪或 RPG 首次直接命中时也会触发检测。这两种提示对每个目标均有 3 秒冷却。

无法识别的弹体会在探测 5 个 tick 后移除；死亡或已移除的弹体会自动清理。

手榴弹警报与投掷检测

• 警报扫描：每隔 5 个 tick，服务器会扫描每位玩家周围 5 格半径范围内 LR Tactical 的 ThrowableItemEntity 实体，筛选类型为 EXPLOSIVE_GRENADE 的实体。排除玩家自己投出的手榴弹。
• 投掷检测：每个 tick，检查玩家是否正在使用（按住右键）LR Tactical 的可投掷物品。玩家开始拉栓或切换到另一种手榴弹类型时，会触发相应提示——烟雾弹触发 THROW_SMOKE，爆炸手榴弹和燃烧瓶触发 THROW_GRENADE。

音频播放模式

客户端支持三种播放模式：

| 模式 | 行为 | 使用场景 |
|——|——|——|
| LOCAL | 非空间定位，音量恒定（SoundSource.PLAYERS，relative=true） | 第一人称自身反馈（例如受伤、死亡、生命值过低） |
| POSITION | 固定在世界坐标位置，根据距离衰减音量 | 定位于世界坐标的声音 |
| ENTITY | 附着在生物实体上，每个 tick 跟随其移动，实体移除后停止 | 附着于第三人称玩家的声音（例如装填、投掷手榴弹） |

第一人称播放时，音量会乘以 firstPersonVolume；第三人称播放时则乘以 thirdPersonVolume。如果提示没有第一人称音频变体，客户端可以回退使用第三人称变体（由 fallbackThirdPersonForLocal 控制）。

音频节流

为避免激烈交火时声音过载，客户端会进行节流限制：

• 每位玩家的第一人称限制：同一时间仅播放一个第一人称声音，但 BURNING（拥有独立的提示列表）和无限优先级提示除外（DEATH、FINAL_DEATH 以及所有复活声音）
• 每位玩家的第三人称限制：同一玩家不能同时播放两个第三人称声音
• 每种类型的第三人称限制：全局范围内，同一种提示类型最多同时播放 maxSimultaneousSingleTpSound 个实例（默认值为 2）
• 每个阵营的玩家数量限制：最多允许 maxSimultaneousTpPlayersFriendly 名友方玩家（默认值为 3）和 maxSimultaneousTpPlayersEnemy 名敌方玩家（默认值为 3）播放第三人称声音。达到上限时，如果新玩家距离更近，则移除最远的玩家

音频分层

某些提示音会同时播放多个音效层：

• DEATH：第一人称音效层 fp.death.death + 音效层 fp.death.sfx；第三人称盟友反应通过 tp.{camp}.death 播放
• BURNING：三个第一人称音效层 — fp.burning.scream + fp.burning.flame + fp.burning.spark

---

GD656Conquest 集成

当服务器安装了 GD656Conquest 时，GD656FrontVoice 会通过反射自动检测到它，并在以下三个方面使用其 API：

1. 阵营解析：resolveCamp(player) 会从 Conquest 的队伍系统中获取玩家所属阵营（CN/US/RU）。分配的语音包将遵循玩家的实际阵营，而非回退到默认设置。
2. 敌对关系检查：isSameCamp(left, right) 用于判断两名玩家是否属于同一个 Conquest 队伍。此检查会替代原版的 isAlliedTo 敌对关系检查，也就是说，只有属于不同 Conquest 队伍的玩家才会在抑制、狙击手警报和 RPG 警报中被视为敌对。
3. 延迟死亡提示音：shouldDeferDeathCue(player) 允许 Conquest 控制死亡语音提示是立即播放还是延迟播放（例如用于倒地/复活系统）。

未安装 GD656Conquest 时：所有玩家默认使用 CN 语音包；基于阵营的敌对关系检查将回退到原版联盟检查。

在客户端，ignoreConquestCamp 配置选项允许玩家忽略服务器提供的阵营，并改用自己的 friendlyVoicePack / enemyVoicePack 设置。

---

备注

• 此模组需要同时在客户端和服务器安装，才能完整发挥功能；
• 此模组仍在积极开发中（0.x）；功能可能会持续变化；
• 部分代码在 AI 技术的辅助下编写；
• 采用 MIT 许可证授权。