godot-genre-shooter-fps

必读脚本（从这里开始）

1. fps_camera_look.gd — 原始 _input 鼠标视角控制（偏航／俯仰）
2. fps_movement_logic.gd — 加速度／摩擦／空中控制
3. hitscan_weapon_query.gd — 基于空间状态的即时命中检测
4. weapon_bobbing_system.gd — 视图模型摆动／摇晃

另外：procedural_recoil_handler.gd、hitscan_weapon_logic.gd、advanced_fps_controller.gd、weapon_state_machine.gd、frame_perfect_input.gd、bullet_decal_spawner.gd、weapon_spread_calc.gd、server_projectile_instance.gd、player_anim_bridge.gd、recoil_system.gd（模式 + 扩散）、aim_assist.gd（手柄摩擦／磁吸）。
advanced_weapon_controller.gd 涵盖通用理论——FPS 手感请通过上述脚本实现；TPS 类型路由请交由同领域的技能处理。

核心循环

移动／视角控制 → 瞄准 → 开火（即时命中检测）→ 后坐力恢复 → 获取目标

切勿执行（FPS）

枪战与命中判定

• 切勿在 _process 中检测命中——应使用 _physics_process + intersect_ray。
• 切勿只对枪械网格应用后坐力——应同时作用于摄像机 + 扩散／散布。
• 切勿信任客户端提供的伤害数据——使用服务器权威判定 + 延迟补偿。
• 切勿忘记为玩家 RID 设置 exclude / add_exception。
• 切勿使用 == 比较浮点冷却时间——应使用 is_equal_approx。

输入与移动

• 切勿在 _physics_process 中轮询鼠标——视角控制应使用 _input / _unhandled_input。
• 切勿将视角变化累积到原始 Transform3D 中——应以浮点数存储偏航／俯仰。
• 切勿在调用 move_and_slide() 前将速度乘以 delta。
• 切勿使用 Transform3D.looking_at 获取枪口朝向——应使用 -transform.basis.z。

润色

• 切勿只用单个 AudioStreamPlayer 播放枪声——应叠加机械声、射击声和尾音。
• 切勿让弹孔贴花永久保留——应使其渐隐／放入对象池（bullet_decal_spawner.gd）。
• 切勿将武器属性硬编码——应使用 WeaponData Resources。
• 切勿用普通 String 表示频繁使用的武器状态——应使用 StringName。

进阶 FPS（保留）

视图模型摇晃／摆动

程序化正弦摆动 + 视角摇晃——weapon_bobbing_system.gd。

跨步

在 move_and_slide() 后检测到 is_on_wall() 时，从 step_height 位置向前／向下发射射线；抬升至台阶顶部以通过楼梯。

战术侧倾

根据 Input.get_axis("lean_left","lean_right") 调整摄像机 Z 轴旋转 + 局部 X 轴偏移，并使用 lerp 平滑。

通用武器理论

即时命中与抛射物、扫射模式以及不依赖 FPS 枪械框架的网络预测细节 → godot-genre-shooter + 战斗／多人游戏相关补充内容。使用 hitscan_weapon_query.gd + procedural_recoil_handler.gd + recoil_system.gd 实现 FPS 开火流程。

必读：有关即时命中／抛射物权衡、三层后坐力、瞄准辅助、武器平衡矩阵和客户端预测的内容，请参阅 fps-weapon-theory.md。完成必读脚本阅读后，除非要扩展摆动／跨步／侧倾功能，否则不要加载该文档。

参考

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

官方文档

• 射线投射 — PhysicsDirectSpaceState3D intersect_ray 模式，用于注册即时命中，无需使用 Area3D 弹道。
• 物理简介 — 碰撞层／遮罩、用于排除玩家的层，以及枪战中物理刻与视觉帧的区别。
• 使用 3D 变换 — 用于瞄准、后坐力和枪口方向的基轴与 -transform.basis.z 前向向量。
• 使用 InputEvent — _input 与 _physics_process 的区别，让鼠标视角保持零延迟，同时让移动与物理同步。
• 鼠标和输入坐标 — 相对鼠标运动、捕获，以及用于瞄准射线的屏幕中心投影。
• 控制器、游戏手柄和操纵杆 — 模拟瞄准轴与死区，是瞄准辅助摩擦／磁吸效果的基础。
• 使用 Decal — 使用 Decal 节点投射弹孔，而非使用 Sprite3D／QuadMesh 贴花。
• 高级多人游戏 — RPC 权限与开火事件模式，用于实现由服务器验证的即时命中，无需同步每颗子弹。
• 使用 AnimationTree — 用于待机／瞄准／开火／装弹的混合／状态机，且无需在表达式中使用 !。
• 资源 — 使用 WeaponData Resource 保存属性（伤害、后坐力、散布），而非将常量硬编码在类中。
• 音频流 — 通过分层的机械声／枪声／尾音流，增强枪声的厚重感。
• 使用 Servers 进行优化 — 使用 RenderingServer RID 路径实现大量视觉弹体效果，避免 SceneTree 过载。

相关技能

前置条件

• godot-project-foundations — 在搭建 FPS 控制器和连接 WeaponData 之前，了解场景树、InputMap 操作和 Resource 导入基础。
• godot-input-handling — 鼠标捕获、操作缓冲，以及视角与移动的分离，是精准开火时机和摄像机视角的基础。
• godot-raycasting-queries — 与物理同步的射线／形状查询和排除 RID，是注册即时命中的基础。

补充

• godot-camera-systems — FOV 冲击、倾斜枢轴和抖动叠加，可与程序化后坐力和武器起伏配合。
• godot-combat-system — 通过鸭子类型应用伤害，并在 hitscan / projectile 确认路径中共享命中区域倍率。
• godot-audio-systems — 总线布线和池化的一次性音效，可分层播放枪声，无需共用单个 AudioStreamPlayer。
• godot-multiplayer-networking — 权威射击 RPC 和不可靠移动传输模式，用于竞技场景中的命中验证。
• godot-adapt-single-to-multiplayer — 在进行延迟补偿射击验证前，搭建客户端预测 / 服务端协调框架。
• godot-state-machine-advanced — 使用 StringName 构建射击 / 装填 / 待机状态机，避免武器状态依赖字符串。
• godot-animation-tree-mastery — 由本地速度桥接驱动的 AnimationTree 参数和混合空间。
• godot-performance-optimization — 为子弹视觉效果和命中效果优化对象池、Decal 预算和 RenderingServer RID 密度。
• godot-genre-shooter — 当项目并非以 FPS 为核心时，了解更广泛的 TPS / 混合射击游戏架构。

下游 / 使用方

• godot-monte-carlo-balancer — 在发布平衡表之前，模拟武器不对称矩阵、TTK 区间和散布 / 后坐力参数。
• godot-genre-battle-royale — 大规模相关性和延迟补偿战斗，在 BR 对局中复用 FPS hitscan / 后坐力手感。

主入口

• godot-master — 库路由器和镜像模块入口；在确定哪个领域技能负责跨领域 FPS 问题时打开。