gdscript基础¶

介绍¶

GDScript 是一种用于创建内容的高级动态类型编程语言。它使用的语法类似于 Python （块是基于缩进的，许多关键字相似）。它的目标是针对Godot引擎进行优化并与之紧密集成，从而为内容创建和集成提供极大的灵活性。

历史¶

早期，引擎使用 Lua 脚本语言。Lua速度很快，但是创建到面向对象系统的绑定（通过使用回退）非常复杂和缓慢，并且需要大量的代码。经过一些实验 Python 也很难嵌入。

最后一种用于附带游戏的第三方脚本语言是 Squirrel 但是它也掉了。在这一点上，很明显自定义脚本语言可以更优化地利用Godot的特定体系结构：

godot在节点中嵌入脚本。大多数语言的设计都没有考虑到这一点。
Godot使用几种内置数据类型进行二维和三维数学运算。脚本语言不提供这一点，并且绑定它们的效率很低。
godot大量使用线程从网络或磁盘提升和初始化数据。通用语言的脚本解释程序对此不友好。
godot已经有了一个资源的内存管理模型，大多数脚本语言都提供了自己的内存管理模型，这会导致重复的工作和错误。
绑定代码总是乱七八糟的，会导致几个故障点、意外的错误和一般的低可维护性。

这些考虑的结果是 GDScript . gdscript的语言和解释器最终比lua和squirrel的绑定代码小，但功能相同。随着时间的推移，拥有内置语言已经被证明是一个巨大的优势。

gdscript示例¶

有些人可以通过查看语法来更好地学习，所以这里有一个关于gdscript外观的简单示例。

# A file is a class!

# Inheritance

extends BaseClass

# (optional) class definition with a custom icon

class_name MyClass, "res://path/to/optional/icon.svg"

# Member Variables

var a = 5
var s = "Hello"
var arr = [1, 2, 3]
var dict = {"key": "value", 2:3}
var typed_var: int
var inferred_type := "String"

# Constants

const ANSWER = 42
const THE_NAME = "Charly"

# Enums

enum {UNIT_NEUTRAL, UNIT_ENEMY, UNIT_ALLY}
enum Named {THING_1, THING_2, ANOTHER_THING = -1}

# Built-in Vector Types

var v2 = Vector2(1, 2)
var v3 = Vector3(1, 2, 3)

# Function

func some_function(param1, param2):
    var local_var = 5

    if param1 < local_var:
        print(param1)
    elif param2 > 5:
        print(param2)
    else:
        print("Fail!")

    for i in range(20):
        print(i)

    while param2 != 0:
        param2 -= 1

    var local_var2 = param1 + 3
    return local_var2

# Functions override functions with the same name on the base/parent class.
# If you still want to call them, use '.' (like 'super' in other languages).

func something(p1, p2):
    .something(p1, p2)

# Inner Class

class Something:
    var a = 10

# Constructor

func _init():
    print("Constructed!")
    var lv = Something.new()
    print(lv.a)

如果您以前有过静态类型语言（如C、C++或C# ）的经验，但以前从未使用过动态类型的语言，建议您阅读本教程： gdscript：动态语言简介 .

语言¶

以下是对gdscript的概述。应在链接类描述中查找详细信息，例如哪些方法可用于数组或其他对象。

标识符¶

将自身限制为字母字符的任何字符串 (a 到 z 和 A 到 Z ），数字 (0 到 9 ） _ 限定为标识符。此外，标识符不能以数字开头。标识符区分大小写 (foo 不同于 FOO ）

关键词¶

下面是该语言支持的关键字列表。由于关键字是保留字（标记），因此不能用作标识符。操作员（如 in ， not ， and 或 or ）同时，还保留了以下部分列出的内置类型的名称。

关键字定义在 GDScript tokenizer 万一你想看看引擎盖下面。

关键字	描述
如果	见 if/else/elif .
否则如果	见 if/else/elif .
其他的	见 if/else/elif .
对于	见 for.
虽然	见 while.
比赛	见 match.
打破	退出当前的执行 `for` 或 `while` 循环。
持续	立即跳到 `for` 或 `while` 循环。
通过	在语法上需要语句但不希望执行代码的情况下使用，例如在空函数中。
返回	返回函数的值。
类	定义类。
延伸	定义要用当前类扩展的类。
是	测试变量是扩展给定的类，还是属于给定的内置类型。
作为	如果可能，将值强制转换为给定的类型。
自己	引用当前类实例。
工具	在编辑器中执行脚本。
信号	定义信号。
芬克	定义函数。
静止的	定义静态函数。不允许静态成员变量。
康斯特	定义常量。
枚举	定义枚举。
var	定义变量。
准备就绪	一旦脚本附加到的节点及其子节点是场景树的一部分，则初始化变量。
出口	保存变量及其附加的资源，并使其在编辑器中可见和可修改。
设置程序	为变量定义setter和getter函数。
断点	调试器断点的编辑器帮助程序。
预紧力	预加载类或变量。见 Classes as resources .
产量	连体衣支撑。见 Coroutines with yield .
断言	断言条件，记录失败时的错误。在非调试生成中被忽略。见 Assert keyword .
遥远的	网络RPC注释。见 high-level multiplayer docs .
主人	网络RPC注释。见 high-level multiplayer docs .
木偶	网络RPC注释。见 high-level multiplayer docs .
远程同步	网络RPC注释。见 high-level multiplayer docs .
主同步	网络RPC注释。见 high-level multiplayer docs .
木偶同步	网络RPC注释。见 high-level multiplayer docs .
PI	π常数。
TAU	τ常数。
INF	无穷大常数。用于比较。
NAN	NaN（不是数字）常量。用于比较。

算子¶

以下是支持的运算符及其优先级的列表。

算符	描述
`x[index]`	订阅，最高优先级
`x.attribute`	属性引用
`is`	实例类型检查器
`~`	按位取反
`-x`	阴性/一元阴性
`*` `/` `%`	乘法/除法/余数这些操作符具有与C++相同的行为。整数除法被截断而不是返回一个分数，%运算符只能用于整数（“fmod”表示浮点数）
`+`	数组的添加/串联
`-`	减法
`<<` `>>`	钻头移动
`&`	按位与
`^`	按位异或
`\|`	按位或
`<` `>` `==` `!=` `>=` `<=`	比较
`in`	内容测试
`!` `not`	布尔不
`and` `&&`	布尔与
`or` `\|\|`	布尔或
`if x else`	三元if/else
`=` `+=` `-=` `*=` `/=` `%=` `&=` `\|=`	分配，最低优先级

直接常量¶

字面意义的	Type
`45`	以10为底的整数
`0x8F51`	基16（十六进制）整数
`3.14`, `58.1e-10`	浮点数（实数）
`"Hello"`, `"Hi"`	字符串
`"""Hello"""`	多行字符串
`@"Node/Label"`	nodePath或stringName
`$NodePath`	缩写为 `get_node("NodePath")`

评论¶

任何来自 # 到行尾将被忽略，并被视为注释。

# This is a comment.

可以在文本块的开头和结尾使用“”（一行中有三个引号）创建多行注释。请注意，这会创建一个字符串，因此在编译脚本时，它不会被剥离。

""" Everything on these
lines is considered
a comment. """

内置类型¶

内置类型是堆栈分配的。它们作为值传递。这意味着在每次赋值或将它们作为参数传递给函数时都会创建一个副本。唯一的例外是 Array S和 Dictionaries ，通过引用传递，以便共享。（不是） PoolArray 像 PoolByteArray 不过，这些值也是作为值传递的，因此在决定使用哪一个时要考虑到这一点！）

基本内置类型¶

可以将gdscript中的变量分配给多个内置类型。

无效的¶

null 是一个空数据类型，它不包含任何信息，不能分配任何其他值。

布尔¶

布尔数据类型只能包含 true 或 false .

利息¶

integer数据类型只能包含整数（负数和正数）。

浮动¶

用于包含浮点值（实数）。

String ¶

中的字符序列 Unicode format . 字符串可以包含 standard C escape sequences . gdscript支持 format strings aka printf functionality .

向量内置类型¶

Vector2 ¶

包含的二维矢量类型 x 和 y 领域。也可以作为数组访问。

Rect2 ¶

包含两个矢量字段的二维矩形类型： position 和 size . 或者包含 end 字段 position+size .

Vector3 ¶

包含的三维矢量类型 x ， y 和 z 领域。这也可以作为数组访问。

Transform2D ¶

3x2矩阵用于二维转换。

Plane ¶

标准化形式的三维平面类型，其中包含 normal 向量场和A d 标量距离。

Quat ¶

四元数是用于表示三维旋转的数据类型。它对插值旋转很有用。

AABB ¶

轴对齐的边界框（或三维框）包含两个矢量字段： position 和 size . 或者包含 end 字段 position+size .

Basis ¶

3x3矩阵用于三维旋转和缩放。它包含3个向量场 (x ， y 和 z ）也可以作为一个三维向量数组访问。

Transform ¶

三维变换包含基字段 basis 和矢量3场 origin .

引擎内置类型¶

Color ¶

颜色数据类型包含 r ， g ， b 和 a 领域。它也可以访问为 h ， s 和 v 色调/饱和度/值。

NodePath ¶

主要用于场景系统的节点的编译路径。它可以很容易地分配给一个字符串，也可以从一个字符串中分配。

RID ¶

资源ID（RID）。服务器使用通用RID引用不透明数据。

Object ¶

任何不是内置类型的东西的基类。

容器内置类型¶

Array ¶

任意对象类型的通用序列，包括其他数组或字典（见下文）。数组可以动态调整大小。从索引开始对数组进行索引 0 . 从godot 2.1开始，索引可能是负数，就像在python中一样，从末尾开始计数。

var arr = []
arr = [1, 2, 3]
var b = arr[1] # This is 2.
var c = arr[arr.size() - 1] # This is 3.
var d = arr[-1] # Same as the previous line, but shorter.
arr[0] = "Hi!" # Replacing value 1 with "Hi!".
arr.append(4) # Array is now ["Hi!", 2, 3, 4].

gdscript数组在内存中线性分配以提高速度。然而，大型数组（超过数万个元素）可能会导致内存碎片。如果这是一个问题，可以使用特殊类型的数组。它们只接受一种数据类型。它们避免了内存碎片化，并且使用较少的内存，但是是原子的，并且运行速度比一般数组慢。因此，建议仅用于大型数据集：

PoolByteArray ：字节数组（0到255之间的整数）。
PoolIntArray ：整数数组。
PoolRealArray ：浮点数数组。
PoolStringArray ：字符串数组。
PoolVector2Array ：数组 Vector2 物体。
PoolVector3Array ：数组 Vector3 物体。
PoolColorArray ：数组 Color 物体。

Dictionary ¶

包含由唯一键引用的值的关联容器。

var d = {4: 5, "A key": "A value", 28: [1, 2, 3]}
d["Hi!"] = 0
d = {
    22: "value",
    "some_key": 2,
    "other_key": [2, 3, 4],
    "more_key": "Hello"
}

还支持Lua样式的表语法。Lua样式使用 = 而不是 : 并且不使用引号来标记字符串键（使其写起来稍微少一些）。但是请注意，与任何gdscript标识符一样，以该形式编写的键不能以数字开头。

var d = {
    test22 = "value",
    some_key = 2,
    other_key = [2, 3, 4],
    more_key = "Hello"
}

要将密钥添加到现有词典，请像访问现有密钥一样访问它并将其分配给它：

var d = {} # Create an empty Dictionary.
d.waiting = 14 # Add String "waiting" as a key and assign the value 14 to it.
d[4] = "hello" # Add integer 4 as a key and assign the String "hello" as its value.
d["Godot"] = 3.01 # Add String "Godot" as a key and assign the value 3.01 to it.

数据¶

变量¶

变量可以作为类成员或函数局部存在。它们是用 var 关键字和可以在初始化时（可选）分配一个值。

var a # Data type is 'null' by default.
var b = 5
var c = 3.8
var d = b + c # Variables are always initialized in order.

变量可以有选择地具有类型规范。当指定类型时，将强制变量始终具有相同的类型，并且尝试分配不兼容的值将引发错误。

在变量声明中使用 : （冒号）变量名后的符号，后跟类型。

var my_vector2: Vector2
var my_node: Node = Sprite.new()

如果在声明中初始化了变量，则可以推断类型，因此可以省略类型名称：：

var my_vector2 :=  Vector2() # 'my_vector2' is of type 'Vector2'
var my_node := Sprite.new() # 'my_node' is of type 'Sprite'

类型推断只有在分配的值具有定义的类型时才可能，否则它将引发错误。

有效类型为：

内置类型（数组、向量2、int、字符串等）
引擎类（节点、资源、引用等）
常量名（如果它们包含脚本资源） (MyScript 如果你声明 const MyScript = preload("res://my_script.gd") ）
同一脚本中的其他类，考虑范围 (InnerClass.NestedClass 如果你声明 class NestedClass 里面 class InnerClass 在同一范围内）
用声明的脚本类 class_name 关键字。

铸造¶

分配给类型化变量的值必须具有兼容的类型。如果需要将值强制为特定类型，特别是对象类型，则可以使用强制转换运算符 as .

如果值属于同一类型或属于转换类型的子类型，则对象类型之间的转换将导致相同的对象。

var my_node2D: Node2D
my_node2D = $Sprite as Node2D # Works since Sprite is a subtype of Node2D

如果该值不是子类型，则强制转换操作将导致 null 价值。

var my_node2D: Node2D
my_node2D = $Button # Results in 'null' since a Button is not a subtype of Node2D

对于内置类型，如果可能，它们将被强制转换，否则引擎将引发错误。

var my_int: int
my_int = "123" as int # The string can be converted to int
my_int = Vector2() as int # A Vector2 can't be converted to int, this will cause an error

当与树交互时，强制转换对于具有更好的类型安全变量也很有用：

# will infer the variable to be of type Sprite:
var my_sprite := $Character as Sprite

# will fail if $AnimPlayer is not an AnimationPlayer, even if it has the method 'play()':
($AnimPlayer as AnimationPlayer).play("walk")

常量¶

常量与变量类似，但必须是常量或常量表达式，并且必须在初始化时赋值。

const A = 5
const B = Vector2(20, 20)
const C = 10 + 20 # Constant expression.
const D = Vector2(20, 30).x # Constant expression: 20
const E = [1, 2, 3, 4][0] # Constant expression: 1
const F = sin(20) # sin() can be used in constant expressions.
const G = x + 20 # Invalid; this is not a constant expression!
const H = A + 20 # Constant expression: 25

虽然常量的类型是从指定的值推断出来的，但也可以添加显式的类型规范：

const A: int = 5
const B: Vector2 = Vector2()

指定不兼容类型的值将引发错误。

枚举类型¶

枚举基本上是常量的简写，如果要将连续整数赋给某个常量，它非常有用。

如果向枚举传递一个名称，它将把所有键放在该名称的常量字典中。

enum {TILE_BRICK, TILE_FLOOR, TILE_SPIKE, TILE_TELEPORT}
# Is the same as:
const TILE_BRICK = 0
const TILE_FLOOR = 1
const TILE_SPIKE = 2
const TILE_TELEPORT = 3

enum State {STATE_IDLE, STATE_JUMP = 5, STATE_SHOOT}
# Is the same as:
const State = {STATE_IDLE = 0, STATE_JUMP = 5, STATE_SHOOT = 6}
# Access values with State.STATE_IDLE, etc.

功能¶

函数始终属于 class . 变量查找的作用域优先级为：本地→类成员→全局。这个 self 变量始终可用，并作为访问类成员的选项提供，但并非总是必需的（并且应该 not 作为函数的第一个参数发送，与Python不同）。

func my_function(a, b):
    print(a)
    print(b)
    return a + b  # Return is optional; without it 'null' is returned.

函数可以 return 在任何时候。默认返回值为 null .

函数还可以具有参数和返回值的类型规范。参数的类型可以以类似于变量的方式添加：

func my_function(a: int, b: String):
    pass

如果函数参数具有默认值，则可以推断类型：：

func my_function(int_arg := 42, String_arg := "string"):
    pass

函数的返回类型可以在参数列表之后使用箭头标记指定 (-> ）：

func my_int_function() -> int:
    return 0

具有返回类型的函数 must 返回正确的值。将类型设置为 void 表示函数不返回任何内容。void函数可以在 return 关键字，但它们不能返回任何值。

void_function() -> void:
    return # Can't return a value

注解

非空函数必须总是返回一个值，因此如果代码有分支语句（例如 if/else 构造），所有可能的路径都必须有一个返回。例如，如果你有 return 里面 if 块而不是块之后，编辑器将引发一个错误，因为如果块没有执行，函数将没有有效的返回值。

引用函数¶

与python相反，函数是 not gdscript中的第一类对象。这意味着它们不能存储在变量中，不能作为参数传递给另一个函数，也不能从其他函数返回。这是出于性能原因。

要在运行时按名称引用一个函数（例如，将其存储在变量中，或将其作为参数传递给另一个函数），必须使用 call 或 funcref 帮助者：

# Call a function by name in one step.
my_node.call("my_function", args)

# Store a function reference.
var my_func = funcref(my_node, "my_function")
# Call stored function reference.
my_func.call_func(args)

记住默认函数，比如 _init 和大多数通知，例如 _enter_tree ， _exit_tree ， _process ， _physics_process 等在所有基类中自动调用。因此，在以某种方式重载函数时，只需要显式调用函数。

静态函数¶

函数不能声明为静态。当函数是静态的时，它不能访问实例成员变量，或者 self . 这主要用于创建助手函数库：

static func sum2(a, b):
    return a + b

报表和控制流¶

语句是标准的，可以是赋值、函数调用、控制流结构等（见下文）。 ; 作为语句分隔符是完全可选的。

如果/否则/elif¶

通过使用 if/else /`` elif``语法。允许在条件周围加括号，但不是必需的。考虑到基于制表符的缩进的性质， elif can be used instead of else/if 保持压痕的水平。

if [expression]:
    statement(s)
elif [expression]:
    statement(s)
else:
    statement(s)

短语句可以写在与条件相同的行上：

if 1 + 1 == 2: return 2 + 2
else:
    var x = 3 + 3
    return x

有时，您可能希望基于布尔表达式分配不同的初始值。在这种情况下，三元if表达式很有用：

var x = [value] if [expression] else [value]
y += 3 if y < 10 else -1

虽然¶

简单循环是通过使用 while 语法。可以使用 break 或继续使用 continue ：

while [expression]:
    statement(s)

对于¶

循环遍历一个范围，如数组或表， for 使用循环。迭代数组时，当前数组元素存储在循环变量中。当遍历字典时，指数存储在循环变量中。

for x in [5, 7, 11]:
    statement # Loop iterates 3 times with 'x' as 5, then 7 and finally 11.

var dict = {"a": 0, "b": 1, "c": 2}
for i in dict:
    print(dict[i])

for i in range(3):
    statement # Similar to [0, 1, 2] but does not allocate an array.

for i in range(1,3):
    statement # Similar to [1, 2] but does not allocate an array.

for i in range(2,8,2):
    statement # Similar to [2, 4, 6] but does not allocate an array.

for c in "Hello":
    print(c) # Iterate through all characters in a String, print every letter on new line.

比赛¶

A match 语句用于分支程序的执行。它相当于 switch 语句存在于许多其他语言中，但提供了一些附加功能。

基本语法：

match [expression]:
    [pattern](s):
        [block]
    [pattern](s):
        [block]
    [pattern](s):
        [block]

Crash-course for people who are familiar with switch statements ：

替换 switch 具有 match
去除 case
删除任何 break 如果你不想的话 break 默认情况下，您可以使用 continue 为了一次失败。
变化 default 到一个下划线。

控制流量 ：

图案从上到下匹配。如果模式匹配，将执行相应的块。之后，执行继续低于 match 声明。如果您想进行故障排除，可以使用 continue 停止当前块中的执行并检查其下面的块。

有6种模式类型：

恒定模式

常量原语，如数字和字符串：

match x:
    1:
        print("We are number one!")
    2:
        print("Two are better than one!")
    "test":
        print("Oh snap! It's a string!")

可变模式

匹配变量/枚举的内容：

match typeof(x):
    TYPE_REAL:
        print("float")
    TYPE_STRING:
        print("text")
    TYPE_ARRAY:
        print("array")

通配符模式

这个图案与所有东西都匹配。它是用一个下划线写的。

它可以用作 default 在一个 switch 其他语言的声明。：：

match x:
    1:
        print("It's one!")
    2:
        print("It's one times two!")
    _:
        print("It's not 1 or 2. I don't care tbh.")

装订图案

绑定模式引入一个新变量。与通配符模式一样，它匹配所有内容，并为该值命名。它在数组和字典模式中特别有用。：：

match x:
    1:
        print("It's one!")
    2:
        print("It's one times two!")
    var new_var:
        print("It's not 1 or 2, it's ", new_var)

阵列图案

匹配数组。数组模式的每一个元素都是模式本身，所以您可以嵌套它们。

首先测试数组的长度，它必须与模式大小相同，否则模式不匹配。

Open-ended array ：通过使最后一个子模式 ..

每个子模式必须用逗号分隔。：：

match x:
    []:
        print("Empty array")
    [1, 3, "test", null]:
        print("Very specific array")
    [var start, _, "test"]:
        print("First element is ", start, ", and the last is \"test\"")
    [42, ..]:
        print("Open ended array")

字典模式

工作方式与数组模式相同。每把钥匙都必须是一个固定的模式。

首先测试字典的大小，它必须与模式大小相同，否则模式不匹配。

Open-ended dictionary ：通过使最后一个子模式 ..

每个子模式必须用逗号分隔。

如果不指定值，则只检查键的存在。

值模式与键模式用 : ：：

match x:
    {}:
        print("Empty dict")
    {"name": "Dennis"}:
        print("The name is Dennis")
    {"name": "Dennis", "age": var age}:
        print("Dennis is ", age, " years old.")
    {"name", "age"}:
        print("Has a name and an age, but it's not Dennis :(")
    {"key": "godotisawesome", ..}:
        print("I only checked for one entry and ignored the rest")

多用户：

还可以指定由逗号分隔的多个模式。这些模式中不允许有任何绑定。：：

match x:
    1, 2, 3:
        print("It's 1 - 3")
    "Sword", "Splash potion", "Fist":
        print("Yep, you've taken damage")

Classes¶

默认情况下，所有脚本文件都是未命名的类。在这种情况下，只能使用文件路径引用它们，使用相对路径或绝对路径。例如，如果命名脚本文件 character.gd

# Inherit from Character.gd

extends res://path/to/character.gd

# Load character.gd and create a new node instance from it

var Character = load("res://path/to/character.gd")
var character_node = Character.new()

相反，您可以给类一个名称，以便在Godot的编辑器中将其注册为新类型。为此，请使用“classu name”关键字。您可以添加一个可选的逗号，后跟一个到图像的路径，以将其用作图标。然后，类将以其新图标出现在编辑器中：

# Item.gd

extends Node

class_name Item, "res://interface/icons/item.png"

../../../_images/class_name_editor_register_example.png

下面是一个类文件示例：

# Saved as a file named 'character.gd'.

class_name Character

var health = 5

func print_health():
    print(health)

func print_this_script_three_times():
    print(get_script())
    print(ResourceLoader.load("res://character.gd"))
    print(Character)

注解

Godot的类语法是紧凑的：它只能包含成员变量或函数。可以使用静态函数，但不能使用静态成员变量。同样，每次创建实例时，引擎都会初始化变量，这包括数组和字典。这符合线程安全的精神，因为脚本可以在单独的线程中初始化，而用户不知道。

遗传¶

类（存储为文件）可以从继承

全局类
另一个类文件
另一个类文件中的内部类。

不允许多重继承。

继承使用 extends 关键字：

# Inherit/extend a globally available class.
extends SomeClass

# Inherit/extend a named class file.
extends "somefile.gd"

# Inherit/extend an inner class in another file.
extends "somefile.gd".SomeInnerClass

要检查给定实例是否继承自给定类，请 is 可以使用关键字：

# Cache the enemy class.
const Enemy = preload("enemy.gd")

# [...]

# Use 'is' to check inheritance.
if (entity is Enemy):
    entity.apply_damage()

在中调用函数基类（即一个 extend-ed in your current class), prepend . 函数名：

.basefunc(args)

这一点特别有用，因为扩展类中的函数将替换其基类中同名的函数。所以如果你还想给他们打电话，你可以用 . 就像 super 其他语言的关键字：

func some_func(x):
    .some_func(x) # Calls same function on the parent class.

类构造函数¶

在类实例化时调用的类构造函数命名为 _init . 如前所述，继承类时会自动调用父类的构造函数。所以通常不需要打电话 ._init() 明确地。

与正则函数的调用不同，如上面的示例 .some_func ，如果继承类的构造函数接受参数，则按如下方式传递：

func _init(args).(parent_args):
   pass

这可以通过例子得到更好的解释。假设我们有这样的场景：

# State.gd (inherited class)
var entity = null
var message = null

func _init(e=null):
    entity = e

func enter(m):
    message = m


# Idle.gd (inheriting class)
extends "State.gd"

func _init(e=null, m=null).(e):
    # Do something with 'e'.
    message = m

这里有几点需要牢记：

如果继承的类 (State.gd ）定义 _init 接受参数的构造函数 (e 在本例中），然后是继承类 (Idle.gd ） has 定义 _init 并将适当的参数传递给 _init 从 State.gd
Idle.gd can have a different number of arguments than the base class State.gd
在上面的例子中， e 传递给 State.gd 构造函数相同 e 传给 Idle.gd
如果 Idle.gd 的 _init 构造函数接受0个参数，它仍然需要向 State.gd 基类，即使它什么也不做。这让我们了解到，您也可以在基本构造函数中传递文本，而不仅仅是变量。如。：

# Idle.gd

func _init().(5):
    pass

内部类¶

类文件可以包含内部类。内部类是使用 class 关键字。它们是使用 ClassName.new() 功能。

# Inside a class file.

# An inner class in this class file.
class SomeInnerClass:
    var a = 5
    func print_value_of_a():
        print(a)

# This is the constructor of the class file's main class.
func _init():
    var c = SomeInnerClass.new()
    c.print_value_of_a()

类作为资源¶

存储为文件的类被视为 resources . 必须从磁盘加载它们才能在其他类中访问它们。这可以使用 load 或 preload 功能（见下文）。通过调用 new 类对象上的函数：

# Load the class resource when calling load().
var my_class = load("myclass.gd")

# Preload the class only once at compile time.
const MyClass = preload("myclass.gd")

func _init():
    var a = MyClass.new()
    a.some_function()

出口¶

类成员可以导出。这意味着它们的值将与资源一起保存（例如 scene ）他们依附于。它们也可以在属性编辑器中进行编辑。通过使用 export 关键词：

extends Button

export var number = 5 # Value will be saved and visible in the property editor.

导出的变量必须初始化为常量表达式或具有export关键字参数形式的export提示（请参见下文）。

导出成员变量的一个基本好处是让它们在编辑器中可见和可编辑。通过这种方式，艺术家和游戏设计者可以修改后来影响程序运行方式的值。为此，提供了一种特殊的导出语法。

# If the exported value assigns a constant or constant expression,
# the type will be inferred and used in the editor.

export var number = 5

# Export can take a basic data type as an argument, which will be
# used in the editor.

export(int) var number

# Export can also take a resource type to use as a hint.

export(Texture) var character_face
export(PackedScene) var scene_file
# There are many resource types that can be used this way, try e.g.
# the following to list them:
export(Resource) var resource

# Integers and strings hint enumerated values.

# Editor will enumerate as 0, 1 and 2.
export(int, "Warrior", "Magician", "Thief") var character_class
# Editor will enumerate with string names.
export(String, "Rebecca", "Mary", "Leah") var character_name

# Named Enum Values

# Editor will enumerate as THING_1, THING_2, ANOTHER_THING.
enum NamedEnum {THING_1, THING_2, ANOTHER_THING = -1}
export (NamedEnum) var x

# Strings as Paths

# String is a path to a file.
export(String, FILE) var f
# String is a path to a directory.
export(String, DIR) var f
# String is a path to a file, custom filter provided as hint.
export(String, FILE, "*.txt") var f

# Using paths in the global filesystem is also possible,
# but only in tool scripts (see further below).

# String is a path to a PNG file in the global filesystem.
export(String, FILE, GLOBAL, "*.png") var tool_image
# String is a path to a directory in the global filesystem.
export(String, DIR, GLOBAL) var tool_dir

# The MULTILINE setting tells the editor to show a large input
# field for editing over multiple lines.
export(String, MULTILINE) var text

# Limiting editor input ranges

# Allow integer values from 0 to 20.
export(int, 20) var i
# Allow integer values from -10 to 20.
export(int, -10, 20) var j
# Allow floats from -10 to 20, with a step of 0.2.
export(float, -10, 20, 0.2) var k
# Allow values y = exp(x) where y varies between 100 and 1000
# while snapping to steps of 20. The editor will present a
# slider for easily editing the value.
export(float, EXP, 100, 1000, 20) var l

# Floats with Easing Hint

# Display a visual representation of the ease() function
# when editing.
export(float, EASE) var transition_speed

# Colors

# Color given as Red-Green-Blue value
export(Color, RGB) var col # Color is RGB.
# Color given as Red-Green-Blue-Alpha value
export(Color, RGBA) var col # Color is RGBA.

# Another node in the scene can be exported, too.

export(NodePath) var node

必须注意的是，即使在编辑器中不运行脚本，导出的属性仍然是可编辑的（参见下面的“工具”）。

导出位标志¶

用作位标志的整数可以存储多个 true/false （布尔）一个属性中的值。通过使用export提示 int, FLAGS ，可以从编辑器中设置：

# Individually edit the bits of an integer.
export(int, FLAGS) var spell_elements = ELEMENT_WIND | ELEMENT_WATER

也可以将标志限制为一定数量的命名标志。语法类似于枚举语法：

# Set any of the given flags from the editor.
export(int, FLAGS, "Fire", "Water", "Earth", "Wind") var spell_elements = 0

在这个例子中， Fire 值为1， Water 值为2， Earth 具有值4和 Wind 对应值8。通常，应相应地定义常量（例如 const ELEMENT_WIND = 8 等等。

使用位标志需要对位操作有一些了解。如果有疑问，应改为导出布尔变量。

导出数组¶

导出数组是可行的，但有一个重要的警告：虽然常规数组是在每个类实例的本地创建的，但导出的数组是共享在所有实例之间。这意味着在一个实例中编辑它们将导致它们在所有其他实例中发生更改。导出的数组可以有初始值设定项，但它们必须是常量表达式。

# Exported array, shared between all instances.
# Default value must be a constant expression.

export var a = [1, 2, 3]

# Exported arrays can specify type (using the same hints as before).

export(Array, int) var ints = [1,2,3]
export(Array, int, "Red", "Green", "Blue") var enums = [2, 1, 0]
export(Array, Array, float) var two_dimensional = [[1.0, 2.0], [3.0, 4.0]]

# You can omit the default value, but then it would be null if not assigned.

export(Array) var b
export(Array, PackedScene) var scenes

# Typed arrays also work, only initialized empty:

export var vector3s = PoolVector3Array()
export var strings = PoolStringArray()

# Regular array, created local for every instance.
# Default value can include run-time values, but can't
# be exported.

var c = [a, 2, 3]

设置器/获取器¶

无论什么原因，了解类的成员变量何时更改通常都很有用。还可能需要以某种方式封装其访问。

为此，gdscript提供了 setter/getter 语法使用 setget 关键字。它直接在变量定义之后使用：

var variable = value setget setterfunc, getterfunc

每当 variable 由修改 外部的 源（即，不是来自类中的本地用法），即 设定器 功能 (setterfunc 以上）将被调用。这发生了之前值已更改。这个 设定器 必须决定如何处理新值。反之亦然，当 variable 被访问， 吸气剂 功能 (getterfunc 以上）必须 return 所需的值。下面是一个例子：

var myvar setget my_var_set, my_var_get

func my_var_set(new_value):
    my_var = new_value

func my_var_get():
    return my_var # Getter must return a value.

任何一个 设定器 或 吸气剂 功能可以省略：

# Only a setter.
var my_var = 5 setget myvar_set
# Only a getter (note the comma).
var my_var = 5 setget ,myvar_get

当在工具脚本或插件中将变量导出到编辑器以验证输入时，get/setter尤其有用。

如前所述， 地方的 访问将 not 触发setter和getter。这是一个例子：

func _init():
    # Does not trigger setter/getter.
    my_integer = 5
    print(my_integer)

    # Does trigger setter/getter.
    self.my_integer = 5
    print(self.my_integer)

刀具模式¶

默认情况下，脚本不会在编辑器中运行，并且只能更改导出的属性。在某些情况下，需要在编辑器中运行它们（只要它们不执行游戏代码或手动避免这样做）。为此， tool 关键字存在，必须放在文件的顶部：

tool
extends Button

func _ready():
    print("Hello")

警告

释放节点时要小心 queue_free() 或 free() 在工具脚本中（尤其是脚本的所有者本身）。当工具脚本在编辑器中运行它们的代码时，误用它们可能会导致编辑器崩溃。

内存管理¶

如果类继承自参考文献，则实例将在不再使用时释放。不存在垃圾收集器，只存在引用计数。默认情况下，所有不定义继承的类都会扩展 参考文献 . 如果不需要这样做，则类必须继承对象必须手动调用instance.free（）。为了避免无法释放的引用循环，请 weakref 函数用于创建弱引用。

或者，当不使用引用时， is_instance_valid(instance) 可用于检查对象是否已释放。

信号¶

信号是一种工具，用于从其他对象可以响应的对象发出消息。要为类创建自定义信号，请使用 signal 关键字。

extends Node

# A signal named health_depleted
signal health_depleted

注解

信号是一个 Callback 机制。它们还充当观察者的角色，这是一种常见的编程模式。有关详细信息，请阅读 Observer tutorial 在游戏编程模式电子书中。

您可以像连接节点的内置信号一样将这些信号连接到方法纽扣或 RigidBody .

在下面的示例中，我们将 health_depleted 来自A的信号 Character 节点到 Game 节点。当 Character 节点发出信号，游戏节点的 _on_Character_health_depleted 被称为：

# Game.gd

func _ready():
   var character_node = get_node('Character')
   character_node.connect("health_depleted", self, "_on_Character_health_depleted")

func _on_Character_health_depleted():
   get_tree().reload_current_scene()

您可以随信号发出任意数量的参数。

这是一个很有用的例子。比如说，我们希望屏幕上有一个生命条，用动画来响应健康状况的变化，但是我们希望用户界面与场景树中的播放器分开。

在我们 Character.gd 脚本，我们定义 health_changed 发出信号 Object.emit_signal() ，并且来自 Game 节点在场景树的上方，我们将其连接到 Lifebar 使用 Object.connect() 方法：

# Character.gd

...
signal health_changed

func take_damage(amount):
    var old_health = health
    health -= amount

    # We emit the health_changed signal every time the
    # character takes damage
    emit_signal("health_changed", old_health, health)
...

# Lifebar.gd

# Here, we define a function to use as a callback when the
# character's health_changed signal is emitted

...
func _on_Character_health_changed(old_value, new_value):
    if old_value > new_value:
        progress_bar.modulate = Color.red
    else:
        progress_bar.modulate = Color.green

    # Imagine that `animate` is a user-defined function that animates the
    # bar filling up or emptying itself
    progress_bar.animate(old_value, new_value)
...

注解

要使用信号，您的类必须扩展 Object 类或扩展它的任何类型 Node ， KinematicBody ， Control …

在 Game 节点，我们得到 Character 和 Lifebar 节点，然后将发出信号的字符连接到接收器， Lifebar 在本例中是节点。

# Game.gd

func _ready():
   var character_node = get_node('Character')
   var lifebar_node = get_node('UserInterface/Lifebar')

   character_node.connect("health_changed", lifebar_node, "_on_Character_health_changed")

这允许 Lifebar 对健康变化做出反应而不将其与 Character 节点。

您可以在信号定义后的括号中写入可选参数名。

# Defining a signal that forwards two arguments
signal health_changed(old_value, new_value)

这些参数出现在编辑器的node dock中，godot可以使用它们为您生成回调函数。但是，在发出信号时，仍然可以发出任意数量的参数。因此，由您来发出正确的值。

../../../_images/gdscript_basics_signals_node_tab_1.png

gdscript可以将值数组绑定到信号和方法之间的连接。发出信号时，回调方法接收绑定值。这些绑定参数对于每个连接都是唯一的，并且值将保持不变。

如果发出的信号本身不允许您访问所需的所有数据，则可以使用此值数组向连接添加额外的常量信息。

在上面的例子基础上，假设我们想要显示屏幕上每个字符所受到的伤害的日志，比如 Player1 took 22 damage. . 这个 health_changed 信号没有告诉我们造成伤害的角色的名字。因此，当我们将信号连接到游戏中的控制台时，我们可以在binds array参数中添加字符的名称：

# Game.gd

func _ready():
   var character_node = get_node('Character')
   var battle_log_node = get_node('UserInterface/BattleLog')

   character_node.connect("health_changed", battle_log_node, "_on_Character_health_changed", [character_node.name])

我们的 BattleLog 节点将绑定数组中的每个元素作为额外参数接收：

# BattleLog.gd

func _on_Character_health_changed(old_value, new_value, character_name):
   if not new_value <= old_value:
      return
   var damage = old_value - new_value
   label.text += character_name + " took " + str(damage) + " damage."

有产量的协胞体¶

gdscript支持 coroutines 通过 yield 内置功能。打电话 yield() 将立即从当前函数返回，当前冻结状态与返回值相同。打电话 resume 在此结果上，对象将继续执行并返回函数返回的任何内容。一旦恢复，状态对象将变为无效。下面是一个例子：

func my_func():
   print("Hello")
   yield()
   print("world")

func _ready():
    var y = my_func()
    # Function state saved in 'y'.
    print("my dear")
    y.resume()
    # 'y' resumed and is now an invalid state.

将打印：

Hello
my dear
world

还可以在yield（）和resume（）之间传递值，例如：

func my_func():
   print("Hello")
   print(yield())
   return "cheers!"

func _ready():
    var y = my_func()
    # Function state saved in 'y'.
    print(y.resume("world"))
    # 'y' resumed and is now an invalid state.

将打印：

Hello
world
cheers!

协程和信号¶

使用的真正力量 yield 与信号结合时。 yield 可以接受两个参数，一个对象和一个信号。收到信号后，执行将重新开始。以下是一些例子：

# Resume execution the next frame.
yield(get_tree(), "idle_frame")

# Resume execution when animation is done playing.
yield(get_node("AnimationPlayer"), "finished")

# Wait 5 seconds, then resume execution.
yield(get_tree().create_timer(5.0), "timeout")

协同作战人员自己使用 completed 当它们转换为无效状态时发出信号，例如：

func my_func():
    yield(button_func(), "completed")
    print("All buttons were pressed, hurray!")

func button_func():
    yield($Button0, "pressed")
    yield($Button1, "pressed")

my_func 只有在两个按钮都按下后才能继续执行。

onready关键字¶

使用节点时，通常希望保持对变量中部分场景的引用。由于场景只有在进入活动场景树时才有权进行配置，因此只有在调用节点时才能获取子节点。_ready（）。

var my_label

func _ready():
    my_label = get_node("MyLabel")

这可能会有点麻烦，尤其是当节点和外部引用堆积时。为此，gdscript具有 onready 关键字，将成员变量的初始化延迟到调用就绪为止。它可以用一行代码替换上述代码：

onready var my_label = get_node("MyLabel")

断言关键字¶

这个 assert 关键字可用于检查调试生成中的条件。这些断言在非调试版本中被忽略。

# Check that 'i' is 0.
assert(i == 0)