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.

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

导出位标志

用作位标志的整数可以在一个属性中存储多个 true/false``(布尔值)值。通过使用导出提示 ``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 等)。

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

使用位标志需要了解位操作。如果有疑问,应该导出布尔变量。

导出数组

导出数组是可行的,但有一个重要的注意事项:尽管每个类实例都是创建局部的常规数组,但是导出的数组在所有实例之间都是 共享的。这意味着在一个实例中对其进行编辑将导致它们在所有其他实例中进行更改。导出的数组可以具有初始化器,但是它们必须是常量表达式。

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.

# 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

# 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()

# Regular array, created local for every instance.
# 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

Not every type of export can be provided on the level of the language itself to avoid unnecessary design complexity. The following describes some more or less common exporting features which can be implemented with a low-level API.

Before reading further, you should get familiar with the way properties are handled and how they can be customized with _set(), _get(), and _get_property_list() methods as described in 从对象访问数据或逻辑.

参见

For binding properties using the above methods in C++, see 使用 _set/_get/_get_property_list 绑定属性.

警告

The script must operate in the tool mode so the above methods can work from within the editor.

Adding script categories

For better visual distinguishing of properties, a special script category can be embedded into the inspector to act as a separator. Script Variables is one example of a built-in category.

func _get_property_list():
    var properties = []
    properties.append(
        {
            name = "Debug",
            type = TYPE_NIL,
            usage = PROPERTY_USAGE_CATEGORY | PROPERTY_USAGE_SCRIPT_VARIABLE
        }
    )
    return properties
  • name is the name of a category to be added to the inspector;
  • PROPERTY_USAGE_CATEGORY indicates that the property should be treated as a script category specifically, so the type TYPE_NIL can be ignored as it won't be actually used for the scripting logic, yet it must be defined anyway.

Grouping properties

A list of properties with similar names can be grouped.

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 is the name of a group which is going to be displayed as collapsible list of properties;
  • every successive property added after the group property will be collapsed and shortened as determined by the prefix defined via the hint_string key. For instance, rotate_speed is going to be shortened to speed in this case.
  • PROPERTY_USAGE_GROUP indicates that the property should be treated as a script group specifically, so the type TYPE_NIL can be ignored as it won't be actually used for the scripting logic, yet it must be defined anyway.