最后同步日期：2026-04-15 | Godot 官方原文 — WorldEnvironment

WorldEnvironment

节点继承关系

继承链：Node → WorldEnvironment

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

游戏世界的"总控室"——它控制整个场景的环境参数：天空是什么样、环境光有多亮、雾的浓度、色调映射方式等。一个场景通常只需要一个 WorldEnvironment 节点。

打个比方：WorldEnvironment 就像电影片场的"灯光总监"和"美术总监"合体。它不直接出现在画面里，但它决定了整个画面看起来是什么风格——是晴空万里的午后，还是阴雨连绵的黄昏。

使用频率：★★★★ 维度专用常用——每个 3D 场景几乎必备。

节点用途

• 设置天空盒（Sky）：蓝天白云、星空、日落等
• 设置环境光（Ambient Light）：场景的基础照明
• 设置雾效（Fog）：远处的物体逐渐模糊
• 设置色调映射（Tonemap）：画面整体明暗和色彩风格
• 设置辉光（Bloom）：强光周围的光晕效果
• 设置 SSAO、SSIL 等屏幕空间效果

使用场景

典型场景

• 每个 3D 场景：一个场景放一个 WorldEnvironment，配置天空和环境光
• 日夜循环：通过代码动态修改 Environment 资源的属性
• 不同关卡切换风格：不同场景使用不同的 Environment 资源

不适用场景

• 2D 游戏（一般不需要，除非需要特殊的色调映射）
• 局部区域需要不同环境（使用 SubViewport + WorldEnvironment）

常用节点搭配

搭配节点	用途	必需？
DirectionalLight3D	太阳光，配合天空盒使用	推荐
Environment 资源	赋给 environment 属性，定义环境参数	必需

典型节点树：

World (Node3D)
├── WorldEnvironment  ← 世界环境设置
├── DirectionalLight3D  ← 太阳光
└── Player

生效必备素材/资源

资源	类型	说明
Environment 资源	Environment	赋给 environment 属性，包含天空、环境光、雾、后处理等所有环境参数
Sky 材质	ShaderMaterial	赋给 Environment 中的 sky 属性，决定天空的样子
HDRI 贴图	Texture2D	可选，用于创建逼真的天空反射
CameraAttributes 资源	CameraAttributes	赋给 camera_attributes 属性，控制曝光、景深等相机参数

节点属性与信号

环境

属性	类型	默认值	继承自	说明
environment	Environment	—	—	环境配置资源，包含天空、光照、雾、后处理等全部设置
camera_attributes	CameraAttributes	—	—	摄像机属性，控制曝光、泛光、景深等效果

信号

信号	触发时机	继承自	说明
无自有信号	—	—	WorldEnvironment 自身不发出信号

常用方法

方法	返回值	说明
GetEnvironment()	Environment	获取当前环境配置
SetEnvironment(env)	void	设置环境配置
GetCameraAttributes()	CameraAttributes	获取摄像机属性
SetCameraAttributes(attrs)	void	设置摄像机属性

代码示例

C

using Godot;

/// <summary>
/// 日夜循环系统
/// 通过动态修改 WorldEnvironment 的参数实现日夜交替
/// </summary>
public partial class DayNightCycle : Node
{
    [Export] private WorldEnvironment _worldEnv;
    [Export] private DirectionalLight3D _sunLight;
    [Export] public float ExCycleDuration = 120f; // 一个完整日夜循环的秒数

    private float _time;

    public override void _Process(double delta)
    {
        _time += (float)delta / ExCycleDuration;
        if (_time >= 1f) _time -= 1f;

        UpdateEnvironment(_time);
    }

    private void UpdateEnvironment(float t)
    {
        // t: 0 = 午夜, 0.25 = 日出, 0.5 = 正午, 0.75 = 日落
        var env = _worldEnv.Environment;

        // 调整天空颜色
        var skyMat = (ShaderMaterial)env.Sky.SkyMaterial;
        float sunHeight = Mathf.Sin(t * Mathf.Pi * 2f);

        if (sunHeight > 0f)
        {
            // 白天：浅蓝色天空
            skyMat.SetShaderParameter("top_color",
                new Color(0.2f, 0.5f, 1.0f));
            skyMat.SetShaderParameter("bottom_color",
                new Color(0.6f, 0.8f, 1.0f));
            env.BackgroundEnergy = 1.0f;
        }
        else
        {
            // 夜晚：深蓝色天空
            skyMat.SetShaderParameter("top_color",
                new Color(0.02f, 0.02f, 0.08f));
            skyMat.SetShaderParameter("bottom_color",
                new Color(0.05f, 0.05f, 0.15f));
            env.BackgroundEnergy = 0.2f;
        }

        // 调整太阳光
        float angle = t * 360f - 90f;
        _sunLight.RotationDegrees = new Vector3(angle, 45f, 0);
        _sunLight.LightEnergy = Mathf.Max(0f, sunHeight) * 1.5f;
    }
}

GDScript

## 日夜循环系统
## 通过动态修改 WorldEnvironment 的参数实现日夜交替
extends Node

@export var world_env: WorldEnvironment
@export var sun_light: DirectionalLight3D
@export var cycle_duration: float = 120.0  # 一个完整日夜循环的秒数

var _time: float = 0.0

func _process(delta: float):
    _time += delta / cycle_duration
    if _time >= 1.0:
        _time -= 1.0
    _update_environment(_time)

func _update_environment(t: float):
    # t: 0 = 午夜, 0.25 = 日出, 0.5 = 正午, 0.75 = 日落
    var env = world_env.environment
    var sky_mat = env.sky.sky_material as ShaderMaterial
    var sun_height = sin(t * TAU)

    if sun_height > 0:
        # 白天：浅蓝色天空
        sky_mat.set_shader_parameter("top_color", Color(0.2, 0.5, 1.0))
        sky_mat.set_shader_parameter("bottom_color", Color(0.6, 0.8, 1.0))
        env.background_energy = 1.0
    else:
        # 夜晚：深蓝色天空
        sky_mat.set_shader_parameter("top_color", Color(0.02, 0.02, 0.08))
        sky_mat.set_shader_parameter("bottom_color", Color(0.05, 0.05, 0.15))
        env.background_energy = 0.2

    # 调整太阳光
    var angle = t * 360.0 - 90.0
    sun_light.rotation_degrees = Vector3(angle, 45.0, 0)
    sun_light.light_energy = maxf(0.0, sun_height) * 1.5

使用建议

• 一个场景通常只需要一个 WorldEnvironment。多个 WorldEnvironment 会导致冲突
• 如果需要局部不同的环境（如室内外切换），使用 SubViewport 来隔离
• 修改 Environment 属性时建议创建一个新的 Environment 资源副本，避免修改共享资源影响其他场景
• CameraAttributes 的 Exposure 值控制画面亮度，可以配合日光强度动态调整