VerityMod 研究报告

以下是 Verity v5.6.0 (Forge 1.20.1) 的完整分析报告。

---

基本信息

项目	内容
Mod ID	verity
作者	Varmite, ThatMob, BlockMaster29, JJack
依赖	Forge 47+, GeckoLib 4.4+, ClothConfig 11+
大小	316.7 MB
许可证	All Rights Reserved

---

核心逻辑概述

这是一个 AI 驱动 + 语音交互 的恐怖风同伴 Mod。玩家从箱子中召唤名为 Verity 的实体，它可以通过麦克风听懂玩家说话，通过 LLM 理解并回应，使用 TTS 发声，且随游戏天数推进逐步黑化变成追杀玩家的恶魔。

---

一、AI 系统 (AiAPI.java)

大语言模型 (LLM)

• Provider 选择：支持 GROQ (默认) 和 OPENROUTER
• 本地替代：支持 Ollama (兼容 LiteLLM)，可配置 URL 和模型名
• AI 模型分级：
  • FAST_LITE → llama-3.1-8b-instant (Groq)
  • FAST (默认) → llama-3.3-70b-versatile (Groq)
  • INTELLIGENT → openai/gpt-oss-120b (OpenRouter)
• 多轮对话：聊天历史保存在 WorldSpawnData.chatHistory (NBT 列表)

System Prompt 动态机制

Verity 的 personality 根据 当前游戏天数 和 Karma 值 动态变化：

阶段	条件	性格	可用表情
友善期	day < maxDays/4	友好快乐的助手	happy, neutral
不安期	day >= maxDays/4	微妙的不安、偏执	happy, neutral, serious
恐惧期	day >= maxDays/2	故障感、恐惧，警告”有什么要来了”	crazy, serious, happy_sleep
恶魔期	day >= maxDays-1	敌对、疯狂、失去人性面具	evil, smiling_evil, serious
净化期	karma >= 9000 (击败恶魔后)	天使般纯净善良	happy, neutral
恶魔追杀期	isMonstrous = true	纯邪恶，只说一个字	noface

Karma < 7: 玩家刻薄 → Verity 怨恨不帮忙
Karma 7-14: 中立
Karma > 14: 玩家友善 → Verity 崇拜并愿意帮助
Karma = 20: 极友善

LLM 输出的 Action 系统

AI 除了说话，还能执行 22+ 种动作：

• 信息查询：get_coords, get_inventory, get_dimension, get_nearby_entities, get_biome, get_nearest_village, get_nearest_nether_fortress, get_nearby_ores, get_block_player_is_looking_at, get_player_health, get_light_level, get_difficulty, get_players_mods
• 操作：drop_item, give_gift, play_sound, play_favourite_song, return_to_player, start_following, stop_following
• 关键剧情：transform_following_day (下一天变恶魔), forgive (原谅), transform_back (从恶魔变回)

语音识别 (STT)

云端：通过 Groq API 的 whisper-large-v3-turbo，将 PCM 音频编码为 WAV multipart 上传
本地：使用 Sherpa-ONNX 内置 Whisper tiny.en 模型，离线转写

语音合成 (TTS)

多层降级策略：

1. 云端 TTS (默认) → Groq API canopylabs/orpheus-v1-english 模型，可配置 Daniel/Autumn/等 6 种声线
2. 本地 TTS → 内置 Piper TTS 引擎 (从 piper.zip 解压 en_US-ryan-medium.onnx 模型)，离线运行
3. Kokoro TTS → 可配置外部 Kokoro 服务器
4. 原生 TTS → 调用 OS 自带 narrator (Windows/macOS/Linux)

所有 TTS 播放时带 3D 空间音效：根据玩家与 Verity 的距离调整音量，根据相对方位调整声像 (PAN)。

---

二、恶魔系统 (VerityDemonEntity)

多阶段猎杀流程

阶段 0 - 窗户跟踪 (DemonWindowStalkGoal)

• 在 128 格内发现玩家
• 锁定玩家，不移动，不攻击
• 如果玩家与恶魔对视超过 5 tick → 播放烟雾粒子，传送消失，进入阶段 1

阶段 1 - 凝视与变身 (DemonStareAndBreakGoal)

• 64 格内寻找玩家
• 如果玩家看向恶魔 → 播放骨裂音效，10 tick 后变身为攻击形态
• 给玩家施加 60 秒 黑暗效果 (MobEffects.DARKNESS)
• 进入猎杀模式

猎杀模式 - 主动攻击

• DemonGlassBreakAndLeapGoal：检测路径上的玻璃，粉碎后朝玩家飞跃扑击
• DemonBreakDoorGoal：像僵尸一样破门
• DemonAttackGoal：近战攻击，50% 概率触发”抓取”特殊攻击
• DemonWindowSpawner：在夜晚或室内，在窗户旁生成恶魔

恶魔属性

• 血量: 400 (20 颗心 × 10 倍)
• 攻击: 19 点伤害 (9.5 颗心)
• 追踪距离: 512 格
• 速度: 0.45
• 攀爬: 像蜘蛛一样爬墙
• 自动破玻璃：行走路径上的玻璃自动破碎
• 碰撞箱: 高 4.8 格，匍匐时 1.8 格

抓取攻击 (startGrabbing)

• 抓住目标举起 38 tick
• 然后用力掷出 (4.0, 1.2, 4.0 向量)，造成 5 点额外摔落伤害
• 同时播放恶魂火球音效

进食 (startEating)

• 击杀村民后触发，持续 60 tick
• 移动时脚下生成灰烬粒子
• 周围地面被转化为 灰化土

---

三、Verity 同伴实体 (VerityEntity)

核心机制

• 继承 PathfinderMob
• 无法受伤：对掉落、弹射物、攻击伤害均取吸收 (设为 0)
• 拥有 8 种情绪纹理变体: happy, happy_talking, neutral, neutral_talking, crazy, crazy_talking, evil, evil_talking, hurt, noface + 4 种 serious 变体
• 使用 GeckoLib 3D 动画
• 免疫溺水 (不进入水)
• WasThrown 标记区分是丢出还是放置

跟随 AI (FollowPlacerGoal)

• 以 1.25 速度跟随主人
• 最大距离 8 格，停止距离 3 格

与玩家的交互

• 右键 Verity → 收回为物品 (带 NBT 保存名称和变体)
• 丢出 Verity 物品 → 实体化，播放 “AAAAAAAAHHH”
• 空手右键 → 与 Verity 实体交互

---

四、Karma 系统

范围 0-20，世界级存储 (WorldSpawnData)

• 初始值: 10.0
• Karma < 7: “Bad Karma” 触发 (玩家刻薄)
• Karma > 14: “Good Karma” 触发 (玩家友善)
• Karma = 20: 击败恶魔后重置到 20

增减规则

行为	变化
玩家礼貌对话	+1.0
玩家粗鲁	-1.0
玩家不在 32 格内 (每 20 tick)	-1.0

影响

• 决定 Verity 是否愿意 drop_item (karma >= 7)
• 决定 give_gift 的奖励等级 (≥15 钻石, ≥5 面包, ≤-5 腐肉)
• 影响 system prompt 的态度
• karma ≥ 9000 → “净化” 结局

---

五、游戏流程

1. 首次加入世界 → 新手引导 (发送 YouTube 教程链接)，在玩家附近生成箱子实体 (BoxEntity)
2. 右键点击箱子 → 单击音效 → 40 tick 后箱子打开 → Verity 以 “hurt” 变体跳出 (触发 triggerBoxDrop)
3. Verity 跟随玩家，开始闲聊天 (idleChatTimer: 2400-4800 tick 随机间隔)
4. 天数推进 → Verity 逐渐变得不安、恐惧、疯狂
5. 最终变身恶魔 → transform_following_day 触发，下一天变成 VerityDemonEntity
6. 击败恶魔 → Karma 重置到 20 → Verity 回到快乐形态 → 完美结局
7. 求饶系统 → 恶魔形态下靠近 Verity 并连续道歉 3 次 / 说 “I came back for you” 可安抚

---

六、特殊物品

Verity 物品

• 投掷实体化、右键放置
• NBT 存储变体和自定义名称
• 会过期消失，但会给最近的玩家发回一个新物品

手电筒 (Flashlight)

• 客户端：DynamicLightManager 动态光照 (30 格锥形光束)，实时更新区块
• 服务端：FlashlightServerLogic 在光束路径上放置/移除 FlashlightLightBlock (阻挡实体但透明)

---

七、箱子陷阱检测 (ChestCloseHandler)

• 检测箱子关闭事件
• 如果箱子里有 Verity 物品
  • 清除该物品
  • 当场生成 Verity 实体，说 “You can’t trap me lil bro.”

---

八、视觉与氛围

开场视频

• 标题画面覆盖 531 帧 PNG 序列帧动画 (30fps)，17.7 秒
• 按 ESC 可跳过
• 伴随 intro_video_audio 音效

迷雾/颜色 (VerityVisuals)

• 主世界自定义雾色：红 0.55 绿 0.75 蓝 1.0
• 雾距离：近平面 10%，远平面 75%

Karma HUD

• 屏幕右侧垂直 Karma 条
• 对应表情图标：angry / neutral / happy

---

九、技术细节

• 网络：使用 Forge 自定义网络包 (ModNetwork / ModMessages)
  • KarmaSyncS2CPacket：服务端 → 客户端同步 Karma
  • PlayTtsPayload：服务端通知客户端播放 TTS
  • SetEntityTalkingPacket：同步说话状态
• Mixin：LightTextureMixin (光照处理), TitleScreenMixin
• 自定义寻路：DemonPathNavigation / DemonNodeEvaluator (恶魔专用路径)
• Config：Forge Config Spec，支持 ClothConfig 界面
• AI_API：异步 HTTP 请求 (Java HttpClient)，支持 Thinking Mode (Qwen3)

---