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

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

@global_class

定义

@global_class 是 GDScript 中的一个注解（annotation），用来将当前脚本注册为一个全局可用的自定义类型。注册后，你可以在任何地方使用这个类名来创建节点、声明变量类型，而不需要先加载或引用对应的脚本文件。

简单说，正常情况下你要用 preload("res://xxx.gd") 才能引用另一个脚本。加了 @global_class 之后，这个脚本就像 Godot 内置类型（如 RigidBody3D、Sprite2D）一样，直接用类名就能引用，非常方便。

想象你做了一个 HealthComponent 脚本，加了 @global_class 之后，在任何脚本里直接写 var health: HealthComponent 就行，不用管文件路径。

在 C# 中，对应的写法是在类上方添加 [GlobalClass] 特性。

语法

C#

// 将类注册为全局类型
[GlobalClass]
public partial class HealthComponent : Node
{
    [Export] public int ExMaxHealth = 100;
}

GDScript

# 将脚本注册为全局类型
class_name HealthComponent
extends Node

@export var ex_max_health: int = 100

参数说明

@global_class 不需要任何参数。在 GDScript 中，通常使用 class_name 关键字来同时实现全局类注册和命名。@global_class 和 class_name 的效果相同。

说明项	详情
放置位置	脚本顶部
命名	GDScript 中用 class_name 名称 指定类名
效果	注册后可在任意脚本中直接使用类名引用
编辑器	在"添加节点"对话框和检查器类型提示中出现

返回值

@global_class 是一个注解，没有返回值。它的作用是将当前脚本注册为全局类型，使其在项目中的任何地方都可用。

代码示例

C#

using Godot;

// ===== 基础用法：注册全局类 =====
// HealthComponent.cs
[GlobalClass]
public partial class HealthComponent : Node
{
    [Export] public int ExMaxHealth = 100;
    private int _currentHealth;

    public override void _Ready()
    {
        _currentHealth = ExMaxHealth;
    }
}

// ===== 在其他脚本中使用全局类 =====
// Player.cs
public partial class Player : CharacterBody3D
{
    // 可以直接使用 HealthComponent 类型，不需要知道文件路径
    private HealthComponent _health;

    public override void _Ready()
    {
        _health = GetNode<HealthComponent>("HealthComponent");
        GD.Print($"玩家最大生命: {_health.ExMaxHealth}");
    }
}
// 运行结果: 玩家最大生命: 100


// ===== 实际场景：组件系统 =====
// InventoryComponent.cs
[GlobalClass]
public partial class InventoryComponent : Node
{
    [Export] public int ExMaxSlots = 20;
    private int _usedSlots = 0;

    public bool AddItem(string itemName)
    {
        if (_usedSlots >= ExMaxSlots)
        {
            GD.Print("背包已满！");
            return false;
        }
        _usedSlots++;
        GD.Print($"拾取: {itemName}，已用槽位: {_usedSlots}/{ExMaxSlots}");
        return true;
    }
}

// 使用组件
public partial class Chest : StaticBody3D
{
    private InventoryComponent _inventory;

    public override void _Ready()
    {
        _inventory = GetNode<InventoryComponent>("InventoryComponent");
        _inventory.AddItem("金币");
        _inventory.AddItem("红药水");
    }
}
// 运行结果: 拾取: 金币，已用槽位: 1/20
// 运行结果: 拾取: 红药水，已用槽位: 2/20


// ===== 进阶用法：自定义资源类型 =====
[GlobalClass]
public partial class WeaponData : Resource
{
    [Export] public string ExWeaponName = "未命名武器";
    [Export] public int ExDamage = 10;
    [Export] public float ExAttackSpeed = 1.0f;

    public string GetDescription()
    {
        return $"{ExWeaponName}: 攻击力 {ExDamage}，攻速 {ExAttackSpeed}";
    }
}

// 使用自定义资源
public partial class Weapon : Node3D
{
    [Export] public WeaponData ExData;

    public override void _Ready()
    {
        if (ExData != null)
        {
            GD.Print(ExData.GetDescription());
        }
    }
}
// 运行结果: 铁剑: 攻击力 15，攻速 1.5

GDScript

# ===== 基础用法：注册全局类 =====
# health_component.gd
class_name HealthComponent
extends Node

@export var ex_max_health: int = 100
var _current_health: int

func _ready():
    _current_health = ex_max_health

# ===== 在其他脚本中使用全局类 =====
# player.gd
extends CharacterBody3D

# 可以直接使用 HealthComponent 类型，不需要知道文件路径
@onready var _health: HealthComponent = $HealthComponent

func _ready():
    print("玩家最大生命: %d" % _health.ex_max_health)
# 运行结果: 玩家最大生命: 100


# ===== 实际场景：组件系统 =====
# inventory_component.gd
class_name InventoryComponent
extends Node

@export var ex_max_slots: int = 20
var _used_slots: int = 0

func add_item(item_name: String) -> bool:
    if _used_slots >= ex_max_slots:
        print("背包已满！")
        return false
    _used_slots += 1
    print("拾取: %s，已用槽位: %d/%d" % [item_name, _used_slots, ex_max_slots])
    return true

# chest.gd
extends StaticBody3D

@onready var _inventory: InventoryComponent = $InventoryComponent

func _ready():
    _inventory.add_item("金币")
    _inventory.add_item("红药水")
# 运行结果: 拾取: 金币，已用槽位: 1/20
# 运行结果: 拾取: 红药水，已用槽位: 2/20


# ===== 进阶用法：自定义资源类型 =====
# weapon_data.gd
class_name WeaponData
extends Resource

@export var ex_weapon_name: String = "未命名武器"
@export var ex_damage: int = 10
@export var ex_attack_speed: float = 1.0

func get_description() -> String:
    return "%s: 攻击力 %d，攻速 %.1f" % [ex_weapon_name, ex_damage, ex_attack_speed]

# weapon.gd
extends Node3D

@export var ex_data: WeaponData

func _ready():
    if ex_data:
        print(ex_data.get_description())
# 运行结果: 铁剑: 攻击力 15，攻速 1.5

注意事项

• 在 GDScript 中，推荐使用 class_name 关键字而不是 @global_class 注解，两者效果相同但 class_name 更常见、更符合社区习惯。
• 全局类名必须在整个项目中唯一，不能和 Godot 内置类名（如 Node、Sprite2D）重复。
• 注册全局类后，在编辑器的"添加节点"对话框中可以搜索到这个自定义类型。
• 过多使用全局类可能导致编辑器启动变慢（因为需要扫描所有全局类型），建议只在需要跨文件引用时使用。
• C# 中使用 [GlobalClass] 特性注册全局类。
• 如果不需要全局可见，可以不注册——用 preload() 或 load() 直接引用脚本文件即可。