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

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

AnimationTree.set_active

定义

AnimationTree.set_active 就像动画系统的"总开关"——设为 true 时动画树开始工作，设为 false 时动画树完全停止。

打个比方：AnimationTree 就像一个自动变速箱，它会根据你的输入（速度、方向、是否攻击等）自动切换到合适的动画档位。SetActive(true) 是启动这个变速箱，SetActive(false) 是熄火停车。熄火后不管你怎么踩油门（改变参数），动画都不会响应。

和 AnimationPlayer 不同，AnimationTree 不是简单地"播放一个动画"，而是根据参数（如移动速度、方向）在多个动画之间自动混合和过渡，适合复杂的角色动画系统（如 Blend Tree、State Machine）。

函数签名

C#

// AnimationTree.SetActive 启用或禁用动画树
public void SetActive(bool active)

GDScript

func set_active(active: bool) -> void

参数说明

参数	类型	必需	说明
active	bool	是	true 启用动画树，false 禁用动画树

返回值

无返回值（void）。

代码示例

基础用法：在游戏开始时启用动画树

C#

using Godot;

public partial class Player : CharacterBody2D
{
    private AnimationTree _animTree;

    public override void _Ready()
    {
        _animTree = GetNode<AnimationTree>("AnimationTree");

        // 启用动画树，开始响应参数变化
        _animTree.SetActive(true);

        GD.Print($"动画树已启用: {_animTree.Active}");
        // 运行结果: 动画树已启用: True
    }
}

GDScript

extends CharacterBody2D

@onready var anim_tree = $AnimationTree

func _ready():
    # 启用动画树，开始响应参数变化
    anim_tree.active = true

    print("动画树已启用: ", anim_tree.active)
    # 运行结果: 动画树已启用: True

实际场景：控制角色移动动画混合

C#

using Godot;

public partial class Player : CharacterBody2D
{
    [Export] public float ExMoveSpeed = 200.0f;

    private AnimationTree _animTree;
    private bool _isEnabled = false;

    public override void _Ready()
    {
        _animTree = GetNode<AnimationTree>("AnimationTree");
        _animTree.SetActive(true);
        _isEnabled = true;
    }

    public override void _PhysicsProcess(double delta)
    {
        if (!_isEnabled) return;

        float direction = Input.GetAxis("ui_left", "ui_right");

        // 设置动画树参数：速度（用于混合 idle/walk/run）
        float speedParam = Mathf.Abs(direction) * ExMoveSpeed;
        _animTree.Set("parameters/Speed/blend_position", speedParam);

        // 运行结果: 根据移动速度，动画树自动混合站立/走路/跑步动画
    }

    /// 禁用动画树（比如角色被冰冻）
    public void Freeze()
    {
        _animTree.SetActive(false);
        _isEnabled = false;
        GD.Print("角色被冰冻，动画已停止");
        // 运行结果: 角色被冰冻，动画已停止
    }

    /// 解除冰冻
    public void Unfreeze()
    {
        _animTree.SetActive(true);
        _isEnabled = true;
        GD.Print("冰冻解除，动画恢复");
        // 运行结果: 冰冻解除，动画恢复
    }
}

GDScript

extends CharacterBody2D

@export var move_speed: float = 200.0

@onready var anim_tree = $AnimationTree
var _is_enabled: bool = false

func _ready():
    anim_tree.active = true
    _is_enabled = true

func _physics_process(delta):
    if not _is_enabled:
        return

    var direction = Input.get_axis("ui_left", "ui_right")

    # 设置动画树参数：速度（用于混合 idle/walk/run）
    var speed_param = abs(direction) * move_speed
    anim_tree["parameters/Speed/blend_position"] = speed_param

    # 运行结果: 根据移动速度，动画树自动混合站立/走路/跑步动画

## 禁用动画树（比如角色被冰冻）
func freeze():
    anim_tree.active = false
    _is_enabled = false
    print("角色被冰冻，动画已停止")
    # 运行结果: 角色被冰冻，动画已停止

## 解除冰冻
func unfreeze():
    anim_tree.active = true
    _is_enabled = true
    print("冰冻解除，动画恢复")
    # 运行结果: 冰冻解除，动画恢复

进阶用法：通过属性直接设置（GDScript 风格）

C#

using Godot;

public partial class EnemySpawner : Node
{
    public void SpawnEnemy(PackedScene enemyScene)
    {
        // 生成敌人实例
        Node2D enemy = enemyScene.Instantiate<Node2D>();
        GetTree().CurrentScene.AddChild(enemy);

        // 获取敌人的动画树
        AnimationTree animTree = enemy.GetNode<AnimationTree>("AnimationTree");

        // 初始时禁用动画树（敌人在"待机"状态）
        animTree.SetActive(false);

        // 假设 1 秒后敌人"醒来"
        GetTree().CreateTimer(1.0).Timeout += () =>
        {
            animTree.SetActive(true);
            GD.Print($"{enemy.Name} 的动画树已激活！");
            // 运行结果: Enemy 的动画树已激活！
        };
    }
}

GDScript

extends Node

func spawn_enemy(enemy_scene: PackedScene):
    # 生成敌人实例
    var enemy = enemy_scene.instantiate()
    get_tree().current_scene.add_child(enemy)

    # 获取敌人的动画树
    var anim_tree = enemy.get_node("AnimationTree")

    # 初始时禁用动画树（敌人在"待机"状态）
    anim_tree.active = false

    # 假设 1 秒后敌人"醒来"
    get_tree().create_timer(1.0).timeout.connect(func():
        anim_tree.active = true
        print(enemy.name, " 的动画树已激活！")
        # 运行结果: Enemy 的动画树已激活！
    )

注意事项

• 也可以通过属性设置：GDScript 中可以直接写 anim_tree.active = true，C# 中可以用 animTree.Active = true，效果和 SetActive() 一样。
• 禁用后动画冻结在当前帧：设为 false 时，动画会停在当前状态，所有参数变化都不会生效。
• 必须配置了动画树才能使用：SetActive(true) 之前，AnimationTree 节点必须已经在编辑器中配置好 AnimationNode（如 BlendTree、StateMachine 等），否则启用后不会有任何效果。
• 与 AnimationPlayer 的关系：AnimationTree 内部会控制一个 AnimationPlayer 节点（通过 AnimationPlayer 属性指定）。启用 AnimationTree 后，不建议手动调用那个 AnimationPlayer 的 Play()，两者会冲突。
• 启用时的性能开销：AnimationTree 在 active 时每帧都会计算混合，如果场景中有大量角色，注意性能影响。