猎人系统

文档版本：基于 2026-06-01 代码分析

概述

猎人系统是逃走中MOD最复杂的子系统，管理两种猎人实体（A型普通猎人、B型通报猎人）的完整生命周期：AI寻路、抓捕流程、冷却机制、猎人类型特效、装置复活、出生点分配和猎人箱结构。核心逻辑由 RfmHunterSystemManager 调度，RfmHunterEntityManager 和 RfmAnnounceHunterEntityManager 分别管理两类猎人实体。

---

核心概念

两种猎人实体

特性	A型（RfmHunterEntity）	B型（RfmAnnounceHunterEntity）
基类	Zombie	Zombie
攻击能力	有 ZombieAttackGoal，抓捕逃走者	无攻击，不参与抓捕
通报功能	无	8格内每500ms发射烟花通报
自定义AI	NfaBreakDoorGoal 破门	同A型
全局冷却	有（抓捕后10秒全局冷却）	无
强制区块加载	是	是

猎人类型（玩家）

类型	效果
NORMAL	无特殊效果，正常可见
INVISIBLE	潜行时获得隐身效果 + 红色粒子，冲刺时取消隐身

---

架构设计

抓捕完整时序

sequenceDiagram
    participant Hunter as 猎人（实体/玩家）
    participant Event as 事件系统
    participant HEM as RfmHunterEntityManager
    participant HS as RfmHunterSystemManager
    participant State as PlayerStateStore
    participant Pair as RfmPairingManager

    Hunter->>Event: 攻击逃走者
    alt 生物实体攻击
        Event->>HEM: tryCaptureByHunter()
        HEM->>HS: tryCaptureRunnerByHunterEntity()
    else 玩家攻击（LivingIncomingDamage）
        Event->>HS: tryCaptureRunner(hunter, runner)
    end

    HS->>HS: 检查 canHunterCaptureNow()
    Note over HS: canCapture && catchable && !冷却中
    HS->>HS: 检查 isCapturableRunner()
    Note over HS: 角色=RUNNER && 参与者 && !eliminated && !abstained
    HS->>HS: 检查 pendingElimination（防重复）

    alt 复活阶段待复活者
        HS->>HS: 仅移除复活资格，不淘汰
    else 正常淘汰
        HS->>State: 加入 pendingElimination（5秒延迟）
        HS-->>Hunter: 发送"你已被淘汰"
        HS->>HS: applyHunterAreaCooldown()
        Note over HS: 24格内所有猎人减速+失明+冷却10秒

        HS->>HS: finalizeElimination()
        HS->>State: setEliminated(true)
        HS->>HS: 计算淘汰奖励(roundCoins/10)

        alt LIFE 结对模式
            HS->>Pair: handleLifeModeEliminateAndGetPartner()
            Pair->>HS: 联动淘汰伴侣
        end

        HS->>HS: 检查存活人数
        alt 存活<=0 或 仅剩叛节者
            HS->>HS: finishByAllCaptured()
        end
    end

猎人系统架构

graph TB
    subgraph Entities["实体层"]
        A_Entity["RfmHunterEntity<br/>A型猎人（可抓捕）"]
        B_Entity["RfmAnnounceHunterEntity<br/>B型猎人（仅通报）"]
    end

    subgraph Managers["管理层"]
        HEM["RfmHunterEntityManager<br/>A型AI/生成/区块加载"]
        AHEM["RfmAnnounceHunterEntityManager<br/>B型AI/烟花通报"]
        HS["RfmHunterSystemManager<br/>抓捕/淘汰/冷却/复活/结算"]
        HSM["RfmHunterSpawnManager<br/>出生点随机分配"]
        HTS["RfmHunterTypeService<br/>隐身类型特效"]
    end

    subgraph Items["装备与道具"]
        Armor["HunterArmorItem<br/>猎人盔甲"]
        SuitCard["HunterSuitCardItem<br/>套装卡A/B"]
        Device["HunterDeviceItem<br/>猎人装置"]
        Freeze["FreezeHunterItem<br/>冻结道具"]
    end

    subgraph Data["持久化"]
        EntityData["PersistentRfmHunterEntitySavedData<br/>A型UUID/激活/冷却"]
        EntityBData["PersistentRfmHunterEntityBSavedData<br/>B型UUID/激活"]
        RoundData["PersistentRfmHunterRoundSavedData<br/>回合币/冷却/淘汰奖励"]
        SpawnData["PersistentRfmHunterSpawnSavedData<br/>出生点列表"]
        BoxLock["PersistentRfmHunterBoxLockSavedData<br/>猎人箱锁记录"]
    end

    Entities --> Managers
    Items --> Managers
    Managers --> Data

---

关键文件

实体类

文件	说明
com/chenxi/chenxi_rfm/common/entity/RfmHunterEntity.java	A型猎人实体
com/chenxi/chenxi_rfm/common/entity/RfmAnnounceHunterEntity.java	B型通报猎人实体
com/chenxi/chenxi_rfm/common/entity/goal/NfaBreakDoorGoal.java	自定义破门 AI
com/chenxi/chenxi_rfm/common/registry/ModEntityTypes.java	实体类型注册

服务端管理

文件	说明
com/chenxi/chenxi_rfm/server/rfm/RfmHunterSystemManager.java	抓捕/淘汰/冷却/复活/结算核心
com/chenxi/chenxi_rfm/server/rfm/RfmHunterEntityManager.java	A型猎人实体AI管理
com/chenxi/chenxi_rfm/server/rfm/RfmAnnounceHunterEntityManager.java	B型通报猎人AI管理
com/chenxi/chenxi_rfm/server/rfm/RfmHunterSpawnManager.java	猎人出生点分配
com/chenxi/chenxi_rfm/server/rfm/RfmHunterTypeService.java	猎人隐身类型特效

装备与物品

文件	说明
com/chenxi/chenxi_rfm/common/registry/ModArmorMaterials.java	猎人盔甲材料（耐久0，无敌由药水实现）
com/chenxi/chenxi_rfm/common/item/HunterArmorItem.java	猎人盔甲物品
com/chenxi/chenxi_rfm/common/item/HunterSuitCardItem.java	A/B型套装卡
com/chenxi/chenxi_rfm/common/item/HunterDeviceItem.java	猎人装置（复活机制头盔）
com/chenxi/chenxi_rfm/common/item/FreezeHunterItem.java	冻结道具（20格内猎人定身30秒）

猎人箱

文件	说明
com/chenxi/chenxi_rfm/common/block/HunterBoxABlock.java	猎人箱A（3格高，可锁定）
com/chenxi/chenxi_rfm/common/block/HunterBoxA2Block.java	猎人箱A2（带释放时间显示）
com/chenxi/chenxi_rfm/common/block/HunterBoxStartMainBlock.java	起始箱主方块（2x3多部件）
com/chenxi/chenxi_rfm/common/block/HunterBoxStartSideBlock.java	起始箱侧方块

---

关键流程

猎人永久效果（游戏全程）

游戏运行期间所有猎人玩家自动获得：

• MOVEMENT_SPEED（前60%时间 lv0，后40%时间 lv1）— 逐步加速
• DAMAGE_RESISTANCE 255 — 完全无敌

注意：猎人的无敌不是盔甲属性，而是 DAMAGE_RESISTANCE 255 药水效果。

抓捕冷却机制

全局生物冷却（A型猎人实体）：

• 任何A型猎人成功抓捕后触发，持续 10 秒
• 冷却期间所有A型猎人不再激活（effectiveActive=false）

猎人玩家冷却（24格范围区域冷却）：

• 抓捕者对半径 24 格内的所有在线猎人玩家施加冷却
• 效果：catchable=false + MOVEMENT_SLOWDOWN 255（完全定身）+ BLINDNESS 255（完全失明）
• 持续 10 秒，到期后自动恢复

猎人装置复活（resurrect_device）

sequenceDiagram
    participant Admin as 管理员
    participant HS as RfmHunterSystemManager
    participant GSM as RfmGameSessionManager
    participant Pending as 待复活者

    Admin->>HS: startHunterDeviceRevival(targetCount)
    HS->>HS: 收集已淘汰未弃权的逃走者
    HS->>GSM: startCountdownFreeze()
    Note over GSM: 冻结倒计时

    loop tickHunterDeviceRevival
        Pending->>HS: 装备 HunterDeviceItem
        HS->>Pending: 5秒定身（SLOW+BLINDNESS）
        HS->>Pending: 定身结束→活跃（SPEED+红色粒子）
        Pending->>Pending: 攻击其他待复活者
        HS->>Pending: 攻击者复活，被攻击者失去资格
    end

    alt 复活人数>=目标 或 剩余==0
        HS->>Pending: 所有剩余者自动复活
        HS->>GSM: 结束复活阶段
    end

自定义 AI Goal：NfaBreakDoorGoal

• 优先检测导航路径前方的关闭门
• 有替代路径时跳过破门（hasNoAlternativeProgressCheck）
• 破门持续 100 tick（5 秒），期间播放破坏动画和敲击音效
• 完成后直接 removeBlock 移除门的上半和下半部分

---

数据持久化

PersistentRfmHunterEntitySavedData

文件：<world>/data/nfa_rfm/rfm_hunter_entity.dat

字段	类型	说明
hunterEntityUuids	List<UUID>	A型猎人实体UUID
active	boolean	全局激活状态
cooldownUntilMillis	long	全局冷却到期时间戳

PersistentRfmHunterRoundSavedData

文件：<world>/data/nfa_rfm/rfm_hunter_round.dat

字段	类型	说明
roundCoins	Map<UUID, Integer>	回合币
eliminatedRewards	Map<UUID, Integer>	淘汰补偿（roundCoins/10）
hunterCooldowns	Map<UUID, Long>	每玩家冷却到期时间
coinLockedPlayers	Set<UUID>	逃走币锁定状态

---

注意事项 / 限制

1. 猎人实体继承 Zombie：实体复用 Zombie 的部分 AI 和动画，但不能被阳光灼烧（已重写相关逻辑）。
2. 强制区块加载：每个猎人所处区块被 setChunkForced(true)，防止生物因区块卸载而消失。
3. B型仅通报：RfmAnnounceHunterEntity.doHurtTarget() 直接返回 false，不造成伤害。
4. 无敌是药水效果：猎人的无敌通过 DAMAGE_RESISTANCE 255 实现，可通过 /effect clear 清除（但会被 tick 立即重新施加）。
5. 冷却区域效果强：抓捕后 24 格内所有猎人被定身+失明 10 秒，这是一个强力的平衡机制。
6. 猎人箱红石控制：POWERED && !LOCKED 时开门，管理员可用 ConfigTool 切换锁状态。

---

相关文档

• 首页 — 项目总览
• 游戏会话管理 — 状态机与tick
• 玩家身份与状态 — 角色与状态
• 权限系统 — 权限谓词
• 逃走币系统 — 淘汰奖励与结算
• 结对系统 — LIFE模式联动淘汰
• 警报系统 — 侦测方块联动警报
• 定位追踪 — 定位指南针
• 猎人实体 — 实体详解