godot-3d-essentials

Godot 3D Essentials（4.x）

组装一个可运行的 3D 场景：变换、摄像机、灯光、环境／后期处理、材质和 GridMap 灰盒关卡。目标版本为 Godot 4.7。

适用场景

• 在开始搭建或修复 3D 场景时使用：定位 Camera3D、添加灯光、设置 WorldEnvironment（天空、环境光、色调映射、辉光／SSAO）、分配材质，或 使用 GridMap 构建关卡。

**不适用场景：**编写空间着色器 → godot-shaders；3D 物理体和 射线检测 → godot-physics；角色动画混合 → godot-animation；完整 FPS 模板 → fps-shooter 类型技能。

核心工作流

1. 所有 3D 对象都是 Node3D，并带有 Transform3D（位置、旋转基向量、缩放）。 使用 global_position 移动，使用 rotate_y(angle) 或 look_at(target) 旋转。
2. 添加 Camera3D。 将其标记为 current（或调用 make_current()）；设置 fov、near、 far。将其设为支架／枢轴的子节点，以实现环绕或跟随摄像机。
3. 布置场景灯光。 DirectionalLight3D 是太阳光；OmniLight3D／SpotLight3D 是 局部光源。为每个灯光启用阴影。没有灯光和环境光时，表面会渲染为黑色。
4. 添加带有 Environment 资源的 WorldEnvironment：背景（天空／颜色）、 环境光、色调映射和后期处理（辉光、SSAO、雾、调整）。
5. 为网格添加材质（StandardMaterial3D 或 ShaderMaterial），赋给 MeshInstance3D。
6. 使用 GridMap 构建关卡灰盒，在 3D 网格上放置 MeshLibrary 项目 （相当于 3D 版的图块地图）。

模式

1. 跟随摄像机（第三人称、平滑）

extends Camera3D

@export var target: Node3D
@export var offset := Vector3(0, 4, 8)
@export var smooth := 6.0

func _physics_process(delta: float) -> void:
    if target == null:
        return
    var desired := target.global_position + offset
    global_position = global_position.lerp(desired, smooth * delta)  # smooth follow
    look_at(target.global_position, Vector3.UP)                      # face the target

2. 在代码中设置太阳光和环境

func _ready() -> void:
    var sun := DirectionalLight3D.new()
    sun.rotation_degrees = Vector3(-45, -30, 0)
    sun.shadow_enabled = true
    add_child(sun)

    var we := WorldEnvironment.new()
    var env := Environment.new()
    env.background_mode = Environment.BG_SKY
    env.sky = Sky.new()
    env.sky.sky_material = ProceduralSkyMaterial.new()
    env.ambient_light_source = Environment.AMBIENT_SOURCE_SKY
    env.tonemap_mode = Environment.TONE_MAPPER_FILMIC
    env.glow_enabled = true
    we.environment = env
    add_child(we)

3. 在代码中分配 StandardMaterial3D

func tint_mesh(mesh: MeshInstance3D, color: Color) -> void:
    var mat := StandardMaterial3D.new()
    mat.albedo_color = color
    mat.metallic = 0.0
    mat.roughness = 0.6
    mat.emission_enabled = true
    mat.emission = color * 0.3
    mesh.material_override = mat       # overrides the mesh's surface materials

4. 在 GridMap 中放置图块

@onready var grid: GridMap = $GridMap   # cell_size + mesh_library set in the editor

func build_floor(width: int, depth: int, item_id: int) -> void:
    for x in width:
        for z in depth:
            # set_cell_item(Vector3i cell, int item, orientation = 0)
            grid.set_cell_item(Vector3i(x, 0, z), item_id)

常见问题

• 场景渲染为黑色 → 没有灯光和环境光。添加 DirectionalLight3D，和／或添加带有环境光／天空的 WorldEnvironment。新场景默认两者都没有。
• 没有摄像机／摄像机不正确。 如果什么都看不到，说明没有 Camera3D 处于 current 状态。设置 current = true 或调用 make_current()；每个视口一次只能由一台摄像机渲染。
• 混淆局部变换和全局变换。 position／rotation 相对于父节点；global_position／global_transform 是世界空间坐标。在经过旋转的父节点下混用会产生意外结果。look_at 使用全局坐标。
• 缩放物理体／灯光。 对 Node3D 使用非均匀 scale 会扭曲子节点碰撞体和灯光；优先缩放网格资源，或使用均匀缩放。
• 在 look_at 中忘记 from／up。 look_at(target, up)：如果目标与节点位置相同，或 up 与观察方向平行，会产生 NaN／翻转。
• 没有 MeshLibrary 的 GridMap 不会放置任何内容。创建一个 MeshLibrary（从场景创建）并分配给它；set_cell_item(cell, -1) 会清空单元格。
• HDR／辉光过强 → 检查 tonemap_mode 和辉光阈值；在胶片色调映射下，原始自发光值会产生强烈泛光。

参考资料

• 有关 Transform3D 数学、摄像机投影模式、灯光／阴影参数、完整的环境／后期处理选项、 MeshLibrary 创建，以及 ReflectionProbe／LightmapGI 照明，请阅读 references/scene-and-environment.md。

相关技能

• godot-physics — 3D 物理体、区域和射线检测。
• godot-shaders — 用于自定义 3D 表面的空间着色器。
• godot-animation — 用于 3D 角色的 AnimationTree。
• camera-systems — 第三人称环绕／第一人称视角支架、取景和碰撞。
• performance-optimization — 让 3D 场景保持在帧预算内（绘制调用、灯光、LOD）。
• fps-shooter — 将 3D 移动、输入和 AI 组合成游戏。