GDScript 子集语法参考

GDCC 支持强类型和弱类型混合编写。可以给属性、局部变量、参数和返回值写显式类型，也可以省略类型让它们落到 Variant。Variant 表示运行时动态值，适合渐进迁移；显式类型适合让编译器尽早检查赋值、调用参数和返回值。

var typed_score: int = 10
var dynamic_payload

func mix(value, count: int) -> Variant:
    var local := count + 1
    dynamic_payload = value
    return local

类型系统

动态类型

支持 Variant。以下位置省略类型时通常按 Variant 处理：

函数参数。
函数返回值。
类属性。
部分局部变量。

func echo(value):
    return value

func reopen(seed: Variant) -> int:
    return int(seed)

支持的 Variant 边界：

具体类型赋给 Variant。
Variant 赋给具体目标类型。
Variant 作为动态调用目标来调用方法。
Variant 返回值赋给显式类型变量。

内建类型

支持以下类型标注：

类型组	支持类型
空值/动态/无返回	`Nil`、`null`、`Variant`、`void`、`Void`
标量	`bool`、`int`、`float`
字符串类	`String`、`StringName`、`NodePath`
几何/数学	`Vector2`、`Vector2i`、`Vector3`、`Vector3i`、`Vector4`、`Vector4i`、`Rect2`、`Rect2i`、`Transform2D`、`Transform3D`、`Plane`、`Quaternion`、`AABB`、`Basis`、`Projection`、`Color`
句柄/可调用	`RID`、`Callable`、`Signal`
容器	`Array`、`Dictionary`
PackedArray	`PackedByteArray`、`PackedInt32Array`、`PackedInt64Array`、`PackedFloat32Array`、`PackedFloat64Array`、`PackedStringArray`、`PackedVector2Array`、`PackedVector3Array`、`PackedVector4Array`、`PackedColorArray`
对象	`Object`、Godot 引擎类、GDCC 脚本类、词法可见内部类

类型化容器

支持 Array[T] 和 Dictionary[K, V]。

var nodes: Array[Node]
var workers: Array[Worker]
var payloads: Dictionary[StringName, Node]

支持规则：

Array 是普通动态数组。
Dictionary 是普通动态字典。
Array[T] 的 T 必须是可解析叶子类型。
Dictionary[K, V] 的 K 和 V 必须是可解析叶子类型。
Array[Array] 这类叶子为裸容器名的写法可用。

当前支持的类型兼容

Source	Target	状态
同类型	同类型	支持
`int`	`float`	支持
任意稳定类型	`Variant`	支持
`Variant`	具体类型	支持
对象子类	对象父类	支持
`null`	对象类型	支持
`Array[Child]`	`Array[Parent]`	有限支持
`Dictionary[K1, V1]`	`Dictionary[K2, V2]`	有限支持

int -> float 适用于需要 float 的显式类型位置，包括赋值、属性初始化、调用参数、返回值、内建构造函数的 float 参数，以及 Dictionary[float, V] 的 key。通过 Godot 动态调用编译脚本时，也允许把 int 传给 float 参数；对外显示的参数类型仍然是 float。

var ratio: float = 1

func take_float(value: float) -> float:
    return value

func compute(scores: Dictionary[float, int]) -> float:
    scores[2] = 7
    return take_float(3)

常见不支持转换：

float -> int。
bool -> int。
bool -> float。
String -> StringName。
StringName -> String。
String -> NodePath。
Vector3i -> Vector3。
Vector3 -> Vector3i。
Array[int] -> Array[float]。
Dictionary[int, V] -> Dictionary[float, V]。
enum 作为一等类型参与类型兼容判断。

文件和类

顶层脚本类

每个 .gd 文件对应一个顶层脚本类。

class_name Player
extends Node

var hp: int = 100

支持写法：

class_name Player
class_name Player extends Node
单独顶层 extends Node
省略 class_name，类名从文件名推导。
省略 extends，默认父类为 RefCounted。

不支持写法：

extends "res://player_base.gd"
autoload 父类绑定。
跨模块父类绑定。
复杂父类表达式。

内部类

支持内部类和多层内部类。

class_name Outer
extends Node

class Worker extends RefCounted:
    var value: int

    func read_value() -> int:
        return value

func make_worker() -> Worker:
    return Worker.new()

支持写法：

class Worker:
class Worker extends RefCounted:
内部类继续包含内部类。
内部类作为类型标注使用。
内部类声明属性、信号、函数和静态函数。

注解

支持少量属性注解。

@export var visible_payload: Variant
@onready var target: Node

支持写法：

@export var name: Type
@onready var name: Type

@onready 使用限制：

只能用于类属性 var。
不能用于 static var。
owner 类必须继承 Node。

不支持或不要依赖：

@export_range(...)
函数 @rpc(...) 的编译语义。
@warning_ignore(...) 的编译语义。
@tool 的运行时语义。
@icon 的运行时语义。

成员声明

属性

var score: int = 0
var payload: Variant
var values: Array[int]
var worker: Worker = Worker.new()

支持写法：

var name
var name = value
var name: Type
var name: Type = value
var name := value
@export var name: Type
@onready var name: Type

注意事项：

属性建议写显式类型。
未写显式类型的属性按 Variant 处理。
:= 属性当前也会作为 Variant 属性处理。
有初始值的属性支持常见表达式、构造调用、静态常量、静态调用和链式访问。
属性初始值不要读取当前实例的非静态属性、信号、实例方法或 self。

不支持写法：

static var shared: int
const NAME = value
依赖 property := 推导成非 Variant 属性类型。

信号

signal changed(value: int)
signal ready()

支持写法：

无参数信号。
带类型参数信号。
信号作为类成员被声明和绑定。

不支持或不要依赖：

await changed
信号 coroutine flow。
复杂信号发射流程。

函数

func add(a: int, b: int) -> int:
    return a + b

static func build() -> Worker:
    return Worker.new()

func _init() -> void:
    pass

支持写法：

实例函数。
static func。
显式参数类型。
省略参数类型，参数为 Variant。
显式返回类型。
省略返回类型，返回槽为 Variant。
零参数 _init。

不支持或受限写法：

GDCC 自定义类带参数 .new(...)。
依赖带参数 _init 被 .new(...) 自动调用。
参数默认值。
脚本函数 vararg 的完整 GDScript 行为。

引擎虚函数

支持引擎虚函数覆盖，签名必须精确。

func _ready() -> void:
    pass

func _process(delta: float) -> void:
    pass

func _physics_process(delta: float) -> void:
    pass

特别注意：

_process(delta) 不等价于 _process(delta: float)。
_physics_process(delta) 不等价于 _physics_process(delta: float)。
虚函数必须是实例函数。
参数数量、参数类型、返回类型必须匹配。

语句

`pass` 和注释

func noop() -> void:
    # allowed
    pass

支持：

pass
普通注释

局部变量

func compute(seed: int) -> int:
    var value: int = seed + 1
    var dynamic_value = value
    var inferred := value * 2
    return inferred

支持写法：

var name
var name = value
var name: Type
var name: Type = value
var name := value

不支持写法：

const local_value = 1
同一作用域重复声明同名局部变量。

赋值

func update(values: Array) -> void:
    var local: int = 1
    local = local + 1
    values[0] = local
    self.hp = local

支持赋值目标：

局部变量。
参数。
类属性。
self.property。
属性链。
数组索引。
字典索引。
PackedArray 索引和支持的可写路径。

复合赋值

func run_once() -> int:
    var local: int = 3
    local += 4
    total *= local
    total -= 2
    return total

支持运算符：

+=
-=
*=
/=
%=
**=
<<=
>>=
&=
^=
|=

`return`

func read_value() -> int:
    return 1

func maybe_value(flag: bool):
    if flag:
        return 1
    return

支持：

return expr
bare return

规则：

return expr 必须兼容返回类型。
void 函数只能 bare return。
Variant 返回函数可以 bare return。
int、float、对象等具体返回类型不能 bare return。

`if` / `elif` / `else`

func branch_value(value: int) -> int:
    if value > 0:
        return 100
    elif value:
        return 10
    else:
        return 1

支持：

if condition:
elif condition:
else:
嵌套分支。
非 bool condition 的 truthiness。

`while`

func sum(limit: int) -> int:
    var index := 0
    var total := 0
    while index < limit:
        total += index
        index += 1
    return total

支持：

while condition:
嵌套 while。
循环内 break。
循环内 continue。

不支持：

for
match
assert
await
lambda body
coroutine flow

表达式

字面量

var n: int = 1
var f: float = 1.5
var ok: bool = true
var missing: Object = null
var text: String = "hello"
var name: StringName = &"Player"

支持：

整数字面量。
浮点字面量。
true / false。
null。
字符串字面量。
StringName 字面量：&"name"。
字符串转义：\"、\n、\t、\\、\uXXXX、\UXXXXXXXX。
UTF-8 字符串内容。

不支持：

数组字面量：[1, 2, 3]。
字典字面量：{"key": value}。

标识符和 `self`

支持：

局部变量。
参数。
属性。
信号。
singleton。
global enum。
类型名。
内部类名。
self。

self 使用限制：

实例函数中可用。
静态函数中不可用。
属性初始值中不要依赖。

属性链

func vector_y() -> float:
    var vector: Vector3 = Vector3(1.0, 2.0, 3.0)
    return vector.y

支持：

对象属性读取。
对象属性写入。
对象方法调用。
内建值属性读取，例如 Vector3.x、Color.a。
内建值属性写入，例如 vector.x = 1.0。
静态常量，例如 Vector3.ZERO、Color.RED。
链式访问，例如 Node.new().get_class()。

不支持：

vector["x"] 形式的内建属性访问。使用 vector.x。

索引

func compute(values: Array) -> int:
    values[1] = 6
    var first: int = values[0]
    var second: int = values[1]
    return first * 10 + second

支持：

Array 读取和写入。
Dictionary 读取和写入。
PackedInt32Array 等 PackedArray 读取。
属性链中的索引，例如 holder.values[0]。
类型化数组读取返回元素类型。

注意：

键和索引的类型转换较严格；当前 Dictionary[float, V] 的键可以接收 int。
字典 key 类型不明确时，优先显式放入 Variant。

调用

func helper(value: int) -> int:
    return value + 1

func compute(seed: int) -> int:
    return helper(seed)

支持：

裸函数调用。
实例方法调用。
静态方法调用。
Godot utility function，例如 typeof(...)。
引擎方法调用。
内建方法调用。
语句位置丢弃 void 调用返回值。
部分引擎默认参数调用。
部分引擎 vararg 调用。
Variant 动态调用目标。

构造调用

var vector: Vector3 = Vector3(1, 2.0, 3)
var values: Array = Array()
var table: Dictionary = Dictionary()
var name: StringName = StringName("Player")
var node: Node = Node.new()
var worker: Worker = Worker.new()

支持：

内建类型裸构造。
int(value)、String(value)。
Array()、Dictionary()。
PackedArray 构造。
engine class .new()。
GDCC 自定义类零参数 .new()。

不支持：

GDCC 自定义类带参数 .new(...)。
用裸调用构造对象类型，例如 Node()。

一元运算符

支持：

not expr
!expr
+expr
-expr
~expr

二元运算符

支持：

类型	运算符
逻辑短路	`and`、`&&`、`or`、`
算术	`+`、`-`、``、`/`、`%`、`*`
位运算	`<<`、`>>`、`&`、`\|`、`^`
比较	`==`、`!=`、`<`、`<=`、`>`、`>=`
包含	`in`

当前不支持的表达式

写法	状态	替代写法
`[1, 2, 3]`	不支持	`Array()` + `push_back`
`{"a": 1}`	不支持	`Dictionary()` + 索引赋值
`a if cond else b`	不支持	`if` 语句
`preload("res://...")`	不支持	暂不使用
`$Node`	不支持	暂不使用 shorthand
`value as Type`	不支持	显式构造或 `Variant` 边界
`value is Type`	不支持	暂不使用
lambda	不支持	普通函数
`await expr`	不支持	暂不使用

数据结构写法

数组

func build_values() -> Array:
    var values: Array = Array()
    values.push_back(2)
    values.push_back(4)
    values.push_back(6)
    return values

支持：

Array()。
push_back(...)。
size()。
resize(...)。
values[index]。
values[index] = value。

字典

func build_scores() -> Dictionary:
    var scores: Dictionary = Dictionary()
    scores["alpha"] = 2
    scores["beta"] = 5
    return scores

支持：

Dictionary()。
size()。
has(key)。
dict[key]。
dict[key] = value。

PackedArray

func compute() -> int:
    var values: PackedInt32Array = PackedInt32Array()
    values.push_back(4)
    values.push_back(5)
    values.push_back(6)
    return values[0] * 100 + values[1] * 10 + values[2]

支持：

PackedArray 构造。
常见方法调用。
索引读取。
支持面内的 mutation。

常用替代写法

用 `while` 替代 `for`

func sum(values: Array) -> int:
    var index := 0
    var total := 0
    while index < values.size():
        total += int(values[index])
        index += 1
    return total

用构造和方法替代数组字面量

var values: Array = Array()
values.push_back(1)
values.push_back(2)
values.push_back(3)

用构造和索引赋值替代字典字面量

var scores: Dictionary = Dictionary()
scores["alpha"] = 2
scores["beta"] = 5

用初始化方法替代带参构造

class Worker extends RefCounted:
    var value: int

    func setup(next: int) -> void:
        value = next

func make_worker(seed: int) -> Worker:
    var worker: Worker = Worker.new()
    worker.setup(seed)
    return worker

完整示例

class_name InventoryCounter
extends Node

class Item extends RefCounted:
    var amount: int

    func set_amount(next: int) -> void:
        amount = next

    func read_amount() -> int:
        return amount

var total: int = 0

func make_item(amount: int) -> Item:
    var item: Item = Item.new()
    item.set_amount(amount)
    return item

func add_amounts(values: Array) -> int:
    var index := 0
    total = 0
    while index < values.size():
        var item: Item = make_item(int(values[index]))
        total += item.read_amount()
        index += 1
    return total

不支持写法速查

写法	状态
`for item in values:`	不支持
`match value:`	不支持
`func f(a = 1):`	参数默认值不支持
`assert(condition)`	不支持
`await signal`	不支持
`lambda`	不支持
`const X = 1`	不支持
`static var x: int`	不支持
`[1, 2, 3]`	不支持
`{"a": 1}`	不支持
`a if cond else b`	不支持
`preload(...)`	不支持
`$Node`	不支持
`value as Type`	不支持
`value is Type`	不支持
`not in`	不支持
`extends "res://base.gd"`	不支持
`Custom.new(arg)`	GDCC 自定义类带参构造不支持

GDScript 子集语法参考

类型系统

动态类型

内建类型

类型化容器

当前支持的类型兼容

文件和类

顶层脚本类

内部类

注解

成员声明

属性

信号

函数

引擎虚函数

语句

pass 和注释

局部变量

赋值

复合赋值

return

if / elif / else

while

表达式

字面量

标识符和 self

属性链

索引

调用

构造调用

一元运算符

二元运算符

当前不支持的表达式

数据结构写法

数组

字典

PackedArray

常用替代写法

用 while 替代 for

用构造和方法替代数组字面量

用构造和索引赋值替代字典字面量

用初始化方法替代带参构造

完整示例

不支持写法速查

`pass` 和注释

`return`

`if` / `elif` / `else`

`while`

标识符和 `self`

用 `while` 替代 `for`