3d-essentials

Godot 4.3+ 中的 3D 基础

所有示例均面向 Godot 4.3+，不使用已弃用的 API。首先展示 GDScript，然后展示 C#。

相关技能： rendering-pipeline 用于选择渲染器、制定光照策略、设置抗锯齿和分辨率缩放；player-controller 用于 CharacterBody3D 移动；physics-system 用于 3D 碰撞形状和射线检测；camera-system 用于 Camera3D 跟随和过渡；shader-basics 用于空间着色器和后期处理；godot-optimization 用于 3D 性能调优；animation-system 用于 AnimationTree 和 3D 动画混合。

---

1. 3D 坐标系与核心节点

坐标系

Godot 使用右手坐标系，单位为米（1 个单位 = 1 米）：

轴	方向	颜色
X	右	红色
Y	上	绿色
Z	屏幕外（+Z 朝向观察者）	蓝色

摄像机和灯光默认沿 -Z 方向指向。当角色“面朝前方”时，它们朝向 -Z。

必备 3D 节点

节点	用途
Node3D	基础变换节点——位置、旋转、缩放
MeshInstance3D	使用材质显示网格
Camera3D	渲染 3D 场景必需——透视或正交投影
DirectionalLight3D	太阳／月亮——平行光线，开销最低的灯光
OmniLight3D	点光源——向各个方向发光
SpotLight3D	锥形光源——手电筒、聚光灯
WorldEnvironment	天空、雾效、色调映射、后期处理
Decal	将纹理投射到表面上
GPUParticles3D	GPU 驱动的粒子效果
CSGBox3D 等	构造实体几何——用于原型制作
GridMap	基于 3D 图块构建关卡

Godot 4.7+： GridMap 提供内部八叉树节点供空间查询使用（cell_octant_size、get_used_octants()、get_octants_in_bounds() 等），因此你可以将处理范围限定在某个区域，而不必遍历每个单元格。CSGShape3D 新增了 autosmooth / smoothing_angle，用于自动平滑面。完整的方法表和语义说明：references/godot-4.7-additions.md

最小化 3D 场景

World (Node3D)
├── Camera3D
├── DirectionalLight3D
├── WorldEnvironment
├── MeshInstance3D (floor)
└── MeshInstance3D (player model)

---

2. 材质

StandardMaterial3D 与 ShaderMaterial

材质	用途	说明
StandardMaterial3D	大多数 3D 对象——PBR 工作流	无需编写代码；通过检查器设置
ORMMaterial3D	与 Standard 相同，但使用打包的 ORM 纹理	在一张纹理中包含环境光遮蔽、粗糙度和金属度
ShaderMaterial	自定义效果——卡通、水面、溶解	需要空间着色器代码

StandardMaterial3D 的关键属性

PBR 核心属性：albedo_color / albedo_texture（基础颜色）、metallic（0 为电介质 → 1 为金属）、roughness（0 为镜面 → 1 为哑光）、搭配 normal_enabled 的 normal_texture（表面细节）、ao_texture（环境光遮蔽）。添加 emission + emission_energy_multiplier 可实现自发光；使用 heightmap_texture 实现视差效果；使用 rim / clearcoat 增添材质特色。

透明模式

优先使用 Alpha Scissor（速度快、有阴影的镂空）或 Alpha Hash（抖动效果——适用于头发），而不是普通 Alpha（速度慢、无阴影）；对于大部分不透明、边缘透明的网格，适合使用 Depth Pre-Pass。

对比表见 references/materials-and-lighting-recipes.md。

通过代码设置材质与材质实例化

在运行时创建 StandardMaterial3D，将其赋给 mesh.material_override，并通过 Tween 控制自发光闪烁。使用 .duplicate() 创建每个实例各自的副本，这样更改单个网格的材质不会影响其他网格。

完整的 GDScript 和 C# 示例配方（基础材质设置、自发光闪烁、逐实例复制、动态 OmniLight3D 爆炸）见 references/materials-and-lighting-recipes.md。

---

3. 光照

灯光类型对比

灯光	形状	阴影	成本	最大可见数量
DirectionalLight3D	平行光线	PSSM	最低	8（Forward+）
OmniLight3D	球体	立方体／双抛物面	中等	512 个聚类*
SpotLight3D	圆锥体	单张纹理	低	512 个聚类*
AreaLight3D（4.7+）	矩形	PCSS 软阴影	最高	—

*Forward+ 中，全向灯、聚光灯、贴花和反射探针共用 512 个聚类元素槽位。

灯光属性

关键参数：light_color、light_energy（HDR——允许使用大于 1 的值）、shadow_enabled（会显著影响性能）、directional_shadow_mode、directional_shadow_max_distance（值越低，阴影越锐利）。

属性表以及 GDScript + C# 太阳灯光设置代码片段，请参阅 references/materials-and-lighting-recipes.md。

AreaLight3D（Godot 4.7+）

AreaLight3D 沿节点的 -Z 方向从矩形发光（霓虹灯管、屏幕、柔光箱面板），并通过 light_size 控制 PCSS 软阴影。移动平台支持有限，Compatibility 无法投射面光源阴影；在 Forward+ 中，每个可见的面光源都会增加所有渲染对象的聚类光照开销，因此仅在过场动画或高端目标平台中使用。

完整属性表以及 GDScript + C# 设置方法，请参阅 references/materials-and-lighting-recipes.md。

动态点光源

在运行时生成 OmniLight3D，通过补间动画控制其能量，并在动画完成后调用 queue-free。常用于爆炸、枪口闪光和魔法效果。

完整的 GDScript 和 C# 方法，请参阅 references/materials-and-lighting-recipes.md。

阴影配置与烘焙模式

处理阴影痤疮时，优先使用 shadow_normal_bias 而非 shadow_bias；将 directional_shadow_max_distance 设为所需的最小值（通常为 50–100 m）。烘焙模式：Disabled（完全实时，不受 GI 影响）、Static（完全烘焙，运行时无开销）、Dynamic（默认；间接光烘焙到光照贴图中，直接光实时计算）。

阴影调节表和烘焙模式表，请参阅 references/materials-and-lighting-recipes.md。

---

4. 环境与后期处理

通过包含 Environment 资源的 WorldEnvironment 节点配置全局渲染——天空背景、色调映射、辉光、SSR、SSAO/SSIL/SDFGI、景深。在 Environment 资源中选择色调映射模式（Linear、Reinhard、Filmic、ACES，或 Godot 4.4 起提供的 AgX）。Forward+ 支持 SSAO、SSIL、SSR 和 SDFGI；Mobile 渲染器不支持这些效果，Compatibility 仅支持 SSAO（4.6 起）。

完整设置方法（天空选项、色调映射模式、所有后期处理效果、4.6+ 的辉光混合与默认值变更、AgX 的 tonemap_agx_white / tonemap_agx_contrast 控件，以及 4.6+ 的 SSR 质量升级），请参阅 references/environment-and-post.md。

Godot 4.7+：display/window/hdr/request_hdr_output 用于请求 HDR 显示输出（启动时读取；运行时切换 Window.hdr_output_requested）。⚠️ rendering/reflections/sky_reflections/roughness_layers 的默认值在 4.6.0–4.6.1 中为 7，此后再次变为 8。详情请参阅 references/environment-and-post.md。

5. 全局光照

五种 GI 选项在画质和成本之间各有取舍：无（仅环境光）→ ReflectionProbe（局部）→ LightmapGI（画质最佳，烘焙）→ VoxelGI（适用于小型／中型动态场景）→ SDFGI（适用于大型开放世界）。VoxelGI 和 SDFGI 需要 Forward+；LightmapGI 可在三种渲染器上运行，但只能在 Forward+ 或 Mobile 编辑器中烘焙。下方 4.5+ 小节适用于各种 GI 方法。

请参阅 references/global-illumination.md，了解各方法对比表、ReflectionProbe 场景与代码示例、LightmapGI 烘焙工作流和 SDFGI 配置。

镜面遮蔽与弯曲法线贴图（Godot 4.5+）

从 4.5 开始，所有渲染器中的间接镜面光都会根据到达各像素的环境光进行衰减。此功能默认启用，无需重新烘焙；可通过 rendering/reflections/specular_occlusion/enabled 全局禁用，或通过着色器中的 render_mode specular_occlusion_disabled 禁用。StandardMaterial3D 的 Bent Normal 插槽可使用烘焙的弯曲法线贴图，为重要资产提供更好的间接光照效果。

请参阅 references/global-illumination.md，了解各功能的适用场景以及弯曲法线的设置方法。

---

6. 雾效

雾效分为三层：在 WorldEnvironment.environment 中设置的深度／高度雾（成本低，适用于所有渲染器）、体积雾（仅限 Forward+，可沿深度方向呈现光束效果），以及用于局部雾效的 FogVolume 节点（室内房间、深坑、大气体积）。

请参阅 references/fog-recipes.md，查看完整的 GDScript 和 C# 示例，包括深度／高度雾设置、体积雾参数与性能说明，以及 FogVolume 的放置方法。

⚠️ Godot 4.7 中的变更： 新增项目设置 rendering/environment/fog/use_legacy_blending（默认值为 false），可恢复 Godot 4.5 及更早版本中的体积雾混合效果（GH-119414；4.6 分支也包含此设置）。混合方式本身在 4.6 中发生了变化，变得更符合物理规律，因此从 4.5 升级后，经过调校的雾效会显得更亮（GH-112494）。启用此设置即可精确恢复旧版效果；否则请降低雾效密度或灯光的 Volumetric Fog Energy。

7. Decal

Decal 节点会将纹理投射到其包围盒内的表面上，适用于弹孔、血迹飞溅、地面细节和标牌。Forward+ 和 Mobile 可渲染 Decal；Compatibility 不支持。性能开销随过度绘制和 Decal 数量增加。

请参阅 references/decals.md，了解场景设置、运行时生成示例（GDScript + C#）以及各渲染器的 Decal 数量限制。

---

8. 优化——LOD、剔除、MultiMesh

有四种工具：自动网格 LOD（在导入时或按 MeshInstance3D 单独设置）、用于分阶段切换的手动 VisibilityRange、通过 OccluderInstance3D 进行遮挡剔除，以及用于在一次绘制调用中渲染数千个相同网格的 MultiMeshInstance3D。

请参阅 references/lod-and-culling.md，查看每种工具的设置示例以及运行时填充 MultiMesh 的示例。

9. 渲染器对比

应在构建视觉效果前选择渲染器：Forward+（桌面端默认）是唯一支持 SDFGI 和体积雾的渲染器；Mobile 牺牲这两项功能，以适配基于 tile 的 GPU 并提升性能；Compatibility（GLES3 级别）则完全不支持大部分高级光照。假设支持 SDFGI 的建议在另外两种渲染器上会悄然失效。

完整的渲染器功能对比表和选择指南：references/renderer-comparison.md

---

10. 常见问题

快速症状 → 原因 → 解决方法对照表，涵盖黑屏场景、没有环境光时物体发暗、阴影痤疮和阴影悬浮、阴影跳变、材质效果平淡、Decal 不可见、透明排序伪影、SDFGI 漏光、体积雾缺失，以及 MultiMesh 实例不可见。

请参阅 references/common-pitfalls.md，查看完整对照表。

---

11. 实施清单

• 场景包含 Camera3D、至少一个光源和 WorldEnvironment
• 环境设有天空材质（程序生成或 HDR 全景图），用于提供环境光和反射光
• 已设置色调映射模式（追求真实效果时使用 Filmic 或 ACES；追求物理准确时使用 AgX（4.4+））
• DirectionalLight3D 已启用阴影，并调整 shadow_normal_bias 以避免阴影痤疮
• directional_shadow_max_distance 已设为满足需求的最小值（通常为 50–100m）
• 静态几何体使用带有适当 PBR 纹理（反照率、法线、粗糙度、金属度）的 StandardMaterial3D
• 尽可能让透明材质使用 Alpha Scissor 或 Alpha Hash，而不是 Alpha（提升性能并支持阴影）
• 在带有反射表面的房间或区域中放置 ReflectionProbes
• 根据项目需求选择 GI 方法（静态场景使用 LightmapGI，大型动态场景使用 SDFGI，小型动态场景使用 VoxelGI）
• 导入时启用网格 LOD（glTF/Blend 默认启用；请检查 OBJ 文件）
• 对遮挡严重的场景（室内、城市）启用并烘焙遮挡剔除
• 对实例化几何体（草、树木、道具）使用 MultiMeshInstance3D，而不是单独的节点
• 渲染器与目标平台匹配（桌面平台使用 Forward+，移动平台使用 Mobile，Web 使用 Compatibility）
• 保持启用镜面遮蔽（自 Godot 4.5 起默认启用）；如果反射显得过暗，可通过 rendering/reflections/specular_occlusion/enabled 有意将其禁用
• 表面细节复杂的主体资产在 StandardMaterial3D 的 Bent Normal 插槽中使用弯曲法线贴图，以改善间接光照（Godot 4.5+）
• 升级到 Godot 4.6 后，如果外观发生变化，请重新调整辉光设置（默认混合模式现在为 Screen，且辉光会在色调映射之前混合）
• 使用 AgX 色调映射器时，调整 AgX 的 tonemap_agx_white 和 tonemap_agx_contrast，以精准控制外观（Godot 4.6+）
• 升级后重新检查体积雾（混合方式在 4.6 中发生变化；4.7 新增 use_legacy_blending）和天空反射（roughness_layers 在 4.6.0–4.6.1 中有所不同）