在 Godot 4 中实现自定义属性的全面指南

概述

在 Godot 4 引擎中，自定义属性（Custom Properties）的实现是增强节点和资源功能的关键手段。通过自定义属性，开发者可以为游戏对象添加特定的数据和行为，使得项目更加模块化和灵活。本文将详细介绍在 Godot 4 中如何使用 GDScript 和 C# 创建和管理自定义属性，涵盖基础概念、代码示例、编辑器集成以及最佳实践。

1. 自定义属性的基本概念

自定义属性指的是开发者在脚本中定义的变量，这些变量可以通过 Godot 编辑器的 Inspector 面板进行设置和调整。它们用于配置游戏对象的行为、外观或其他特性，如角色的速度、生命值，或 UI 按钮的颜色等。

1.1 为什么使用自定义属性？

• 扩展功能：为节点或资源添加额外的功能。
• 可视化编辑：允许在编辑器中直接修改属性值，提升开发效率。
• 数据序列化：自定义属性会自动保存到场景或资源文件中，便于版本控制和项目管理。

2. 使用 GDScript 实现自定义属性

2.1 基本示例

在 GDScript 中，@export 注解用于将变量暴露到编辑器中，使其可以在 Inspector 面板中进行查看和编辑。

示例代码：

extends Node

# 将变量暴露到编辑器中
@export var health: int = 100
@export var speed: float = 5.0
@export var is_enemy: bool = false

func _ready() -> void:
    # 在 ready 函数中访问自定义属性
    print("Health: ", health)
    print("Speed: ", speed)
    print("Is Enemy: ", is_enemy)
  

在这个示例中，health、speed 和 is_enemy 是通过 @export 注解定义的自定义属性。这些属性可以在 Godot 编辑器中直接编辑和修改。

2.2 使用枚举类型

枚举类型可以为属性提供预定义的选项，提升代码的可读性和可维护性。

示例代码：

extends Node

# 定义枚举类型
enum CharacterState { IDLE, RUNNING, JUMPING, ATTACKING }

# 将枚举类型暴露到编辑器中
@export var state: int = CharacterState.IDLE

func _process(delta: float) -> void:
    match state:
        CharacterState.IDLE:
            print("Character is idle.")
        CharacterState.RUNNING:
            print("Character is running.")
        CharacterState.JUMPING:
            print("Character is jumping.")
        CharacterState.ATTACKING:
            print("Character is attacking.")
  

在 Inspector 面板中，state 属性将显示为一个下拉菜单，用户可以选择不同的状态。

2.3 设置范围限制和滑块

通过 @export_range 注解，可以为数值类型的属性设置范围和步长，使得在编辑器中使用滑块进行调整。

示例代码：

extends Node

# 为 health 设置范围限制，并使用滑块
@export var health: int = 50 setget set_health

# 为 transparency 设置范围限制，并使用滑块
@export var transparency: float = 0.5 setget set_transparency

func set_health(value: int) -> void:
    health = clamp(value, 0, 100)

func set_transparency(value: float) -> void:
    transparency = clamp(value, 0.0, 1.0)
  

在此示例中，health 的值被限制在 0 到 100 之间，transparency 的值被限制在 0.0 到 1.0 之间。

3. 使用 C# 实现自定义属性

3.1 基本示例

在 C# 中，可以使用 [Export] 特性将字段暴露到编辑器中。

示例代码：

using Godot;
using System;

public partial class MyNode : Node2D
{
    [Export]
    public int Speed { get; set; } = 100;

    [Export]
    public Color NodeColor { get; set; } = new Color(1, 0, 0);

    public override void _Process(double delta)
    {
        Position += new Vector2((float)(Speed * delta), 0);
        Modulate = NodeColor;
    }
}
  

在这个示例中，Speed 和 NodeColor 被暴露到编辑器中，用户可以直接在 Inspector 面板中进行配置。

3.2 使用枚举类型

同样可以在 C# 中使用枚举类型，并通过 [Export] 特性将其暴露到编辑器中。

示例代码：

using Godot;
using System;

public enum State
{
    Idle,
    Run,
    Jump,
    Attack
}

public partial class MyNode : Node2D
{
    [Export]
    public State CurrentState { get; set; } = State.Idle;

    public override void _Process(double delta)
    {
        switch (CurrentState)
        {
            case State.Idle:
                GD.Print("State: Idle");
                break;
            case State.Run:
                GD.Print("State: Run");
                break;
            case State.Jump:
                GD.Print("State: Jump");
                break;
            case State.Attack:
                GD.Print("State: Attack");
                break;
        }
    }
}
  

在 Inspector 面板中，CurrentState 将显示为一个下拉菜单，用户可以选择不同的状态。

3.3 设置范围限制

可以为数值属性设置范围限制，使其在编辑器中通过滑块进行调整。

示例代码：

using Godot;
using System;

public partial class MyNode : Node2D
{
    [Export(PropertyHint.Range, "0,100,1")]
    public int Health { get; set; } = 50;

    [Export(PropertyHint.Range, "0.0,1.0,0.01")]
    public float Transparency { get; set; } = 0.5f;

    public override void _Process(double delta)
    {
        // 使用 Health 和 Transparency 属性
    }
}
  

在编辑器中，Health 和 Transparency 将分别显示为带有指定范围和步长的滑块。

4. 使用 EditorInspectorPlugin 创建自定义属性编辑器

当默认的属性编辑器满足不了需求时，可以通过创建自定义的属性编辑器来增强编辑体验。EditorInspectorPlugin 允许开发者为特定属性定义自定义的编辑器界面。

4.1 创建 EditorInspectorPlugin

下面是一个示例，展示如何创建一个自定义的 Inspector 插件，为特定属性添加自定义编辑器：

示例代码：

tool
extends EditorInspectorPlugin

func can_handle(object: Object) -> bool:
    return object is MyCustomNode

func parse_begin(object: Object) -> void:
    # 添加自定义控件到属性列表的开头
    pass

func parse_end(object: Object) -> void:
    # 添加自定义控件到属性列表的末尾
    pass

func parse_property(object: Object, type: int, name: String, hint_type: int, hint_string: String, usage_flags: int, wide: bool) -> bool:
    if name == "my_custom_property":
        var editor = MyCustomPropertyEditor.new()
        add_property_editor(name, editor)
        return true
    return false

class MyCustomPropertyEditor extends EditorProperty:
    func _init() -> void:
        add_child(Label.new())
        # 初始化自定义编辑器控件

    func update_property() -> void:
        # 更新属性值
        pass
  

在这个示例中，EditorInspectorPlugin 被用来检测是否支持特定类型的节点，并为特定的属性（如 my_custom_property）添加一个自定义编辑器。

5. 使用 Resource 创建自定义资源

通过创建自定义资源，可以将相关的数据封装在一起，便于管理和复用。这些资源可以在编辑器中直接编辑，并在不同的节点之间共享。

5.1 创建自定义资源脚本

以下是一个示例，展示如何创建一个自定义资源脚本：

示例代码：

tool
extends Resource

class_name CustomResource

@export var data: Dictionary = {}

func _init() -> void:
    # 初始化资源数据
    pass
  

这个脚本定义了一个名为 CustomResource 的资源，可以在 Inspector 面板中编辑 data 字段。

5.2 在节点中使用自定义资源

创建自定义资源后，可以在节点脚本中声明并使用它：

示例代码：

extends Node

@export var custom_resource: Resource = CustomResource.new()

func _ready() -> void:
    print(custom_resource.data)
  

通过这种方式，自定义资源可以作为数据容器，在不同节点间共享和管理数据。

6. 高级用法与最佳实践

6.1 自定义 Getter 和 Setter

通过定义 Getter 和 Setter，可以在属性访问时执行额外的逻辑，如数据验证或触发事件。

示例代码：

extends Node

@export var speed: int = 100 setget set_speed, get_speed
var _speed_internal: int = 100

func set_speed(value: int) -> void:
    _speed_internal = clamp(value, 0, 500)
    emit_signal("speed_changed", _speed_internal)

func get_speed() -> int:
    return _speed_internal

signal speed_changed(new_speed)
  

在这个示例中，speed 属性的 setter 函数对输入值进行了限制，并在值变化时发出信号。

6.2 信号与属性联动

当属性值发生变化时，可以通过信号通知其他部分的逻辑或 UI 更新。

示例代码：

extends Node

@export var health: int = 100 setget set_health
signal health_changed(new_health)

func set_health(value: int) -> void:
    health = clamp(value, 0, 100)
    emit_signal("health_changed", health)
  

此代码在 health 属性变化时发出 health_changed 信号，可以用于更新 UI 或触发其他游戏逻辑。

6.3 性能优化

合理使用自定义属性，避免过多的属性导致性能下降。对于仅在编辑器中使用的属性，可以通过逻辑区分运行时和编辑器行为，确保运行时的高效性。

7. 实际应用场景

7.1 角色属性配置

自定义属性可以用于定义角色的各项属性，如健康值、移动速度、攻击力等。

示例代码：

extends Node

@export var health: int = 100
@export var speed: float = 5.0
@export var attack_power: int = 20
@export var defense: int = 10
  

7.2 UI 组件配置

通过自定义属性，可以快速配置 UI 组件的外观和行为，如按钮的文本和颜色。

示例代码：

extends Control

@export var button_text: String = "Click Me"
@export var button_color: Color = Color(0, 0, 1)
  

7.3 游戏关卡配置

自定义属性可以用于配置不同的游戏关卡，如敌人数量、关卡名称和下一个关卡的路径。

示例代码：

extends Node

@export var enemy_count: int = 5
@export var level_name: String = "Level 1"
@export var next_level: String = "res://levels/level2.tscn"
  

8. 注意事项与最佳实践

8.1 合理使用范围和默认值

为属性提供合理的默认值和范围，确保在编辑器中易于编辑和理解。

8.2 避免过多的自定义属性

如果一个节点的自定义属性过多，可能需要重新设计场景或逻辑，以保持代码的简洁和可维护性。

8.3 使用脚本类名

为脚本定义 class_name，这样可以在编辑器中直接选择脚本类型，简化脚本分配过程。

8.4 优化性能

仅在必要时使用自定义属性，避免在运行时处理过多的属性逻辑，确保游戏的高效运行。

9. 结论

在 Godot 4 中，自定义属性的实现为开发者提供了强大的工具，用于扩展节点和资源的功能。无论是通过 GDScript 还是 C#，自定义属性都能显著提升开发效率和代码的可维护性。通过合理的设计和最佳实践，开发者可以创建灵活且高效的游戏系统，充分发挥 Godot 引擎的潜力。

10. 参考资料