Godot 2D/3D 相机系统：平滑跟随、抖动…

在 Godot 中实现玩家相机、过场动画或多相机系统时，避免抖动、穿模、边界跳变等常见相机问题。

适用场景

解决思路

1. 不要每帧使用 `global_position = target.global_position` 直接匹配位置，改用 `lerp()` 或开启 `position_smoothing_enabled = true` 实现平滑跟随。
2. 不要用 `offset` 做永久相机定位，`offset` 只用于抖动、摇摆或临时后坐力效果；永久构图用 `position`。
3. `Camera2D` 必须设置 `limit_smoothed = true`，否则硬边界会造成突兀的视觉停顿。
4. 同一视口中不要同时启用多个 `Camera2D` 节点，只有最后启用的相机会生效，需显式禁用非活动相机。
5. 使用 `SpringArm3D` 时必须设置碰撞遮罩（world/environment 层），否则会穿透地形和墙壁。
6. 不要用随机化 `position`（或对整个系统用 `randf` 作用于 `offset`）来实现屏幕抖动，应使用专门的 Trauma/Noise 系统叠加在跟随之上（参考 camera_shake_trauma_pro.gd）。
7. 不要把相机直接作为高速物理体的子节点作为默认方案，物理卡顿或父节点旋转会导致晕动症；优先使用 `RemoteTransform2D/3D` 或 phantom 解耦，并禁用旋转同步（参考 remote_transform_decoupling.gd、phantom_decoupling.gd）。
8. 3D 中使用 `look_at()` 时必须为 'Up' 向量提供回退保护，目标正上/正下方会导致相机翻转；使用守卫条件或四元数数学。
9. 小地图不要依赖 `SubViewport` 默认值，将 `render_target_update_mode` 设为 `UPDATE_WHEN_VISIBLE` 或更低的固定频率。
10. 缩放不要用线性插值，优先使用指数 lerp 或 Tween 的 `TRANS_CUBIC`。
11. 相机绑定方案选择：默认用 RemoteTransform/phantom（玩家为 CharacterBody、高速或会旋转时）；相机作为玩家子节点仅用于慢速俯视/锁定旋转/原型，且出现晕动症或物理抖动时禁用，绝不与位置覆盖式抖动组合；第三人称遮挡用 SpringArm3D + Camera3D（必须设置遮罩）。
12. 实现对应行为前必须先阅读匹配的脚本：屏幕抖动/打击感必须用 camera_shake_trauma_pro.gd（轻量版 camera_shake_trauma.gd）；物理体跟随默认必须用 remote_transform_decoupling.gd（备选 phantom_decoupling.gd）；自定义 3D 跟随弹簧前必须用 spring_lerp_camera_3d.gd；平台跳跃死区/拖拽用 deadzone_drag_margins.gd；2D 平滑跟随用 camera_follow_2d.gd；非线性缩放用 zoom_damping_controller.gd；跟随/静态/过场切换用 camera_state_machine.gd；电影构图用 cinematic_framing_logic.gd；小地图用 minimap_viewport_manager.gd；本地多人分屏用 split_screen_setup.gd；FPS 摇摆用 first_person_sway.gd；综合打击感用 juice_camera.gd；多目标 AABB 构图+缩放适配用 framing_box_camera_2d.gd；SpringArm 不足时的射线遮挡用 occlusion_aware_camera_3d.gd；调试用 trauma_debugger.gd。
13. 多目标构图：计算目标的 AABB → 将相机 lerp 到中心 → 带边距地缩放/调整距离以适配；打击感抖动只放在 `offset` 上，必须使用 framing_box_camera_2d.gd。
14. 3D 遮挡：优先用带世界碰撞遮罩的 `SpringArm3D`；自定义方案在理想相机位置与目标之间使用 `intersect_ray`（参考 occlusion_aware_camera_3d.gd，配合 godot-raycasting-queries）。
15. Trauma 审计：调参 camera_shake_trauma_pro.gd 时用调试绘制画出 trauma 衰减曲线，将 trauma_debugger.gd 接到 `get_trauma()`；绝不用原始 `randf` offset 演示来验证手感。
16. 多目标构图、自定义遮挡方案、2D/3D 跟随配方和电影转场必须参考 camera-expert-patterns.md；当黄金路径脚本已覆盖你的绑定方案时不要加载它。
17. 渐进式查阅：只在研究特定 API 时打开官方文档链接，只在路由到对等领域时加载相关技能，不要预加载整个知识网络。

适用边界 · 注意事项

• 当黄金路径脚本（如 camera_shake_trauma_pro.gd、remote_transform_decoupling.gd、spring_lerp_camera_3d.gd 等）已经覆盖你的相机绑定方案时，不要加载 camera-expert-patterns.md。
• 不要预加载整个官方文档和相关技能网络，只在研究特定 API 或路由到对等领域时才按需打开。
• 相机作为玩家子节点的方案不适用于会旋转或高速移动的物理体，也不适用于出现晕动症或物理抖动的情况，且绝不能与位置覆盖式抖动组合使用。