Godot 3D 场景基础

要解决什么问题

在 Godot 4.x 里新建或修补 3D 场景时，常见问题不是「缺模型」，而是场景能跑却全黑、视口里没有当前相机、父子节点局部/全局变换混用导致位移诡异，或是 GridMap 配了却一格都铺不出来。本技能面向 Godot 4.3+，把「能看的、能搭关卡的 3D 场景」拆成可执行的检查清单：变换、相机、光照、环境/后处理、材质与 GridMap 白盒。

技能如何组织工作流

核心约定是：一切 3D 对象都是带 Transform3D 的 Node3D。移动用 global_position，绕 Y 轴转用 rotate_y，对准目标用 look_at（注意 from/up 退化会出 NaN）。

典型步骤包括：

• 放置 Camera3D，设 current 或 make_current()，并配置 fov / near / far；跟拍相机可挂在 rig/pivot 上。
• 打光：DirectionalLight3D 当日光，OmniLight3D / SpotLight3D 作局部光，按需开阴影；无光且无环境时表面会黑。
• 挂 WorldEnvironment，用 Environment 管天空/背景、环境光、tonemap 与 glow、SSAO、雾等后处理。
• 在 MeshInstance3D 上赋 StandardMaterial3D 或 ShaderMaterial。
• 用 GridMap + MeshLibrary 在网格上铺关卡块（类似 2D TileMap 的 3D 版）。

技能内还给出跟拍相机、代码里搭太阳与环境、代码赋材质、向 GridMap 填格等模式示例，并指向 references/scene-and-environment.md 查 Transform、投影、阴影与 GI 等细节。

适用边界与常见坑

• 不要用它写空间着色器 → 用 godot-shaders；3D 物理与射线 → godot-physics；角色动画混合 → godot-animation；完整 FPS 模板 → fps-shooter 类技能。
• 非均匀缩放父 Node3D 会扭曲子碰撞与灯光，优先缩放网格资源或保持均匀 scale。
• HDR/glow 过曝时检查 tonemap_mode 与 glow 阈值；自发光在 filmic tonemap 下很容易炸 bloom。
• GridMap 未绑定 MeshLibrary 不会放置任何格子；set_cell_item(cell, -1) 可清空单元格。