godot-genre-stealth

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

检测与感知

• 绝不要使用二元的“看到／没看到”检测；必须使用渐进式检测计量表（0-100%），根据距离、光照水平和速度逐步累积。
• 绝不要使用标准的 RayCast3D 节点执行大量视野检测；必须使用**PhysicsDirectSpaceState3D.intersect_ray()**，直接向 PhysicsServer 查询，无需节点。
• 绝不要让 AI 透过实体几何体看见目标；必须在 AI 眼睛与玩家的采样点（头部／躯干／脚部）之间进行射线检测。
• 绝不要只使用一个采样点判断可见性；必须至少采样3 个点（头部、躯干、脚部），以避免目标部分处于掩体中时出现检测错误。
• 绝不要使用静态的“守卫路线”；必须实现动态调查，让守卫离开巡逻路线，检查可疑的声音或活动。
• 绝不要在线视范围内立即触发“检测”；必须使用带衰减率的检测计量表，为玩家提供“宽限窗口”以便脱身。
• 绝不要假设随机生成的导航网格点是安全的；必须通过朝威胁方向进行射线检测来验证掩体点，确保几何体确实能阻断视线。
• 绝不要忘记将守卫自身的 RID 传入射线检测排除数组；如果遗漏，射线会击中守卫自身的身体，导致错误阻挡。
• 绝不要对屏幕外的守卫运行复杂的 AI 检测；必须使用 VisibleOnScreenNotifier3D 暂停远处敌人的高负载逻辑。

系统与世界逻辑

• 绝不要使用简单的 distance_to() 检查来判断声音传播；必须计算声音沿导航路径的传播距离，以确定墙壁是否会阻挡噪声。
• 绝不要让正面战斗和潜行同样可行；必须确保“火力全开”会引来强力增援或进入高致命性状态，以维持潜行循环。
• 绝不要隐藏检测发生的“原因”；必须通过**UI 图标（?、!）**或音频喊话（“那是什么？”）提供即时反馈。
• 绝不要忽略 intersect_ray() 的返回值；必须先检查 is_empty()，以防止运行时崩溃。
• 绝不要假设射线检测不会击中守卫自身；必须在查询参数中排除守卫的 RID。

优化与性能

• 绝不要让 AI 与玩家脚本紧密耦合；必须使用鸭子类型（例如，if body.has_method("get_detected")），让守卫能够发现诱饵或尸体，而不依赖脆弱的耦合关系。
• 绝不要使用硬编码数组触发全基地警报；必须将守卫加入 "guards" 组，并使用 get_tree().call_group() 进行动态通知。
• 绝不要使用标准 String 表示 AI 状态；必须使用 StringName（&"alert"），以便在高频循环中进行 O(1) 指针级比较。
• 绝不要同步烘焙大型 NavigationMesh；必须使用 use_async_iterations，防止运行时烘焙导致主线程卡顿。
• 绝不要在游戏运行期间依赖 Node.find_child()；必须使用组或导出的引用，以 O(1) 的方式跟踪玩家。
• 绝不要让失去行动能力的身体继续启用 CollisionShapes；必须将其禁用或移至“尸体”层，以免干扰寻路。

---

🛠 专家组件（scripts/）

实现相应系统前必须阅读：

1. stealth_patterns.gd — 空间状态视线检测、锥体 DOT、听觉辅助函数
2. stealth_ai_controller.gd — 多点采样射线 + 排除 RID + 基于路径长度的听觉检测
3. stealth_vision_cone.gd / vision_cone_3d.gd — 视锥的制作

原始专家模式

• stealth_patterns.gd - 无节点视线检测、视锥测试、AI_Audible 总线、异步调查。
• stealth_ai_controller.gd - 使用 PhysicsDirectSpaceState 的警戒计量表 AI（而非 RayCast3D 节点）。

模块化组件

• stealth_vision_cone.gd - 2D/逻辑锥形区域辅助工具。
• vision_cone_3d.gd - 3D 锥形区域调试/查询辅助工具。
• visibility_manager.gd - 玩家暴露度/光线宝石聚合。
• light_detector.gd - 光照探测/重叠区域暴露度。
• sound_occlusion_manager.gd - AI 听觉的遮挡/总线路由。

---

核心循环

1. 躲藏/移动 → 2. 视野与光照暴露 → 3. 声音传播 → 4. 警戒升级 → 5. 调查/逃脱

决策树

感知

需求	操作
视线检测 + 排除自身/玩家 RID	必须 stealth_ai_controller.gd + stealth_patterns.gd
按光照调整检测	visibility_manager.gd / light_detector.gd
穿透几何体的听觉	通过 NavigationServer 计算路径长度（控制器）+ sound_occlusion_manager.gd

何时加载模块

任务	加载内容
守卫 AI 主干	patterns + ai_controller
创建锥形区域	vision_cone 脚本
玩家光线宝石	visibility + light_detector
嘈杂的世界道具	sound_occlusion_manager

不要将冗长的视野/警戒/能力教程粘贴到技能正文中——在此保留决策树，并根据脚本实现。

技能链

阶段	技能	用途
1. 物理	godot-raycasting-queries	空间状态视线检测
2. 导航	godot-navigation-pathfinding	调查/听觉路径
3. AI	godot-state-machine-advanced	IDLE→ALERT FSM
4. 音频	godot-audio-systems	AI_Audible 总线
5. 平衡	godot-monte-carlo-balancer	检测阈值

常见问题

问题	解决方案
每个守卫都使用 RayCast3D	使用多重采样 intersect_ray + RID 排除
听觉使用 distance_to	使用导航路径长度
屏幕外 CPU 占用	暂停 VisibleOnScreenNotifier

深入参考（按需查看）

主题	参考资料/脚本
设计支柱	design-principles.md
视野/声音/光照	ai-detection-system.md + stealth_ai_controller.gd
警戒 FSM 与 UI 反馈	alert-states.md + visibility_manager.gd
玩家工具（侧身探看、装置）	player-abilities.md
掩体与遭遇战布局	level-design.md
UI 信息传达	ui-communication.md

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；需要转到相关领域时加载关联技能——不要预先加载整个技能网络。

官方文档

• 射线投射 — 对于大量 AI 视线检测，比较节点投射与 PhysicsDirectSpaceState3D.intersect_ray()，避免滥用 RayCast3D。
• 物理简介 — 用于过滤视野射线、听觉球体和尸体图层的碰撞图层／遮罩。
• PhysicsDirectSpaceState3D — 用于复合视野检测和掩体验证的无节点 intersect_ray / intersect_shape 约定。
• PhysicsRayQueryParameters3D — 遮罩、排除 RID 和碰撞标志，确保守卫不会在视线查询中挡住自己。
• 灯光与阴影 — 驱动光宝石暴露度和阴影图层隐藏机制的 Omni/Spot 能量与阴影。
• 音频总线 — 专用的 AI 可听总线，可将响亮的脚步声／撞击声传入听觉系统。
• 导航简介（3D） — 用于巡逻和调查路径的区域、Agent 和异步烘焙。
• 使用导航路径 — 使用路径长度计算考虑墙壁的声音传播距离，而非原始 distance_to()。
• NavigationServer3D — 用于调查守卫的 map_get_path、随机掩体点和避让遮罩。
• 组 — 守卫／玩家／灯光组以及 call_group，可在整个基地触发警报，无需硬编码数组。
• VisibleOnScreenNotifier3D — 离开屏幕后暂停开销较大的检测，避免远处的 AI 消耗物理预算。
• 屏幕读取着色器 — hint_screen_texture 视野锥反馈叠加效果（不是 Godot 3 的 SCREEN_TEXTURE）。

相关技能

前置条件

• godot-project-foundations — 在连接守卫、灯光和玩家采样点之前，先了解场景树、组以及导入／项目设置。
• godot-physics-3d — 视野射线和听觉范围必须能够准确检测到 CharacterBody3D、图层／遮罩和碰撞形状。
• godot-raycasting-queries — 该类型游戏每帧都依赖 PhysicsServer 查询参数、RID 排除项和多采样视线检测方案。

补充

• godot-navigation-pathfinding — NavigationAgent 巡逻、调查目标，以及能绕过墙壁、根据路径长度判定的听觉系统。
• godot-ai-navigation — 视野传感器和感知堆栈，为怀疑/警戒状态机提供输入。
• godot-audio-systems — 3D 音流和总线布局，让 AI 能听到噪声，同时避免与玩家音效总线耦合。
• godot-3d-lighting — 光照能量、阴影和探针设置，让光照等级检测公平且易于理解。
• godot-state-machine-advanced — 使用 StringName 实现 IDLE/SUSPICIOUS/ALERTED/COMBAT 状态机，替代临时的字符串比较。
• godot-signal-architecture — alert_state_changed 和 detection-meter 信号，让 UI、喊话和 AI 保持解耦。
• godot-shaders-basics — 屏幕空间锥形色调和轮廓反馈，让玩家始终明白自己为何被发现。
• godot-camera-systems — 倾身/窥视，以及由视锥驱动的 VisibleOnScreenNotifier 挂起机制，用于控制屏幕外守卫的资源开销。
• godot-monte-carlo-balancer — 在发布难度设置前，模拟检测率、视野范围、听觉衰减和宽限窗口。

下游 / 使用方

• godot-genre-horror — 复用感官 AI 模式的追踪者视野锥、藏身点和怀疑度计量表。
• godot-combat-system — 当 ALERTED/COMBAT 打破潜行循环后，触发致命升级和击倒时机。

主模块

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