godot-3d-essentials

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Godot 3D Essentials (4.x)

Godot 3D基础教程（4.x版本）

Assemble a working 3D scene: transforms, camera, lights, environment/post, materials, and

GridMap

blockouts. Targets Godot 4.3+.

组装可运行的3D场景：变换、相机、灯光、环境/后期处理、材质以及

GridMap

关卡原型。适配**Godot 4.3+**版本。

When to use

适用场景

Use when starting or fixing a 3D scene: positioning a
```
Camera3D
```
, adding lights, setting up a
```
WorldEnvironment
```
(sky, ambient, tonemap, glow/SSAO), assigning materials, or building levels with
```
GridMap
```
.

When not to use: writing spatial shaders →

godot-shaders

; 3D physics bodies and raycasts →

godot-physics

; character animation blending →

godot-animation

; full FPS template → the

fps-shooter

genre skill.

适用于创建或修复3D场景时：定位
```
Camera3D
```
、添加灯光、设置
```
WorldEnvironment
```
（天空、环境光、色调映射、光晕/屏幕空间环境光遮蔽）、分配材质，或使用
```
GridMap
```
构建关卡。

不适用场景：编写空间着色器 → 使用

godot-shaders

；3D物理体与射线检测 → 使用

godot-physics

；角色动画混合 → 使用

godot-animation

；完整FPS模板 → 使用

fps-shooter

类型技能。

Core workflow

核心工作流程

Everything 3D is a
Node3D
with a
```
Transform3D
```
(position, rotation basis, scale). Move with
```
global_position
```
, rotate with
```
rotate_y(angle)
```
or
```
look_at(target)
```
.
Add a
Camera3D
. Mark it
```
current
```
(or call
```
make_current()
```
); set
```
fov
```
,
```
near
```
,
```
far
```
. Parent it to a rig/pivot for orbit or follow cameras.
Light the scene. A
```
DirectionalLight3D
```
is the sun;
```
OmniLight3D
```
/
```
SpotLight3D
```
are local. Enable shadows per light. Without lights and ambient, surfaces render black.
Add a
WorldEnvironment
with an
```
Environment
```
resource: background (sky/color), ambient light, tonemap, and post (glow, SSAO, fog, adjustments).

Give meshes materials (

StandardMaterial3D

or a

ShaderMaterial

) on

MeshInstance3D

Block out levels with
GridMap
, which places
```
MeshLibrary
```
items on a 3D grid (the 3D analog of a tilemap).

所有3D对象均为
Node3D
，带有
```
Transform3D
```
组件（位置、旋转基、缩放）。通过
```
global_position
```
移动，使用
```
rotate_y(angle)
```
或
```
look_at(target)
```
旋转。
添加
Camera3D
。标记为
```
current
```
（或调用
```
make_current()
```
方法）；设置
```
fov
```
（视野）、
```
near
```
（近裁剪面）、
```
far
```
（远裁剪面）。将其挂载到控制节点/枢轴上，实现轨道或跟随相机效果。
为场景添加光照。
```
DirectionalLight3D
```
模拟太阳光；
```
OmniLight3D
```
/
```
SpotLight3D
```
用于局部光照。为每个灯光启用阴影。如果没有灯光和环境光，表面会渲染为黑色。
**添加
```
WorldEnvironment
```
**并关联
```
Environment
```
资源：背景（天空/纯色）、环境光、色调映射，以及后期处理（光晕、SSAO、雾效、参数调整）。

为网格赋予材质：在

MeshInstance3D

上使用

StandardMaterial3D

或

ShaderMaterial

。

使用
GridMap
制作关卡原型，它会将
```
MeshLibrary
```
中的物品放置在3D网格上（相当于3D版本的瓦片地图）。

Patterns

实践模式

1. A follow camera (third-person, smoothed)

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

gdscript

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

gdscript

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. Sun + environment in code

2. 代码实现太阳光与环境

gdscript

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)

gdscript

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. Assign a StandardMaterial3D from code

3. 通过代码分配StandardMaterial3D

gdscript

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

gdscript

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. Place tiles into a GridMap

4. 向GridMap中放置瓦片

gdscript

@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)

gdscript

@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)

Pitfalls

常见陷阱

Scene renders black → no lights and no ambient. Add a
```
DirectionalLight3D
```
and/or a
```
WorldEnvironment
```
with ambient/sky. New scenes have neither by default.
No camera / wrong camera. If nothing shows, no
```
Camera3D
```
is
```
current
```
. Set
```
current = true
```
or
```
make_current()
```
; only one camera renders per viewport.
Confusing local vs global transforms.
```
position
```
/
```
rotation
```
are relative to the parent;
```
global_position
```
/
```
global_transform
```
are world space. Mixing them under a rotated parent gives surprising results.
```
look_at
```
uses global coordinates.
Scaling physics/lights. Non-uniform
```
scale
```
on a
```
Node3D
```
distorts child collisions and lights; prefer scaling the mesh asset or using uniform scale.
Forgetting
from
/
up
in
look_at
.
```
look_at(target, up)
```
— a target equal to the node's position, or an
```
up
```
parallel to the look direction, produces NaNs/flips.
GridMap with no
MeshLibrary
places nothing. Create a
```
MeshLibrary
```
(from scenes) and assign it;
```
set_cell_item(cell, -1)
```
clears a cell.
HDR/glow too strong → check
```
tonemap_mode
```
and glow thresholds; raw emissive values bloom hard under filmic tonemapping.

场景渲染为黑色 → 没有灯光和环境光。添加
```
DirectionalLight3D
```
和/或带有环境光/天空的
```
WorldEnvironment
```
。新场景默认没有这些元素。
无相机/相机错误。如果没有内容显示，说明没有
```
Camera3D
```
被设置为
```
current
```
。设置
```
current = true
```
或调用
```
make_current()
```
；每个视口仅能有一个相机进行渲染。
混淆局部与全局变换。
```
position
```
/
```
rotation
```
是相对于父节点的；
```
global_position
```
/
```
global_transform
```
是世界空间坐标。在旋转的父节点下混用二者会导致意外结果。
```
look_at
```
使用全局坐标。
缩放物理体/灯光。对
```
Node3D
```
进行非均匀缩放会扭曲子节点的碰撞体和灯光；建议缩放网格资源或使用均匀缩放。
look_at
中遗漏
from
/
up
参数。
```
look_at(target, up)
```
— 如果目标与节点位置相同，或
```
up
```
方向与注视方向平行，会产生NaN值或翻转问题。
GridMap未关联
MeshLibrary
→ 无法放置任何物品。创建
```
MeshLibrary
```
（从场景生成）并分配给它；使用
```
set_cell_item(cell, -1)
```
清除单元格。
HDR/光晕效果过强 → 检查
```
tonemap_mode
```
和光晕阈值；在电影色调映射下，原始自发光值会导致严重的 bloom 效果。

References

参考资料

For Transform3D math, camera projection modes, light/shadow params, the full Environment/post-processing options,
```
MeshLibrary
```
creation, and
```
ReflectionProbe
```
/
```
LightmapGI
```
lighting, read
```
references/scene-and-environment.md
```
.

关于Transform3D数学、相机投影模式、灯光/阴影参数、完整的环境/后期处理选项、
```
MeshLibrary
```
创建，以及
```
ReflectionProbe
```
/
```
LightmapGI
```
光照的内容，请查阅
```
references/scene-and-environment.md
```
。

godot-3d-essentials

Original

Translation

Godot 3D Essentials (4.x)

Godot 3D基础教程（4.x版本）

When to use

适用场景

Core workflow

核心工作流程

Patterns

实践模式

1. A follow camera (third-person, smoothed)

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

2. Sun + environment in code

2. 代码实现太阳光与环境

3. Assign a StandardMaterial3D from code

3. 通过代码分配StandardMaterial3D

4. Place tiles into a GridMap

4. 向GridMap中放置瓦片

Pitfalls

常见陷阱

References

参考资料

Related skills

相关技能