最后更新日期：2026-04-16

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

Engine.set_time_scale

定义

Engine.set_time_scale（对应属性 Engine.TimeScale）是游戏世界的"时间快慢旋钮"——它控制游戏内一切受 _Process 和 _PhysicsProcess 驱动的时间流速。

打个比方：你在看视频时按了 2 倍速播放，视频里的一切都会变成两倍速——人物走得更快、对话更快、动作更快。TimeScale 就是这个倍速按钮：设为 2.0 整个游戏世界加速两倍，设为 0.5 一切变成慢动作，设为 0.0 时间完全冻结。

在游戏开发中，这个功能常用于：慢动作回放、子弹时间效果、暂停菜单（不完全暂停，而是把时间缩放设为 0）、游戏开始前的倒计时慢放等。

函数签名

C#

// Engine.TimeScale 属性 — 设置/获取时间缩放倍率
public static double TimeScale { get; set; }

// 默认值为 1.0

GDScript

# Engine.time_scale 属性 — 设置/获取时间缩放倍率
var time_scale: float  # 默认值为 1.0

参数说明

TimeScale 是一个属性而非方法，直接赋值即可：

值	类型	说明
1.0	float/double	正常速度（默认值）
2.0	float/double	两倍速
0.5	float/double	半速（慢动作）
0.0	float/double	完全冻结

返回值

读取 Engine.TimeScale 返回当前的时间缩放倍率（double / float）。

代码示例

基础用法：设置慢动作和加速

C#

using Godot;

public partial class MyScene : Node
{
    public override void _Ready()
    {
        // 正常速度
        Engine.TimeScale = 1.0;
        GD.Print($"时间缩放: {Engine.TimeScale}");
        // 运行结果: 时间缩放: 1

        // 半速（慢动作）
        Engine.TimeScale = 0.5;
        // 运行结果: 游戏中的一切变成一半速度

        // 恢复正常
        Engine.TimeScale = 1.0;
    }
}

GDScript

extends Node

func _ready():
    # 正常速度
    Engine.time_scale = 1.0
    print("时间缩放: ", Engine.time_scale)
    # 运行结果: 时间缩放: 1.0

    # 半速（慢动作）
    Engine.time_scale = 0.5
    # 运行结果: 游戏中的一切变成一半速度

    # 恢复正常
    Engine.time_scale = 1.0

实际场景：子弹时间效果

C#

using Godot;

public partial class BulletTime : Node
{
    [Export] public float ExSlowMotionScale = 0.2f;
    [Export] public double ExDuration = 3.0;

    private bool _isActive = false;

    public override void _Input(InputEvent ev)
    {
        if (ev.IsActionPressed("bullet_time") && !_isActive)
        {
            Activate();
        }
    }

    public void Activate()
    {
        _isActive = true;
        Engine.TimeScale = ExSlowMotionScale;

        GD.Print("子弹时间激活！");
        // 运行结果: 子弹时间激活！

        // 注意：定时器也受 TimeScale 影响，所以用真实时间恢复
        // 这里使用 SceneTreeTimer 的 process_in_physics = false 不受影响
        // 更好的方式是在 _Process 中用 delta 累加（delta 会自动受 TimeScale 影响）
        GetTree().CreateTimer(ExDuration, processAlways: true, ignoreTimeScale: true)
            .Timeout += () =>
            {
                Engine.TimeScale = 1.0;
                _isActive = false;
                GD.Print("子弹时间结束");
                // 运行结果: 子弹时间结束
            };
    }
}

GDScript

extends Node

@export var slow_motion_scale: float = 0.2
@export var duration: float = 3.0

var _is_active: bool = false

func _input(ev):
    if ev.is_action_pressed("bullet_time") and not _is_active:
        activate()

func activate():
    _is_active = true
    Engine.time_scale = slow_motion_scale

    print("子弹时间激活！")
    # 运行结果: 子弹时间激活！

    # 注意：定时器也受 time_scale 影响
    # 使用 ignore_time_scale = true 让定时器不受影响
    get_tree().create_timer(duration, true, true).timeout.connect(func():
        Engine.time_scale = 1.0
        _is_active = false
        print("子弹时间结束")
        # 运行结果: 子弹时间结束
    )

进阶用法：游戏暂停/恢复

C#

using Godot;

public partial class PauseManager : Node
{
    private bool _isPaused = false;
    private double _savedTimeScale = 1.0;

    public override void _Input(InputEvent ev)
    {
        if (ev.IsActionPressed("pause"))
        {
            if (_isPaused)
            {
                Resume();
            }
            else
            {
                Pause();
            }
        }
    }

    public void Pause()
    {
        _isPaused = true;
        _savedTimeScale = Engine.TimeScale;
        Engine.TimeScale = 0.0;

        GD.Print("游戏已暂停");
        // 运行结果: 游戏已暂停
    }

    public void Resume()
    {
        _isPaused = false;
        Engine.TimeScale = _savedTimeScale;

        GD.Print("游戏已恢复");
        // 运行结果: 游戏已恢复
    }
}

GDScript

extends Node

var _is_paused: bool = false
var _saved_time_scale: float = 1.0

func _input(ev):
    if ev.is_action_pressed("pause"):
        if _is_paused:
            resume()
        else:
            pause()

func pause():
    _is_paused = true
    _saved_time_scale = Engine.time_scale
    Engine.time_scale = 0.0

    print("游戏已暂停")
    # 运行结果: 游戏已暂停

func resume():
    _is_paused = false
    Engine.time_scale = _saved_time_scale

    print("游戏已恢复")
    # 运行结果: 游戏已恢复

注意事项

• 影响 _Process 和 _PhysicsProcess 的 delta：当 TimeScale 设为 0.5 时，_Process 接收到的 delta 也会变成正常值的一半。这意味着所有用 delta 做计算的移动、动画都会自动变慢。
• 定时器也受影响：GetTree().CreateTimer() 创建的定时器默认也会被 TimeScale 影响。如果你需要创建不受时间缩放影响的定时器，在 GDScript 中使用 ignore_time_scale = true 参数。
• 不要设为负数：负数的时间缩放会导致不可预测的行为，不建议使用。
• 记得恢复：设置慢动作后一定要确保有恢复机制，否则游戏会一直处于慢动作/暂停状态。建议保存原始值以便恢复。
• 影响物理引擎：TimeScale 会同时影响物理模拟的速度，可能导致物理行为不太准确（特别是极端值如 0.1 以下时）。