Back to Details

3d-essentials

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

3D Essentials in Godot 4.3+

Godot 4.3+ 3D必备知识

All examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, then C#.
Related skills: player-controller for CharacterBody3D movement, physics-system for 3D collision shapes and raycasting, camera-system for Camera3D follow and transitions, shader-basics for spatial shaders and post-processing, godot-optimization for 3D performance tuning, animation-system for AnimationTree and 3D animation blending.
所有示例均面向Godot 4.3+，不包含已弃用的API。代码示例优先展示GDScript版本，其后是C#版本。
相关技能： player-controller 用于CharacterBody3D移动，physics-system 用于3D碰撞形状与射线检测，camera-system 用于Camera3D跟随与过渡，shader-basics 用于空间着色器与后处理，godot-optimization 用于3D性能调优，animation-system 用于AnimationTree与3D动画混合。

1. 3D Coordinate System & Core Nodes

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

Coordinate System

坐标系

Godot uses a right-handed coordinate system with metric units (1 unit = 1 meter):
AxisDirectionColor
XRightRed
YUpGreen
ZOut of screen (+Z toward viewer)Blue
Cameras and lights point along -Z by default. When a character "faces forward," they look along -Z.
Godot采用右手坐标系，单位为公制（1单位 = 1米）：
轴方向颜色
X向右红色
Y向上绿色
Z穿出屏幕（+Z朝向观察者）蓝色
相机和光源默认沿**-Z**方向指向。当角色「面朝前方」时，其朝向为-Z方向。

Essential 3D Nodes

必备3D节点

NodePurpose
Node3D
Base transform node — position, rotation, scale
MeshInstance3D
Displays a mesh with a material
Camera3D
Required to render 3D — perspective or orthogonal
DirectionalLight3D
Sun/moon — parallel rays, cheapest light
OmniLight3D
Point light — emits in all directions
SpotLight3D
Cone light — flashlights, spotlights
WorldEnvironment
Sky, fog, tonemap, post-processing
Decal
Projected texture onto surfaces
GPUParticles3D
GPU-driven particle effects
CSGBox3D
etc.		Constructive Solid Geometry — prototyping
GridMap
3D tile-based level building
Godot 4.7+: 
GridMap
exposes its internal octants for spatial queries (
cell_octant_size
, 
get_used_octants()
, 
get_octants_in_bounds()
and friends) so you can scope work to a region instead of walking every cell. 
CSGShape3D
gains 
autosmooth
/ 
smoothing_angle
for automatic face smoothing. Full method table and semantics: references/godot-4.7-additions.md
节点用途
Node3D
基础变换节点——控制位置、旋转、缩放
MeshInstance3D
显示带材质的网格
Camera3D
渲染3D场景的必备节点——支持透视或正交投影
DirectionalLight3D
太阳光/月光——平行光线，性能开销最低的光源
OmniLight3D
点光源——向所有方向发射光线
SpotLight3D
锥形光源——手电筒、聚光灯
WorldEnvironment
天空、雾效、色调映射、后处理
Decal
投射到表面的纹理
GPUParticles3D
GPU驱动的粒子效果
CSGBox3D
等		构造实体几何（CSG）——用于原型制作
GridMap
基于3D瓦片的关卡搭建
Godot 4.7+： 
GridMap
对外暴露了内部的八分圆（octant）用于空间查询（
cell_octant_size
、
get_used_octants()
、
get_octants_in_bounds()
等相关方法），因此你可以将工作范围限定在特定区域，而非遍历所有单元格。
CSGShape3D
新增了 
autosmooth
/ 
smoothing_angle
参数，可自动进行面平滑处理。完整方法表与语义说明见：references/godot-4.7-additions.md

Minimal 3D Scene

最简3D场景

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

2. Materials

2. 材质

StandardMaterial3D vs ShaderMaterial

StandardMaterial3D 与 ShaderMaterial 对比

MaterialUse ForNotes
StandardMaterial3D
Most 3D objects — PBR workflowNo code; Inspector-driven
ORMMaterial3D
Same as Standard but with packed ORM textureOcclusion+Roughness+Metallic in one texture
ShaderMaterial
Custom effects — toon, water, dissolveRequires spatial shader code
材质类型适用场景说明
StandardMaterial3D
大多数3D对象——PBR工作流无需代码；通过Inspector（检查器）配置
ORMMaterial3D
与StandardMaterial3D用途相同，但使用打包的ORM纹理遮挡+粗糙度+金属度整合在一张纹理中
ShaderMaterial
自定义效果——卡通、水、溶解效果需要编写空间着色器代码

Key StandardMaterial3D Properties

StandardMaterial3D 核心属性

The PBR core: 
albedo_color
/ 
albedo_texture
(base color), 
metallic
(0 dielectric → 1 metal), 
roughness
(0 mirror → 1 matte), 
normal_map
(surface detail), 
ao_texture
(ambient occlusion). Add 
emission
+ 
emission_energy_multiplier
for self-illumination, 
heightmap_texture
for parallax, 
rim
/ 
clearcoat
for material flair.
PBR核心属性包括：
albedo_color
/ 
albedo_texture
（基础颜色）、
metallic
（0为电介质→1为金属）、
roughness
（0为镜面→1为哑光）、
normal_map
（表面细节）、
ao_texture
（环境遮挡）。添加 
emission
+ 
emission_energy_multiplier
可实现自发光效果，
heightmap_texture
用于视差效果，
rim
/ 
clearcoat
用于增强材质质感。

Transparency Modes

透明度模式

Prefer Alpha Scissor (fast, shadowed cutouts) or Alpha Hash (dithered — hair) over plain Alpha (slow, no shadows); Depth Pre-Pass suits mostly-opaque meshes with transparent edges.
See references/materials-and-lighting-recipes.md for the comparison table.
优先使用Alpha Scissor（速度快，支持带阴影的镂空效果）或Alpha Hash（抖动效果——适用于毛发），而非普通Alpha（速度慢，不支持阴影）；深度预通道（Depth Pre-Pass）适用于边缘透明、主体不透明的网格。
对比表详见 references/materials-and-lighting-recipes.md

Setting Materials from Code & Material Instancing

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

Create a 
StandardMaterial3D
at runtime, assign to 
mesh.material_override
, and drive emissive flashes via Tween. Use 
.duplicate()
to make per-instance copies so changing one mesh's material doesn't affect others.
See references/materials-and-lighting-recipes.md for the full GDScript and C# recipes (basic material setup, emissive flash, per-instance duplicate, dynamic OmniLight3D explosion).
在运行时创建 
StandardMaterial3D
，赋值给 
mesh.material_override
，并通过Tween控制自发光闪烁效果。使用 
.duplicate()
方法创建每个实例的专属副本，这样修改一个网格的材质不会影响其他网格。
完整的GDScript和C#示例（基础材质设置、自发光闪烁、按实例复制、动态OmniLight3D爆炸效果）详见 references/materials-and-lighting-recipes.md

3. Lighting

3. 光照

Light Types Comparison

光源类型对比

LightShapeShadowsCostMax Visible
DirectionalLight3D
Parallel raysPSSMCheapest8 (Forward+)
OmniLight3D
SphereCube/Dual ParaboloidMedium512 clustered*
SpotLight3D
ConeSingle textureCheap512 clustered*
AreaLight3D
(4.7+)		RectanglePCSS softMost expensive—
*Forward+ shares 512 clustered element slots among omni lights, spot lights, decals, and reflection probes.
光源类型形状阴影性能开销最大可见数量
DirectionalLight3D
平行光线PSSM最低8（Forward+模式下）
OmniLight3D
球形立方体/双抛物面中等512个集群式*
SpotLight3D
锥形单纹理低512个集群式*
AreaLight3D
(4.7+)		矩形PCSS软阴影最高—
*Forward+模式下，点光源、聚光灯、贴花和反射探针共享512个集群元素槽位。

Light Properties

光源属性

Key knobs: 
light_color
, 
light_energy
(HDR — values >1 are valid), 
shadow_enabled
(big perf hit), 
directional_shadow_mode
, 
directional_shadow_max_distance
(lower = sharper shadows).
See references/materials-and-lighting-recipes.md for the properties table and the GDScript + C# sun setup snippet.
核心参数：
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（Godot 4.7+）

AreaLight3D
emits light from a rectangle along the node's -Z — neon tubes, screens, softbox panels — with PCSS soft shadows driven by 
light_size
. Key properties: 
area_size = Vector2(1, 1)
(meters), 
area_range = 5.0
, 
area_attenuation = 1.0
(
2.0
= physically accurate inverse square), 
area_normalize_energy = true
(resizing keeps total output stable), optional 
area_texture
for textured emission (Forward+/Mobile only). Mobile support is limited and Compatibility cannot cast area-light shadows; in Forward+, a single visible area light adds clustered-lighting cost to all rendered objects — reserve for cinematics or high-end targets.
See references/materials-and-lighting-recipes.md for the full property table and the GDScript + C# setup recipe.
AreaLight3D
从矩形平面沿节点的**-Z方向发射光线——适用于霓虹灯管、屏幕、柔光箱面板等场景，支持由 
light_size
控制的PCSS软阴影。核心属性：
area_size = Vector2(1, 1)
（单位：米）、
area_range = 5.0
、
area_attenuation = 1.0
（
2.0
为符合物理规律的平方反比衰减）、
area_normalize_energy = true
（调整大小时保持总输出能量稳定），可选的 
area_texture
用于带纹理的发光效果（仅Forward+/移动端支持）。移动端对该特性的支持有限，兼容模式（Compatibility）无法投射面光源阴影；在Forward+模式下，单个可见的面光源会为所有**渲染对象增加集群光照开销——请仅用于过场动画或高端设备项目。
完整属性表以及GDScript + C#的设置示例详见 references/materials-and-lighting-recipes.md

Dynamic Point Light

动态点光源

Spawn an 
OmniLight3D
at runtime, drive its energy with a tween, queue-free on completion. Common for explosions, muzzle flashes, magic effects.
See references/materials-and-lighting-recipes.md for the full GDScript and C# recipe.
在运行时生成 
OmniLight3D
，通过Tween驱动其强度变化，效果结束后调用 
queue_free()
销毁。常用于爆炸、枪口火光、魔法特效等场景。
完整的GDScript和C#示例详见 references/materials-and-lighting-recipes.md

Shadow Configuration & Bake Modes

阴影配置与烘焙模式

Prefer 
shadow_normal_bias
over 
shadow_bias
against acne; keep 
directional_shadow_max_distance
at the minimum needed (50–100 m typical). Bake modes: Disabled (fully real-time, default), Static (fully baked, no runtime cost), Dynamic (indirect baked, direct real-time).
See references/materials-and-lighting-recipes.md for the shadow-tuning table and the bake-modes table.
优先使用 
shadow_normal_bias
而非 
shadow_bias
来解决阴影失真（acne）问题；将 
directional_shadow_max_distance
保持在所需的最小值（通常为50-100米）。烘焙模式：Disabled（完全实时，默认）、Static（完全烘焙，无运行时开销）、Dynamic（间接光烘焙，直接光实时）。
阴影调优表和烘焙模式表详见 references/materials-and-lighting-recipes.md

4. Environment & Post-Processing

4. 环境与后处理

Configure global rendering — sky background, tonemapping, glow, SSR, SSAO/SSIL/SDFGI, depth-of-field — through a 
WorldEnvironment
node holding an 
Environment
resource. Pick a tonemap (
Linear
, 
Reinhard
, 
Filmic
, 
ACES
, or 
AgX
) on the Environment resource. Forward+ enables SSAO, SSIL, SSR, and SDFGI; mobile/compatibility renderers omit these.
See references/environment-and-post.md for the full setup recipes (sky options, tonemap modes, all post-processing effects, the 4.6+ glow-before-tonemapping pipeline change, AgX 
tonemap_white
/ 
tonemap_contrast
controls, and the 4.6+ SSR quality upgrade).
Godot 4.7+: 
display/window/hdr/request_hdr_output
(default 
false
, promoted to a basic project setting) requests HDR display output for the main window and editor where supported, auto-switching between HDR and SDR as screens or system settings change; it forces 
Viewport.use_hdr_2d
on for the main viewport (other 
SubViewport
s must enable it themselves). Read only at startup — toggle 
Window.hdr_output_requested
at runtime.
⚠️ Changed in Godot 4.7: The 
rendering/reflections/sky_reflections/roughness_layers
default changed from 
7
to 
8
, altering sky-reflection roughness mip distribution for projects that left it at the default. Set it back to 
7
to keep the 4.6 output. See the 4.7 migration guide.
通过挂载了 
Environment
资源的 
WorldEnvironment
节点配置全局渲染效果——天空背景、色调映射、泛光（glow）、SSR、SSAO/SSIL/SDFGI、景深等。在Environment资源中选择色调映射模式（
Linear
、
Reinhard
、
Filmic
、
ACES
或 
AgX
）。Forward+模式支持SSAO、SSIL、SSR和SDFGI；移动端/兼容模式渲染器不支持这些特性。
完整设置示例（天空选项、色调映射模式、所有后处理效果、4.6+版本泛光先于色调映射的管线变更、AgX的 
tonemap_white
/ 
tonemap_contrast
控制、以及4.6+版本的SSR质量升级）详见 references/environment-and-post.md
Godot 4.7+： 
display/window/hdr/request_hdr_output
（默认值为 
false
，已升级为基础项目设置）用于在支持的设备上为主窗口和编辑器请求HDR显示输出，会随屏幕或系统设置变化自动在HDR和SDR之间切换；它会强制主视口启用 
Viewport.use_hdr_2d
（其他 
SubViewport
需自行启用）。该设置仅在启动时读取——运行时可通过切换 
Window.hdr_output_requested
来调整。
⚠️ Godot 4.7 变更说明： 
rendering/reflections/sky_reflections/roughness_layers
的默认值从 
7
改为 
8
，对于保留默认设置的项目，天空反射的粗糙度mip分布会发生变化。如需保持4.6版本的效果，可将其改回 
7
。详见 4.7迁移指南

5. Global Illumination

5. 全局光照

Five GI options trade quality for cost: none (ambient only) → ReflectionProbe (localized) → LightmapGI (best quality, baked) → VoxelGI (small/medium dynamic) → SDFGI (large open-world). VoxelGI/SDFGI/LightmapGI require Forward+. The 4.5+ subsections below (Specular Occlusion, Bent Normal Maps) stay inline because they apply across GI methods.
See references/global-illumination.md for the methods comparison table, ReflectionProbe scene + code recipe, LightmapGI bake workflow, and SDFGI configuration.
五种全局光照（GI）方案在质量和性能之间各有取舍：无（仅环境光）→ ReflectionProbe（局部反射）→ LightmapGI（质量最佳，烘焙式）→ VoxelGI（中小规模动态场景）→ SDFGI（大型开放世界）。VoxelGI/SDFGI/LightmapGI 需要Forward+模式支持。下方4.5+版本的小节（高光遮挡、弯曲法线贴图）放在这里是因为它们适用于所有GI方案。
方案对比表、ReflectionProbe的场景+代码示例、LightmapGI烘焙流程以及SDFGI配置详见 references/global-illumination.md

Specular Occlusion from Ambient Light (Godot 4.5+)

环境光高光遮挡（Godot 4.5+）

Godot 4.5+ automatically computes specular occlusion from the ambient light probe when LightmapGI, VoxelGI, or SDFGI is active. Prevents unrealistically bright speculars in areas that receive little indirect light (under eaves, inside crevices, in corners). No API change — re-bake after upgrading to see the improvement on metallic / low-roughness surfaces. ReflectionProbe alone does not provide specular occlusion.
当启用 LightmapGI、VoxelGI 或 SDFGI 时，Godot 4.5+ 会自动从环境光探针计算高光遮挡效果。可避免在间接光不足的区域（屋檐下、缝隙内、角落处）出现不真实的亮高光。无需修改API——升级后重新烘焙即可在金属/低粗糙度表面看到效果提升。仅使用ReflectionProbe无法提供高光遮挡效果。

Bent Normal Maps (Godot 4.5+)

弯曲法线贴图（Godot 4.5+）

Bent normal maps encode the mean unoccluded direction from each texel — the average direction toward open sky across the hemisphere. When assigned to the Bent Normal slot on 
StandardMaterial3D
, Godot uses this information to improve indirect lighting directionality and specular occlusion accuracy. The result is more realistic ambient lighting on complex surfaces like cloth, carved stone, or organic shapes.
Inspector setup: In 
StandardMaterial3D
, enable Bent Normal → assign your tangent-space bent normal texture (baked from Marmoset, Substance, or xNormal).
Most visible on: materials that combine low roughness or high metallic values with baked GI (LightmapGI / VoxelGI / SDFGI). On fully rough dielectric surfaces the benefit is subtler. Use on hero assets; skip on background geometry.
See references/materials-and-lighting-recipes.md for the runtime-assignment GDScript + C# code path (the Inspector setup above is the typical case).
弯曲法线贴图（Bent Normal Maps）编码了每个纹素的平均未遮挡方向——即半球范围内朝向开阔天空的平均方向。将其赋值给 
StandardMaterial3D
的 Bent Normal 槽位后，Godot会利用该信息提升间接光照的方向性和高光遮挡的准确性。对于布料、雕刻石材、有机形状等复杂表面，能获得更真实的环境光照效果。
检查器设置步骤： 在 
StandardMaterial3D
中启用 Bent Normal → 分配你的切线空间弯曲法线纹理（可通过Marmoset、Substance或xNormal烘焙得到）。
效果最明显的场景： 低粗糙度或高金属度、且使用烘焙GI（LightmapGI / VoxelGI / SDFGI）的材质。对于完全粗糙的电介质表面，提升效果较不明显。建议用于核心资产；背景几何体可省略。
运行时赋值的GDScript + C#代码实现详见 references/materials-and-lighting-recipes.md（上述检查器设置是常规用法）。

6. Fog

6. 雾效

Three layers: depth/height fog set on 
WorldEnvironment.environment
(cheap, all renderers), volumetric fog (Forward+ only — godrays through depth), and 
FogVolume
nodes for localized fog effects (interior rooms, pits, atmospheric volumes).
See references/fog-recipes.md for the full GDScript and C# recipes — depth/height fog setup, volumetric fog parameters and performance notes, and FogVolume placement.
⚠️ Changed in Godot 4.7: Volumetric fog is now blended using transmittance instead of opacity, so existing volumetric fog can look different after upgrading. Enable the project setting 
rendering/environment/fog/use_legacy_blending
(default 
false
) to restore the previous behavior. See GH-119414.
雾效分为三层：在 
WorldEnvironment.environment
上设置的深度/高度雾（开销低，所有渲染器都支持）、体积雾（仅Forward+支持——可产生穿透深度的体积光），以及用于局部雾效的 
FogVolume
节点（适用于室内房间、坑洞、大气体积效果）。
完整的GDScript和C#示例——深度/高度雾设置、体积雾参数与性能注意事项、以及FogVolume放置方法——详见 references/fog-recipes.md
⚠️ Godot 4.7 变更说明： 体积雾现在使用透射率（transmittance）而非不透明度进行混合，因此升级后现有体积雾的效果可能会发生变化。启用项目设置 
rendering/environment/fog/use_legacy_blending
（默认值为 
false
）可恢复旧版本的行为。详见 GH-119414

7. Decals

7. 贴花

Decal
nodes project a texture onto whatever surfaces fall within their bounding box — bullet holes, blood splatter, ground details, signage. All renderers support decals; performance scales with overdraw and decal count.
See references/decals.md for the scene setup, runtime spawning recipe (GDScript + C#), and the per-renderer decal limits.
Decal
节点会将纹理投射到其包围盒内的所有表面上——适用于弹孔、血迹、地面细节、标识等场景。所有渲染器都支持贴花；性能开销与过度绘制（overdraw）和贴花数量成正比。
场景设置、运行时生成示例（GDScript + C#）以及各渲染器的贴花限制详见 references/decals.md

8. Optimization — LOD, Culling, MultiMesh

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

Four tools: automatic mesh LOD (set on import or per 
MeshInstance3D
), manual 
VisibilityRange
for staged swaps, occlusion culling via 
OccluderInstance3D
, and 
MultiMeshInstance3D
for thousands of identical meshes in one draw call.
See references/lod-and-culling.md for setup recipes for each tool plus the MultiMesh runtime population example.
四种优化工具：自动网格LOD（可在导入时设置或针对单个 
MeshInstance3D
设置）、用于分级切换的手动 
VisibilityRange
、通过 
OccluderInstance3D
实现的遮挡剔除，以及可在一次绘制调用中渲染数千个相同网格的 
MultiMeshInstance3D
。
每种工具的设置示例以及MultiMesh运行时填充示例详见 references/lod-and-culling.md

9. Renderer Comparison

9. 渲染器对比

Pick the renderer before you build the look: Forward+ (desktop default) is the only one with SDFGI and volumetric fog, Mobile trades those for performance on tile-based GPUs, and Compatibility (GLES3-class) drops most advanced lighting entirely. Advice that assumes SDFGI silently fails on the other two.
Full feature-by-renderer table and selection guidance: references/renderer-comparison.md
在搭建视觉效果前请先选择渲染器：Forward+（桌面端默认）是唯一支持SDFGI和体积雾的渲染器；Mobile（移动端）为了在瓦片式GPU上的性能表现舍弃了这些特性；而 Compatibility（兼容模式，GLES3级别）则完全移除了大多数高级光照特性。基于SDFGI的建议在另外两种渲染器上会静默失效。
按渲染器划分的完整功能表与选择指南见：references/renderer-comparison.md

10. Common Pitfalls

10. 常见问题

Quick symptom → cause → fix table covering black scenes, dark objects without ambient light, shadow acne and peter-panning, popping shadows, flat materials, invisible decals, transparency sorting artifacts, SDFGI light leaking, missing volumetric fog, and invisible MultiMesh instances.
See references/common-pitfalls.md for the full table.
包含「症状→原因→解决方法」的快速对照表，涵盖场景全黑、无环境光导致物体过暗、阴影失真（acne）和阴影飘移（peter-panning）、阴影闪烁、材质扁平、贴花不可见、透明度排序瑕疵、SDFGI漏光、体积雾缺失、MultiMesh实例不可见等问题。
完整表格详见 references/common-pitfalls.md

11. Implementation Checklist

11. 实现检查清单

  • Scene has Camera3D, at least one light source, and WorldEnvironment
  • Environment has a sky material (procedural or HDR panorama) for ambient and reflected light
  • Tonemap mode is set (Filmic or ACES for realistic look, AgX for physically accurate)
  • DirectionalLight3D has shadows enabled with 
    shadow_normal_bias
    tuned to prevent acne
  • directional_shadow_max_distance
    is set to the minimum needed (50–100m typical)
  • Static geometry uses StandardMaterial3D with appropriate PBR textures (albedo, normal, roughness, metallic)
  • Transparent materials use Alpha Scissor or Alpha Hash instead of Alpha where possible (performance + shadows)
  • ReflectionProbes are placed in rooms/areas with reflective surfaces
  • GI method chosen based on project needs (LightmapGI for static, SDFGI for large dynamic, VoxelGI for small dynamic)
  • Mesh LOD is enabled on import (default for glTF/Blend — verify OBJ files)
  • Occlusion culling is enabled and baked for scenes with heavy occlusion (indoor, urban)
  • MultiMeshInstance3D is used for instanced geometry (grass, trees, props) instead of individual nodes
  • Renderer matches target platform (Forward+ desktop, Mobile mobile, Compatibility web)
  • Projects using LightmapGI/VoxelGI/SDFGI take advantage of automatic specular occlusion by upgrading to Godot 4.5+ (no API change required)
  • Hero assets with complex surface detail use bent normal maps in the StandardMaterial3D Bent Normal slot for improved indirect lighting (Godot 4.5+)
  • After upgrading to Godot 4.6, glow settings are re-tuned if appearance has changed (glow now runs before tonemapping)
  • AgX 
    tonemap_white
    and 
    tonemap_contrast
    are adjusted when using AgX tonemapper for precise look control (Godot 4.6+)
  • After upgrading to Godot 4.7, volumetric fog and sky reflections are re-checked (fog blending and the 
    roughness_layers
    default changed)
  • 场景包含Camera3D、至少一个光源和WorldEnvironment
  • 环境配置了天空材质（程序化或HDR全景图）以提供环境光和反射光
  • 已设置色调映射模式（追求真实感用Filmic或ACES，追求物理精准用AgX）
  • DirectionalLight3D已启用阴影，并调整了 
    shadow_normal_bias
    以防止阴影失真
  • directional_shadow_max_distance
    已设置为所需的最小值（通常为50-100米）
  • 静态几何体使用StandardMaterial3D，并配有合适的PBR纹理（albedo、normal、roughness、metallic）
  • 透明材质尽可能使用Alpha Scissor或Alpha Hash而非普通Alpha（提升性能并支持阴影）
  • 在有反射表面的房间/区域放置了ReflectionProbe
  • 已根据项目需求选择了GI方案（静态场景用LightmapGI，大型动态场景用SDFGI，小型动态场景用VoxelGI）
  • 导入时已启用网格LOD（glTF/Blend文件默认启用——需确认OBJ文件的设置）
  • 对于遮挡严重的场景（室内、城市场景），已启用并烘焙了遮挡剔除
  • 实例化几何体（草地、树木、道具）使用MultiMeshInstance3D而非单个节点
  • 渲染器与目标平台匹配（桌面端用Forward+，移动端用Mobile，网页端用Compatibility）
  • 使用LightmapGI/VoxelGI/SDFGI的项目已升级到Godot 4.5+以利用自动高光遮挡特性（无需修改API）
  • 具有复杂表面细节的核心资产在StandardMaterial3D的Bent Normal槽位使用了弯曲法线贴图，以提升间接光照效果（Godot 4.5+）
  • 升级到Godot 4.6后，如果效果发生变化已重新调整泛光设置（泛光现在在色调映射之前运行）
  • 使用AgX色调映射器时，已调整AgX的 
    tonemap_white
    和 
    tonemap_contrast
    以实现精准的视觉控制（Godot 4.6+）
  • 升级到Godot 4.7后，已重新检查体积雾和天空反射效果（雾混合方式和 
    roughness_layers
    默认值已变更）