godot-genre-horror

绝对不要做的事（专家级反模式）

氛围与紧张感

• 绝对不要始终维持 100% 的紧张感；必须严格采用锯齿式节奏模型（铺垫 → 高潮／惊吓 → 专门的舒缓阶段），以免玩家变得麻木、疲惫。
• 绝对不要把跳吓当作恐怖感的主要来源；应着重营造氛围、空间音频线索，以及对威胁的预期，从而建立真正的恐惧感。
• 绝对不要让环境黑到令人难以导航；黑暗应遮蔽威胁（细节），而非地面。使用轮廓光或电量有限的手电筒。
• 绝对不要给玩家无限资源；生存恐怖依赖资源稀缺。电量有限、弹药稀少、动画缓慢都是强制要求，能迫使玩家在压力下做出决策。

AI 与感知

• 绝对不要让 AI 瞬间发现玩家；应实现怀疑度计量表，或设置 1-3s 的反应窗口，再让 AI 进入全面攻击状态，以免让玩家觉得 AI「作弊」且不公平。
• 绝对不要使用可预测的 AI 路径；沿着完美循环行动的敌人是谜题，而非捕食者。使用 Director，定期在玩家附近「提示」一个新目的地。
• 绝对不要使用 Area3D 重叠信号进行即时、帧精确的视线（LoS）检测；使用无节点射线检测 PhysicsDirectSpaceState3D.intersect_ray()，以实现固定物理步同步。
• 绝对不要为远在摄像机视锥之外的怪物计算复杂的 AI 视觉或寻路逻辑；使用 VisibleOnScreenNotifier3D 禁用处理逻辑。
• 绝对不要让追击怪物的导航避障图层处于未配置状态；应明确指定避障掩码，以防它们在狭窄走廊里视觉上「堆叠」在一起。

技术与资源稀缺

• 绝对不要将可视化 SceneTree（如 GridContainer 子节点）作为物品栏的真实数据来源；必须维护类型明确的内存结构，例如 Dictionary[StringName, Resource]。
• 绝对不要依靠实例化标准 Node 来存储基础物品属性／定义；使用自定义 Resource 脚本，以减少内存开销，并支持直接在 Inspector 中编辑。
• 将物品添加到物品栏时，绝对不要忘记对物品的 Resource 调用 duplicate(true)；如果物品具有可变状态（弹药／耐久度），否则会覆盖全局资源。
• 绝对不要同步解析庞大的 JSON 存档文件；必须将繁重的解析任务交给 WorkerThreadPool，以防自动保存卡顿。
• 对高频路径中的 ID（状态、物品类型）绝对不要使用标准字符串；必须使用 StringName（&"chasing"），以获得指针速度的比较性能。
• 绝对不要判断浮点数是否完全相等（sanity == 0.0）；必须使用 is_equal_approx() 或阈值检查来触发确定性事件。
• 绝对不要编写依赖 Godot 3 SCREEN_TEXTURE 的屏幕读取着色器；必须使用带 hint_screen_texture 的 sampler2D。
• 绝对不要在没有剔除机制的情况下实例化精细的怪物网格或灯光；必须配置 visibility_range，以提高自动 HLOD 效率。
• 绝对不要依靠 AnimationPlayer 实现随机闪烁；使用 Tween 以编程方式干净地控制能量。
• 绝对不要通过 load() 同步加载体量大的惊吓场景或 4K 纹理；必须使用 ResourceLoader.load_threaded_request()，以免造成帧卡顿。
• 绝对不要对 CollisionShape3D 进行非均匀缩放；必须调整内部形状资源参数（半径、高度），以免物理行为异常。
• 绝对不要在安全屋内执行繁重的同步文件 I/O；必须使用 Thread 和 Mutex 进行后台保存，避免阻塞游戏主线程。
• 绝对不要通过类型转换来检查藏身点类型；必须使用 Object 元数据（set_meta），以便 AI 查询既高效又解耦。

---

🛠 专家级组件（scripts/）

原始专家模式（架构步骤中必须阅读）

• director_pacing.gd - 隐形的编排器，负责管理“锯齿状”紧张度波动和缓解时段。在接入任何节奏控制器/Director 之前必须阅读。
• predator_stalking_ai.gd - 双脑潜行者（Director 提示 + 真实感官），会避开视锥。在实现捕食者 AI 之前必须阅读。

模块化组件

• monster_los_check.gd - 与物理同步的射线检测，用于高性能可见性检查。
• flashlight_flicker.gd - 程序化光照干扰，营造紧张氛围。
• inventory_data_storage.gd - 用于稀疏资源管理的类型化数据结构。
• async_scare_loader.gd - 通过线程加载资源，避免跳吓时卡顿。
• spatial_noise_emitter.gd - 基于形状的声音感知，供感官型 AI 使用。
• item_state_duplicator.gd - 深度复制，用于管理独特的武器/物品状态。
• fog_claus_intensifier.gd - 操控体积雾以逐渐加深恐惧感。
• offscreen_logic_suspender.gd - 剔除摄像机视野外的 AI 处理逻辑。
• sanity_shader_manager.gd - 由实例统一变量驱动的失真效果。
• sanity_manager.gd - 应力/理智值处理管线，为抖动和音频总线提供数据。
• optimized_horror_state_machine.gd - 高速捕食者行为逻辑。

---

核心循环

1. 探索：玩家在危机四伏的环境中穿行。
2. 感知：玩家听到/看到危险的迹象。
3. 反应：玩家躲藏、奔跑或战斗（战斗能力受限）。
4. 生存：玩家抵达安全地点或解开谜题。
5. 缓解：短暂平静片刻，随后紧张感再次升高。

技能链

阶段	技能	目的
1. 氛围	godot-3d-lighting、godot-audio-systems	体积雾、动态阴影、空间音频
2. AI	godot-state-machine-advanced、godot-navigation-pathfinding、godot-raycasting-queries	猎手 AI、符合真实感的视线/声音感知
3. 玩家	godot-camera-systems、godot-genre-stealth、godot-physics-3d	探身/抖动、躲藏、CharacterBody3D 移动
4. 资源稀缺	godot-inventory-system	有限的电池、弹药、生命值
5. 逻辑 / 存档	此技能的 Director 脚本 + godot-save-load-systems	锯齿状节奏控制 + 安全屋的线程化存档

不要加载（按幻想方向）

幻想侧重点	加载	不要加载
仅氛围 / 雾 / 手电筒	fog_claus_intensifier.gd、flashlight_flicker.gd	捕食者 AI、视线检测、噪声、状态机
潜行者 / 双脑 AI	director_pacing.gd、predator_stalking_ai.gd、monster_los_check.gd、spatial_noise_emitter.gd	理智着色器、物品栏复制器、惊吓加载器
理智 / 压力特效	sanity_manager.gd、sanity_shader_manager.gd	物品栏资源稀缺脚本、异步惊吓加载器
资源稀缺 / 物品栏状态真实可信	inventory_data_storage.gd、item_state_duplicator.gd	浓雾增强器、理智着色器
避免卡顿的惊吓资源	async_scare_loader.gd	完整的 Director + 理智系统

架构概览

1. Director 系统（宏观 AI）

控制节奏，避免玩家长时间处于 100% 紧张状态。

必须阅读：director_pacing.gd — 不要临时粘贴一个紧张度枚举。将 Director 事件连接到玩家附近的调查目标，在平静阶段绝不要瞬间传送到玩家身上。

2. 感官感知（Micro AI）

让怪物拥有可信的感官（视觉 + 声音），Director 只能暗示，绝不允许作弊得毫无掩饰。

必读：predator_stalking_ai.gd，了解双脑协同；monster_los_check.gd + spatial_noise_emitter.gd，了解视线检测/声音。视觉检测优先使用 PhysicsDirectSpaceState3D.intersect_ray()，而非 Area 重叠检测。

3. 理智 / 压力系统

根据恐惧扭曲世界。

加载 sanity_manager.gd + sanity_shader_manager.gd，了解数值 → 震动/总线/着色器管线。使用 is_equal_approx / 区间判断阈值，绝不要使用 sanity == 0.0。

关键机制实现

节奏（锯齿波）

恐怖需要高潮和低谷。

1. 安全：存档房间。
2. 不安：奇怪的声音，灯光闪烁。
3. 恐惧：确定怪物就在附近。
4. 恐慌：追逐序列 / 战斗。
5. 缓解：逃回安全区域。

“双脑” AI

• Director（全知）：通过作弊让异形始终保持存在感（如果它距离太远，就把它传送得近一些；引导它前往玩家的大致位置）。
• 异形（仅依靠感官）：诚实的 AI。必须实际看到/听到玩家才能发起攻击。

3. 藏身点元数据系统

使用 set_meta / groups — 必读：predator_stalking_ai.gd + 配套技能 godot-genre-stealth。不要在此处直接粘贴藏身点教程。

4. 自适应音频（压力导致的声音闷化）

根据恐惧调整总线 LPF / 音量 — 必读：sanity_manager.gd + 配套技能 godot-audio-systems。

5. 安全屋多线程存档

使用线程处理检查点 I/O — 必读：配套技能 godot-save-load-systems（Thread/Mutex / WorkerThreadPool）。绝不要在安全屋的主线程上同步调用 FileAccess。

专家知识（按需加载）

**大模型无知规则：**如果通用 Agent 在阅读之前不会了解相关内容，就加载参考资料——绝不要删去专家补充内容。

• expert-horror-patterns.md — 恢复基础教学内容（架构、原因、实现深度）

参考资料

渐进式披露：只有在研究特定 API 时才打开官方文档链接；转向相关领域时才加载相关技能——不要预加载整个知识网络。

官方文档

• 体积雾与雾体 — 用于营造恐怖氛围的密度／反照率及受光照影响的散射。
• 环境与后期处理 — 用于呈现恐怖风格的 WorldEnvironment 色调映射、辉光和雾效模式。
• 灯光与阴影 — 用于昏暗室内场景的 SpotLight3D 手电筒光束、柔和阴影和偏差。
• 音频总线 — 用于压抑闷音和空间恐惧感的 LowPass／Reverb 总线效果。
• 射线投射 — 使用 PhysicsDirectSpaceState intersect_ray 实现可靠的怪物视线检测（而非 Area 重叠检测）。
• 导航简介（3D） — 用于捕食者追击路径和狭窄走廊中的避让遮罩。
• 后台加载 — 使用 ResourceLoader 线程化请求，避免跳吓素材加载时卡顿。
• 屏幕读取着色器 — 使用 hint_screen_texture 实现理智值失常扭曲效果（而非 Godot 3 的 SCREEN_TEXTURE）。
• 可见性范围 — 使用 GeometryInstance3D HLOD／剔除来处理高开销的怪物网格和灯光。
• 保存游戏 — 使用 FileAccess 模式实现安全屋检查点，无需另创格式。
• 使用线程 — 使用 Thread／Mutex 和 WorkerThreadPool 处理后台保存和繁重的解析工作。
• 资源 — 资源定义和 duplicate(true)，确保可变道具状态不会与全局变量发生别名。

相关技能

前置要求

• godot-project-foundations — 在连接 Director／WorldEnvironment 前，先了解场景树、自动加载和导入基础知识。
• godot-3d-lighting — 营造恐怖氛围所需的体积雾、SpotLight3D 手电筒和阴影预算。
• godot-audio-systems — 理智值／压力系统用于调节的总线、空间发声器和效果堆栈。

补充内容

• godot-navigation-pathfinding — 使用 NavigationAgent 追逐／搜索路径和避让，避免掠食者挤在走廊里。
• godot-state-machine-advanced — 使用 StringName 驱动掠食者微型 AI 的巡逻／追逐／搜索状态机。
• godot-raycasting-queries — 使用与物理同步的视线检测和形状查询实现感官感知，无需借助 Area 作弊。
• godot-shaders-basics — 使用实例 uniform 和读取屏幕的扭曲效果实现理智值特效。
• godot-inventory-system — 使用类型化 Resource 实现物品栏和资源稀缺机制（电池／弹药），并与视觉 UI 树分离。
• godot-camera-systems — 使用 VisibleOnScreenNotifier3D 实现镜头抖动、倾斜，以及由视锥体驱动的屏幕外 AI 挂起。
• godot-tweening — 以程序化方式实现手电筒闪烁和雾密度渐变，无需频繁调用 AnimationPlayer。
• godot-monte-carlo-balancer — 在发布前模拟 Director 的锯齿状峰值／缓解曲线和稀缺资源预算。
• godot-genre-stealth — 实现与感官 AI 共享的怀疑值计量表、藏身处和视锥追踪者模式。

下游／使用者

• godot-genre-survival — 实现复用恐怖游戏资源压力机制的稀缺循环和安全屋检查点。
• godot-save-load-systems — 为安全屋实现线程化／异步存档流程，避免主线程冻结。

主模块

• godot-master — 用于跨技能发现的库路由器和镜像模块入口。