GDScript 导出

导出简介

在 Godot 中可以导出类成员。这意味着它们的值会与它们所附加的资源(例如场景)一起保存。它们也可以在属性编辑器中进行编辑。导出使用关键字 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:
onready 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, ...,可以在编辑器中设置它们:

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

使用位标志需要对位操作有一定的了解. 如果有疑问, 请使用布尔变量代替.

导出数组

导出的数组可以具有初始化器, 但是它们必须是常量表达式.

如果导出的数组指定了从 Resource 继承的类型,则可以通过一次从文件系统面板中拖放多个文件来在检查器中设置数组值。

# 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]

从工具脚本设置导出变量

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

导出进阶

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

在进一步阅读前,你需要熟悉属性的运作方式以及它们是如何通过 _set()_get()_get_property_list() 方法进行定制的。详情可参阅 从对象访问数据或逻辑

参见

要在 C++ 中用上述方法绑定属性,请参阅 使用 _set/_get/_get_property_list 绑定属性

警告

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

属性

To understand how to better use the sections below, you should understand how to make properties with advanced exports.

func _get_property_list():
    var properties = []
    # Same as "export(int) var my_property"
    properties.append({
        name = "my_property",
        type = TYPE_INT
    })
    return properties
  • The _get_property_list() function gets called by the inspector. You can override it for more advanced exports. You must return an Array with the contents of the properties for the function to work.

  • name is the name of the property

  • type is the type of the property from Variant.Type.

备注

The float type is called a real (TYPE_REAL) in the Variant.Type enum.

Attaching variables to properties

To attach variables to properties (allowing the value of the property to be used in scripts), you need to create a variable with the exact same name as the property or else you may need to override the _set() and _get() methods. Attaching a variable to to a property also gives you the ability to give it a default state.

# This variable is determined by the function below.
# This variable acts just like a regular gdscript export.
var my_property = 5

func _get_property_list():
    var properties = []
    # Same as "export(int) var my_property"
    properties.append({
        name = "my_property",
        type = TYPE_INT
    })
    return properties

对脚本中的属性添加类别

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
    })

    # Example of adding a property to the script category
    properties.append({
        name = "Logging_Enabled",
        type = TYPE_BOOL
    })
    return properties
  • name 是要加入检查器中的分类的名字;

  • Every following property added after the category definition will be a part of the category.

  • PROPERTY_USAGE_CATEGORY 表明了该属性应被视为一个脚本分类, 因此可以忽略 TYPE_NIL 这个类型, 因为它其实并没有被脚本逻辑所处理. 但无论如何, 你还是要在这儿定义它.

对属性进行分组

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
    })

    # Example of adding to the group
    properties.append({
        name = "rotate_speed",
        type = TYPE_REAL
    })

    # This property won't get added to the group
    # due to not having the "rotate_" prefix.
    properties.append({
        name = "trail_color",
        type = TYPE_COLOR
    })
    return properties
  • name 是包含了一组属性的可折叠群组的名称;

  • Every following property added after the group property with the prefix (which determined by hint_string) will be shortened. For instance, rotate_speed is going to be shortened to speed in this case. However, movement_speed won't be a part of the group and will not be shortened.

  • PROPERTY_USAGE_GROUP 表明了该属性应被视为一个脚本分类, 因此可以忽略 TYPE_NIL 这个类型, 因为它其实并没有被脚本逻辑所处理. 但无论如何, 你还是要在这儿定义它.