godot-camera-systems

绝不要做

• 绝不要每帧都使用 global_position = target.global_position——瞬间匹配位置会导致移动抖动。请使用 lerp() 或 position_smoothing_enabled = true。
• 绝不要用 offset 永久定位摄像机——offset 仅用于震动、摇摆或临时后坐力效果。永久取景请使用 position。
• 绝不要忘记为 Camera2D 设置 limit_smoothed = true——硬边界会导致画面骤停，十分突兀。
• 绝不要在同一视口中同时启用多个 Camera2D 节点——只有最后启用的摄像机会生效。请明确禁用未激活的摄像机。
• 绝不要在没有碰撞遮罩的情况下使用 SpringArm3D——它会穿过地形和墙壁。请将其设为世界／环境图层。
• 绝不要通过随机化 position（或仅将 randf 用于 offset）来实现屏幕震动——请使用专用的 Trauma/Noise 系统叠加在跟随效果上（camera_shake_trauma_pro.gd）。
• 绝不要默认将摄像机直接设为高速物理实体的子节点——物理抖动或父节点旋转会引起晕动症。优先使用 RemoteTransform2D/3D／phantom 解耦，并禁用旋转同步（remote_transform_decoupling.gd、phantom_decoupling.gd）。
• 绝不要在 3D 中使用 look_at() 而不为“Up”向量提供备用方案——目标正上方／正下方会导致摄像机翻转；请使用保护条件或 Quaternion 数学运算。
• 绝不要依赖 Mini-map 的 SubViewport 默认设置——请将 render_target_update_mode 设为 UPDATE_WHEN_VISIBLE 或更低的固定帧率。
• 绝不要对缩放使用线性插值——优先使用指数插值或 Tween TRANS_CUBIC。

---

父子关系／解耦（已解决）

Rig	适用情况	脚本
默认： RemoteTransform / phantom	玩家是 CharacterBody／高速移动／会旋转	remote_transform_decoupling.gd、phantom_decoupling.gd
摄像机是玩家的子节点	慢速俯视／旋转锁定／仅用于原型	明确注意：如果出现晕动症或物理抖动，请禁用；绝不要与覆盖位置的震动方式结合使用
SpringArm3D + Camera3D	第三人称遮挡处理	spring_lerp_camera_3d.gd——必须设置遮罩

可用脚本

强制要求：实现对应行为前请先阅读。项目代码中不得使用 randf 生成抖动样例。

• camera_shake_trauma_pro.gd — 屏幕抖动／冲击效果必须使用此脚本。
• camera_shake_trauma.gd — 轻量级创伤变体。
• remote_transform_decoupling.gd — 物理刚体跟随的默认强制选项。
• phantom_decoupling.gd — 稳定跟随的替代幻影方案。
• spring_lerp_camera_3d.gd — 编写自定义 3D 跟随弹簧前必须阅读。
• deadzone_drag_margins.gd — 平台游戏的拖动／死区。
• camera_follow_2d.gd — 平滑 2D 跟随辅助工具。
• zoom_damping_controller.gd — 非线性缩放。
• camera_state_machine.gd — 跟随／静态／电影化过渡。
• cinematic_framing_logic.gd — 三分法／前方留白。
• minimap_viewport_manager.gd — SubViewport 更新模式。
• split_screen_setup.gd — 本地多摄像机视口。
• first_person_sway.gd — FPS 中基于偏移量的上下晃动／摆动。
• juice_camera.gd — 综合表现力辅助工具。
• framing_box_camera_2d.gd — 多目标 AABB 构图 + 缩放适配。
• occlusion_aware_camera_3d.gd — SpringArm 不够用时进行射线检测遮挡。
• trauma_debugger.gd — 屏幕上的创伤衰减曲线（调试版本）。

专家级摄像机架构

1. 多目标构图

计算目标的 AABB → 将摄像机插值至中心 → 调整缩放／距离以留出边距。表现力抖动仅作用于 offset。强制要求：framing_box_camera_2d.gd。

2. 遮挡（3D）

优先使用带世界碰撞遮罩的 SpringArm3D；自定义摄像机组可在理想摄像机位置与目标之间调用 intersect_ray — occlusion_aware_camera_3d.gd（同领域 godot-raycasting-queries）。

3. 创伤审查

调试绘制创伤衰减曲线，在调整 camera_shake_trauma_pro.gd 时使用 — 将 trauma_debugger.gd 连接到 get_trauma()。切勿使用原始 randf 偏移演示来验证效果。

多目标构图、自定义遮挡摄像机组、2D／3D 跟随方案和电影化过渡必须使用：camera-expert-patterns.md。如果黄金路径脚本已覆盖你的摄像机组，则不要加载。

参考

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

官方文档

• Camera2D — 位置／拖动边距、limit_*／limit_smoothed 和 position_smoothing_*，为 2D 跟随、死区和关卡边界提供基础。
• Camera3D — 投影、look_at、当前摄像机规则和环境覆盖设置，用于第三人称、FPS 和电影级 3D 摄像机装置。
• 带弹簧臂的第三人称摄像机 — 解释仅将 Camera3D 设为子节点为何会穿过几何体，以及 SpringArm3D 的长度／形状如何保持视野清晰。
• SpringArm3D — 碰撞遮罩、边距和弹簧长度 API，是确保第三人称遮挡拉近效果可靠的前提。
• 使用视口 — 多摄像机、SubViewport 架构，以及分屏／小地图视图何时共享或隔离世界。
• SubViewport — render_target_update_mode 和音频监听器标志决定小地图和本地合作模式的 GPU／音频开销。
• RemoteTransform2D — 无需将摄像机设为物理体的子节点，即可让摄像机位置与玩家旋转／缩放分离。
• 插值 — Lerp／指数跟随和缩放阻尼数学，避免自定义摄像机显得机械或抖动。
• 物理插值（简介） — 解释渲染帧与物理帧不一致时，跟随 CharacterBody 的摄像机为何会卡顿。
• FastNoiseLite — 使用相干噪声实现创伤／偏移抖动，避免直接用 randf 导致位置剧烈跳动。
• PathFollow2D — 沿 Path2D 使用 Tween 移动摄像机时，通过进度比例驱动电影级路径。
• 鼠标和输入坐标 — 滚轮缩放和鼠标视角的坐标空间，确保 FPS 俯仰／偏航和战术缩放在不同视口中保持一致。

相关技能

前置条件

• godot-project-foundations — 拉伸模式、默认视口和输入映射设置决定了 Camera2D 限制和 SubViewport 尺寸在跟随脚本运行前的表现。
• godot-gdscript-mastery — 类型化节点、_physics_process 与 _process 的区别，以及状态机和弹簧跟随中使用的 Tween／await 模式。
• godot-input-handling — 捕获鼠标、视角轴和鼠标滚轮事件用于 FPS 视角、缩放阻尼和摄像机环绕控制。

互补技能

• godot-tweening — 相机在跟随、静态和电影模式之间切换时，应使用 Tween（缓动方式/缓动类型），而不是硬切或线性缩放。
• godot-characterbody-2d — 前瞻和死区相机需要获取其跟随的平台游戏角色主体的真实速度和地面状态。
• godot-physics-3d — SpringArm 碰撞层和 CharacterBody3D 运动，是稳定第三人称相机与 FPS 摇摆父节点在 3D 中的对应实现。
• godot-raycasting-queries — 不使用 SpringArm 的自定义遮挡感知相机，仍需正确设置 intersect_ray 遮罩和排除项。
• godot-state-machine-advanced — 当 camera_state_machine 超出简单枚举的范畴时，将跟随、静态、电影模式（以及过场动画所有权）形式化。
• godot-signal-architecture — 应通过信号驱动震动值增加、过场动画交接和多目标取景，避免游戏逻辑访问相机内部状态。

下游 / 使用方

• godot-performance-optimization — 调整更新模式后，如果 SubViewport 小地图、分屏或始终启用的辅助相机仍占用大量帧时间，则需进一步优化。
• godot-monte-carlo-balancer — 模拟震动强度、缩放公平性和多目标取景，确保相机效果不会遮挡命中框或竞技信息。
• godot-adapt-single-to-multiplayer — 本地合作游戏需要为每位玩家设置相机并分配监听器所有权时，可复用分屏 SubViewport 模式。
• godot-debugging-profiling — 在重写跟随计算逻辑之前，使用监视器和可视化工具确认相机抖动的来源（物理帧、RemoteTransform、震动值）。

主入口

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