GDScript 导出

导出简介

在Godot中,可以导出类成员。这意味着它们的值会与它们所附加的资源(例如 scene)一起保存。它们也可以在属性编辑器中进行编辑。导出使用关键字 export 来完成:

extends Button

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

export 关键字后,导出的变量必须初始化为常量表达式,或者具有使用的参数形式的导出提示(请参见下面的 示例 部分)。

导出成员变量的基本好处之一是使它们在编辑器中可见并可编辑。这样,美术师和游戏设计师可以修改值,这些值以后会影响程序的运行方式。为此,提供了一种特殊的导出语法。

注解

导出属性也可以使用其他语言(例如C#)来完成。语法因语言而异。

示例

# 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 scripts in "tool" mode.

# 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 and snap the value to multiples 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 (alpha will always be 1).
export(Color, RGB) var col
# Color given as red-green-blue-alpha value.
export(Color, RGBA) var col

# Nodes

# Another node in the scene can be exported as a NodePath.
export(NodePath) var node_path
# Do take note that the node itself isn't being exported -
# there is one more step to call the true node:
var node = get_node(node_path)

# Resources

export(Resource) var resource
# In the Inspector, you can then drag and drop a resource file
# from the FileSystem dock into the variable slot.

# Opening the inspector dropdown may result in an
# extremely long list of possible classes to create, however.
# Therefore, if you specify an extension of Resource such as:
export(AnimationNode) var resource
# The drop-down menu will be limited to AnimationNode and all
# its inherited classes.

必须注意,即使在编辑器中未运行脚本,导出的属性仍可编辑。可以与 使用工具模式的脚本 结合使用。

导出位标志

Integers used as bit flags can store multiple true/false (boolean) values in one property. By using the export hint int, FLAGS, ..., they can be set from the editor:

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

You must provide a string description for each flag. In this example, Fire has value 1, Water has value 2, Earth has value 4 and Wind corresponds to value 8. Usually, constants should be defined accordingly (e.g. const ELEMENT_WIND = 8 and so on).

Export hints are also provided for the physics and render layers defined in the project settings:

export(int, LAYERS_2D_PHYSICS) var layers_2d_physics
export(int, LAYERS_2D_RENDER) var layers_2d_render
export(int, LAYERS_3D_PHYSICS) var layers_3d_physics
export(int, LAYERS_3D_RENDER) var layers_3d_render

Using bit flags requires some understanding of bitwise operations. If in doubt, use boolean variables instead.

导出数组

Exported arrays can have initializers, but they must be constant expressions.

If the exported array specifies a type which inherits from Resource, the array values can be set in the inspector by dragging and dropping multiple files from the FileSystem dock at once.

# 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

# Arrays with specified types which inherit from resource can be set by
# drag-and-dropping multiple files from the FileSystem dock.

export(Array, Texture) var textures
export(Array, PackedScene) var scenes

# Typed arrays also work, only initialized empty:

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

# Default value can include run-time values, but can't
# be exported.

var c = [a, 2, 3]

Setting exported variables from a tool script

工具模式 下的脚本中,更改一个导出变量的值时,属性检查器中对应的值不会自动更新。要更新它,请在设置导出变量的值之后,调用 property_list_changed_notify()

Advanced exports

为了避免不必要的复杂设计,不是所有导出类型都在语言层面上提供。下面将说明一些能用底层API实现的,较为常见的导出方法。

在继续阅读之前,你应该了解引擎是如何处理属性的,以及如何用 _set()_get(),以及 _get_property_list() 方法来自定义属性。详情可参阅 从对象访问数据或逻辑

参见

要用上述方法绑定属性,参阅 使用 _set/_get/_get_property_list 绑定属性

警告

脚本必须在 tool 模式运行,上述方法才能在编辑器内运行。

Adding script categories

为了在视觉上更好区分各个属性,可以将特殊的脚本分类作为作为分割线嵌入编辑器。Script Variables 就是一种内建分类。

func _get_property_list():
    var properties = []
    properties.append(
        {
            name = "Debug",
            type = TYPE_NIL,
            usage = PROPERTY_USAGE_CATEGORY | PROPERTY_USAGE_SCRIPT_VARIABLE
        }
    )
    return properties
  • name 是要加入属性面板中的分类的名字;
  • PROPERTY_USAGE_CATEGORY 表明了该属性应被视为一个脚本分类,因此可以忽略 TYPE_NIL 这个类型,因为它其实并没有被脚本逻辑所处理。但无论如何,你还是要在这儿定义它。

Grouping properties

名称类似的属性们可以添加为一组。

func _get_property_list():
    var properties = []
    properties.append({
            name = "Rotate",
            type = TYPE_NIL,
            hint_string = "rotate_",
            usage = PROPERTY_USAGE_GROUP | PROPERTY_USAGE_SCRIPT_VARIABLE
    })
    return properties
  • name 是包含了一组属性的可折叠群组的名称;
  • 接下来所有新增的属性都会被放在该群组中,通过 hint_string 字典键定义为可折叠,并以其为前缀缩写名称。例如,本例中的``rotate_speed`` 将会被缩写为 speed
  • PROPERTY_USAGE_GROUP 表明了该属性应被视为一个脚本分类,因此可以忽略 TYPE_NIL 这个类型,因为它其实并没有被脚本逻辑所处理。但无论如何,你还是要在这儿定义它。