GDScript 导出

导出简介

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

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

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

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

注解

Exporting properties can also be done in other languages such as C#. The syntax varies depending on the language.

示例

  1. # If the exported value assigns a constant or constant expression,
  2. # the type will be inferred and used in the editor.
  4. export var number = 5
  6. # Export can take a basic data type as an argument, which will be
  7. # used in the editor.
  9. export(int) var number
  11. # Export can also take a resource type to use as a hint.
  13. export(Texture) var character_face
  14. export(PackedScene) var scene_file
  15. # There are many resource types that can be used this way, try e.g.
  16. # the following to list them:
  17. export(Resource) var resource
  19. # Integers and strings hint enumerated values.
  21. # Editor will enumerate as 0, 1 and 2.
  22. export(int, "Warrior", "Magician", "Thief") var character_class
  23. # Editor will enumerate with string names.
  24. export(String, "Rebecca", "Mary", "Leah") var character_name
  26. # Named enum values
  28. # Editor will enumerate as THING_1, THING_2, ANOTHER_THING.
  29. enum NamedEnum {THING_1, THING_2, ANOTHER_THING = -1}
  30. export(NamedEnum) var x
  32. # Strings as paths
  34. # String is a path to a file.
  35. export(String, FILE) var f
  36. # String is a path to a directory.
  37. export(String, DIR) var f
  38. # String is a path to a file, custom filter provided as hint.
  39. export(String, FILE, "*.txt") var f
  41. # Using paths in the global filesystem is also possible,
  42. # but only in scripts in "tool" mode.
  44. # String is a path to a PNG file in the global filesystem.
  45. export(String, FILE, GLOBAL, "*.png") var tool_image
  46. # String is a path to a directory in the global filesystem.
  47. export(String, DIR, GLOBAL) var tool_dir
  49. # The MULTILINE setting tells the editor to show a large input
  50. # field for editing over multiple lines.
  51. export(String, MULTILINE) var text
  53. # Limiting editor input ranges
  55. # Allow integer values from 0 to 20.
  56. export(int, 20) var i
  57. # Allow integer values from -10 to 20.
  58. export(int, -10, 20) var j
  59. # Allow floats from -10 to 20 and snap the value to multiples of 0.2.
  60. export(float, -10, 20, 0.2) var k
  61. # Allow values 'y = exp(x)' where 'y' varies between 100 and 1000
  62. # while snapping to steps of 20. The editor will present a
  63. # slider for easily editing the value.
  64. export(float, EXP, 100, 1000, 20) var l
  66. # Floats with easing hint
  68. # Display a visual representation of the 'ease()' function
  69. # when editing.
  70. export(float, EASE) var transition_speed
  72. # Colors
  74. # Color given as red-green-blue value (alpha will always be 1).
  75. export(Color, RGB) var col
  76. # Color given as red-green-blue-alpha value.
  77. export(Color, RGBA) var col
  79. # Nodes
  81. # Another node in the scene can be exported as a NodePath.
  82. export(NodePath) var node_path
  83. # Do take note that the node itself isn't being exported -
  84. # there is one more step to call the true node:
  85. var node = get_node(node_path)
  87. # Resources
  89. export(Resource) var resource
  90. # In the Inspector, you can then drag and drop a resource file
  91. # from the FileSystem dock into the variable slot.
  93. # Opening the inspector dropdown may result in an
  94. # extremely long list of possible classes to create, however.
  95. # Therefore, if you specify an extension of Resource such as:
  96. export(AnimationNode) var resource
  97. # The drop-down menu will be limited to AnimationNode and all
  98. # its inherited classes.

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

导出位标志

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

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

你必须为每个标志提供一个字符串描述. 在这个例子中, 火(Fire) 的值是1, 水(Water) 的值是2, 土(Earth) 的值是4, 风(Wind) 对应的值是8. 通常, 应相应地定义常量(例如 const ELEMENT_WIND = 8 等等).

也可以为项目设置中定义的物理层和渲染层提供导出提示：

  1. export(int, LAYERS_2D_PHYSICS) var layers_2d_physics
  2. export(int, LAYERS_2D_RENDER) var layers_2d_render
  3. export(int, LAYERS_3D_PHYSICS) var layers_3d_physics
  4. export(int, LAYERS_3D_RENDER) var layers_3d_render

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

导出数组

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

如果导出的数组指定了从Resource继承的类型, 则可以通过一次从FileSystem扩展坞中拖放多个文件来在检查器中设置数组值.

  1. # Default value must be a constant expression.
  3. export var a = [1, 2, 3]
  5. # Exported arrays can specify type (using the same hints as before).
  7. export(Array, int) var ints = [1, 2, 3]
  8. export(Array, int, "Red", "Green", "Blue") var enums = [2, 1, 0]
  9. export(Array, Array, float) var two_dimensional = [[1.0, 2.0], [3.0, 4.0]]
  11. # You can omit the default value, but then it would be null if not assigned.
  13. export(Array) var b
  14. export(Array, PackedScene) var scenes
  16. # Arrays with specified types which inherit from resource can be set by
  17. # drag-and-dropping multiple files from the FileSystem dock.
  19. export(Array, Texture) var textures
  20. export(Array, PackedScene) var scenes
  22. # Typed arrays also work, only initialized empty:
  24. export var vector3s = PoolVector3Array()
  25. export var strings = PoolStringArray()
  27. # Default value can include run-time values, but can't
  28. # be exported.
  30. var c = [a, 2, 3]

从工具脚本设置导出变量

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

导出进阶

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

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

参见

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

警告

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

对脚本中的属性添加类别

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

  1. func _get_property_list():
  2.     var properties = []
  3.     properties.append(
  4.         {
  5.             name = "Debug",
  6.             type = TYPE_NIL,
  7.             usage = PROPERTY_USAGE_CATEGORY | PROPERTY_USAGE_SCRIPT_VARIABLE
  8.         }
  9.     )
  10.     return properties

  • name 是要加入属性面板中的分类的名字;

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

对属性进行分组

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

  1. func _get_property_list():
  2.     var properties = []
  3.     properties.append({
  4.             name = "Rotate",
  5.             type = TYPE_NIL,
  6.             hint_string = "rotate_",
  7.             usage = PROPERTY_USAGE_GROUP | PROPERTY_USAGE_SCRIPT_VARIABLE
  8.     })
  9.     return properties

  • name 是包含了一组属性的可折叠群组的名称;

  • 接下来所有新增的属性都会被放在该群组中, 通过 hint_string 字典键定义为可折叠, 并以其为前缀缩写名称. 例如, 本例中的 rotate_speed 将会被缩写为 speed.

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