Godot接口

通常,需要依赖于功能的其他对象的脚本.这个过程分为两部分:

  1. 获取对可能具有这些功能的对象的引用.

  2. 从对象访问数据或逻辑.

本教程的其余部分,概述了完成所有这些操作的各种方法.

获取对象引用

对所有 Object 来说,引用它们最基本的方法,是从另一个获取的实例中,获取对现有对象的引用.

GDScript

C#

  1. var obj = node.object # Property access.
  2. var obj = node.get_object() # Method access.
  1. Object obj = node.Object; // Property access.
  2. Object obj = node.GetObject(); // Method access.

同样的原则也适用于 Reference 对象.虽然用户经常以这种方式访问 NodeResource,还可以采取其他措施.

代替属性或方法访问,可以通过加载访问获得 Resource.

GDScript

C#

  1. var preres = preload(path) # Load resource during scene load
  2. var res = load(path) # Load resource when program reaches statement
  3. # Note that users load scenes and scripts, by convention, with PascalCase
  4. # names (like typenames), often into constants.
  5. const MyScene : = preload("my_scene.tscn") as PackedScene # Static load
  6. const MyScript : = preload("my_script.gd") as Script
  7. # This type's value varies, i.e. it is a variable, so it uses snake_case.
  8. export(Script) var script_type: Script
  9. # If need an "export const var" (which doesn't exist), use a conditional
  10. # setter for a tool script that checks if it's executing in the editor.
  11. tool # Must place at top of file.
  12. # Must configure from the editor, defaults to null.
  13. export(Script) var const_script setget set_const_script
  14. func set_const_script(value):
  15. if Engine.is_editor_hint():
  16. const_script = value
  17. # Warn users if the value hasn't been set.
  18. func _get_configuration_warning():
  19. if not const_script:
  20. return "Must initialize property 'const_script'."
  21. return ""
  1. // Tool script added for the sake of the "const [Export]" example.
  2. [Tool]
  3. public MyType
  4. {
  5. // Property initializations load during Script instancing, i.e. .new().
  6. // No "preload" loads during scene load exists in C#.
  7. // Initialize with a value. Editable at runtime.
  8. public Script MyScript = GD.Load<Script>("MyScript.cs");
  9. // Initialize with same value. Value cannot be changed.
  10. public readonly Script MyConstScript = GD.Load<Script>("MyScript.cs");
  11. // Like 'readonly' due to inaccessible setter.
  12. // But, value can be set during constructor, i.e. MyType().
  13. public Script Library { get; } = GD.Load<Script>("res://addons/plugin/library.gd");
  14. // If need a "const [Export]" (which doesn't exist), use a
  15. // conditional setter for a tool script that checks if it's executing
  16. // in the editor.
  17. private PackedScene _enemyScn;
  18. [Export]
  19. public PackedScene EnemyScn
  20. {
  21. get { return _enemyScn; }
  22. set
  23. {
  24. if (Engine.IsEditorHint())
  25. {
  26. _enemyScn = value;
  27. }
  28. }
  29. };
  30. // Warn users if the value hasn't been set.
  31. public String _GetConfigurationWarning()
  32. {
  33. if (EnemyScn == null)
  34. return "Must initialize property 'EnemyScn'.";
  35. return "";
  36. }
  37. }

请注意以下几点:

  1. 一种语言可以通过多种方式加载这些资源.

  2. 在设计对象如何访问数据时,不要忘记,还可以将资源作为引用传递.

  3. 请记住,加载资源将获取引擎维护的缓存资源实例.要获取一个新对象,必须 复制 一个现有引用,或者使用 new() 从头实例化一个引用.

节点也有一个可选的访问点:场景树.

GDScript

C#

  1. extends Node
  2. # Slow.
  3. func dynamic_lookup_with_dynamic_nodepath():
  4. print(get_node("Child"))
  5. # Faster. GDScript only.
  6. func dynamic_lookup_with_cached_nodepath():
  7. print($Child)
  8. # Fastest. Doesn't break if node moves later.
  9. # Note that `onready` keyword is GDScript only.
  10. # Other languages must do...
  11. # var child
  12. # func _ready():
  13. # child = get_node("Child")
  14. onready var child = $Child
  15. func lookup_and_cache_for_future_access():
  16. print(child)
  17. # Delegate reference assignment to an external source.
  18. # Con: need to perform a validation check.
  19. # Pro: node makes no requirements of its external structure.
  20. # 'prop' can come from anywhere.
  21. var prop
  22. func call_me_after_prop_is_initialized_by_parent():
  23. # Validate prop in one of three ways.
  24. # Fail with no notification.
  25. if not prop:
  26. return
  27. # Fail with an error message.
  28. if not prop:
  29. printerr("'prop' wasn't initialized")
  30. return
  31. # Fail and terminate.
  32. # Note: Scripts run from a release export template don't
  33. # run `assert` statements.
  34. assert(prop, "'prop' wasn't initialized")
  35. # Use an autoload.
  36. # Dangerous for typical nodes, but useful for true singleton nodes
  37. # that manage their own data and don't interfere with other objects.
  38. func reference_a_global_autoloaded_variable():
  39. print(globals)
  40. print(globals.prop)
  41. print(globals.my_getter())
  1. public class MyNode
  2. {
  3. // Slow, dynamic lookup with dynamic NodePath.
  4. public void Method1()
  5. {
  6. GD.Print(GetNode(NodePath("Child")));
  7. }
  8. // Fastest. Lookup node and cache for future access.
  9. // Doesn't break if node moves later.
  10. public Node Child;
  11. public void _Ready()
  12. {
  13. Child = GetNode(NodePath("Child"));
  14. }
  15. public void Method2()
  16. {
  17. GD.Print(Child);
  18. }
  19. // Delegate reference assignment to an external source.
  20. // Con: need to perform a validation check.
  21. // Pro: node makes no requirements of its external structure.
  22. // 'prop' can come from anywhere.
  23. public object Prop;
  24. public void CallMeAfterPropIsInitializedByParent()
  25. {
  26. // Validate prop in one of three ways.
  27. // Fail with no notification.
  28. if (prop == null)
  29. {
  30. return;
  31. }
  32. // Fail with an error message.
  33. if (prop == null)
  34. {
  35. GD.PrintErr("'Prop' wasn't initialized");
  36. return;
  37. }
  38. // Fail and terminate.
  39. Debug.Assert(Prop, "'Prop' wasn't initialized");
  40. }
  41. // Use an autoload.
  42. // Dangerous for typical nodes, but useful for true singleton nodes
  43. // that manage their own data and don't interfere with other objects.
  44. public void ReferenceAGlobalAutoloadedVariable()
  45. {
  46. Node globals = GetNode(NodePath("/root/Globals"));
  47. GD.Print(globals);
  48. GD.Print(globals.prop);
  49. GD.Print(globals.my_getter());
  50. }
  51. };

从对象访问数据或逻辑

Godot的脚本API是鸭子类型.这意味着,如果脚本执行操作,则Godot不会通过 类型 验证其是否支持该操作.相反,它检查对象是否 实现 了单个方法.

例如, CanvasItem 类有一个 visible 的属性.实际上,脚本API公开的所有属性,都是绑定到名称的 settergetter 对.如果有人试图访问 CanvasItem.visible,那么Godot会按照以下顺序进行检查:

  • 如果对象附加了脚本,它将尝试通过脚本设置属性.通过覆盖属性的 setter 方法,这为脚本提供了覆盖基础对象上定义的属性的机会.

  • 如果脚本没有该属性,它在 ClassDB 中对 CanvasItem 类及其所有继承的类型执行 visible 属性的哈希表查找.如果找到,它将调用绑定的 settergetter.有关哈希表的更多信息,参见 数据偏好 文档.

  • 如果没有找到,它会进行显式检查,以查看用户是否要访问 scriptmeta 属性.

  • 如果没有,它将在 CanvasItem 及其继承的类型中检查 _set/_get 实现(取决于访问类型).这些方法可以执行逻辑,从而给人一种对象具有属性的印象.``_get_property_list`` 方法也是如此.

    • 请注意,即使对于非合法的符号名称,例如 TileSet1/tile_name 属性,这种情况也会发生.这是指ID为1的 tile 的名称,即 TileSet.tile_get_name(1).

因此,这个鸭子类型的系统可以在脚本、对象的类、或对象继承的任何类、但只能用于扩展Object的对象中,定位属性.

Godot提供了多种选项,来对这些访问,执行运行时检查:

  • 鸭子类型属性的访问.这些将进行属性检查(如上所述).如果对象不支持该操作,则执行将停止.

    GDScript

    C#

    1. # All Objects have duck-typed get, set, and call wrapper methods.
    2. get_parent().set("visible", false)
    3. # Using a symbol accessor, rather than a string in the method call,
    4. # will implicitly call the `set` method which, in turn, calls the
    5. # setter method bound to the property through the property lookup
    6. # sequence.
    7. get_parent().visible = false
    8. # Note that if one defines a _set and _get that describe a property's
    9. # existence, but the property isn't recognized in any _get_property_list
    10. # method, then the set() and get() methods will work, but the symbol
    11. # access will claim it can't find the property.
    1. // All Objects have duck-typed Get, Set, and Call wrapper methods.
    2. GetParent().Set("visible", false);
    3. // C# is a static language, so it has no dynamic symbol access, e.g.
    4. // `GetParent().Visible = false` won't work.
  • 一个方法检查.在 CanvasItem.visible 的情况下,我们可以像访问任何其他方法一样,访问这些方法,``set_visible`` 和 is_visible .

    GDScript

    C#

    1. var child = get_child(0)
    2. # Dynamic lookup.
    3. child.call("set_visible", false)
    4. # Symbol-based dynamic lookup.
    5. # GDScript aliases this into a 'call' method behind the scenes.
    6. child.set_visible(false)
    7. # Dynamic lookup, checks for method existence first.
    8. if child.has_method("set_visible"):
    9. child.set_visible(false)
    10. # Cast check, followed by dynamic lookup.
    11. # Useful when you make multiple "safe" calls knowing that the class
    12. # implements them all. No need for repeated checks.
    13. # Tricky if one executes a cast check for a user-defined type as it
    14. # forces more dependencies.
    15. if child is CanvasItem:
    16. child.set_visible(false)
    17. child.show_on_top = true
    18. # If one does not wish to fail these checks without notifying users,
    19. # one can use an assert instead. These will trigger runtime errors
    20. # immediately if not true.
    21. assert(child.has_method("set_visible"))
    22. assert(child.is_in_group("offer"))
    23. assert(child is CanvasItem)
    24. # Can also use object labels to imply an interface, i.e. assume it
    25. # implements certain methods.
    26. # There are two types, both of which only exist for Nodes: Names and
    27. # Groups.
    28. # Assuming...
    29. # A "Quest" object exists and 1) that it can "complete" or "fail" and
    30. # that it will have text available before and after each state...
    31. # 1. Use a name.
    32. var quest = $Quest
    33. print(quest.text)
    34. quest.complete() # or quest.fail()
    35. print(quest.text) # implied new text content
    36. # 2. Use a group.
    37. for a_child in get_children():
    38. if a_child.is_in_group("quest"):
    39. print(quest.text)
    40. quest.complete() # or quest.fail()
    41. print(quest.text) # implied new text content
    42. # Note that these interfaces are project-specific conventions the team
    43. # defines (which means documentation! But maybe worth it?).
    44. # Any script that conforms to the documented "interface" of the name or
    45. # group can fill in for it.
    1. Node child = GetChild(0);
    2. // Dynamic lookup.
    3. child.Call("SetVisible", false);
    4. // Dynamic lookup, checks for method existence first.
    5. if (child.HasMethod("SetVisible"))
    6. {
    7. child.Call("SetVisible", false);
    8. }
    9. // Use a group as if it were an "interface", i.e. assume it implements
    10. // certain methods.
    11. // Requires good documentation for the project to keep it reliable
    12. // (unless you make editor tools to enforce it at editor time).
    13. // Note, this is generally not as good as using an actual interface in
    14. // C#, but you can't set C# interfaces from the editor since they are
    15. // language-level features.
    16. if (child.IsInGroup("Offer"))
    17. {
    18. child.Call("Accept");
    19. child.Call("Reject");
    20. }
    21. // Cast check, followed by static lookup.
    22. CanvasItem ci = GetParent() as CanvasItem;
    23. if (ci != null)
    24. {
    25. ci.SetVisible(false);
    26. // useful when you need to make multiple safe calls to the class
    27. ci.ShowOnTop = true;
    28. }
    29. // If one does not wish to fail these checks without notifying users,
    30. // one can use an assert instead. These will trigger runtime errors
    31. // immediately if not true.
    32. Debug.Assert(child.HasMethod("set_visible"));
    33. Debug.Assert(child.IsInGroup("offer"));
    34. Debug.Assert(CanvasItem.InstanceHas(child));
    35. // Can also use object labels to imply an interface, i.e. assume it
    36. // implements certain methods.
    37. // There are two types, both of which only exist for Nodes: Names and
    38. // Groups.
    39. // Assuming...
    40. // A "Quest" object exists and 1) that it can "Complete" or "Fail" and
    41. // that it will have Text available before and after each state...
    42. // 1. Use a name.
    43. Node quest = GetNode("Quest");
    44. GD.Print(quest.Get("Text"));
    45. quest.Call("Complete"); // or "Fail".
    46. GD.Print(quest.Get("Text")); // Implied new text content.
    47. // 2. Use a group.
    48. foreach (Node AChild in GetChildren())
    49. {
    50. if (AChild.IsInGroup("quest"))
    51. {
    52. GD.Print(quest.Get("Text"));
    53. quest.Call("Complete"); // or "Fail".
    54. GD.Print(quest.Get("Text")); // Implied new text content.
    55. }
    56. }
    57. // Note that these interfaces are project-specific conventions the team
    58. // defines (which means documentation! But maybe worth it?).
    59. // Any script that conforms to the documented "interface" of the
    60. // name or group can fill in for it. Also note that in C#, these methods
    61. // will be slower than static accesses with traditional interfaces.
  • 将访问权限外包给 FuncRef.在人们需要最大程度地摆脱依赖的情况下,这些方法可能会很有用.在这种情况下,需要依靠外部上下文来设置此方法.

GDScript

C#

  1. # child.gd
  2. extends Node
  3. var fn = null
  4. func my_method():
  5. if fn:
  6. fn.call_func()
  7. # parent.gd
  8. extends Node
  9. onready var child = $Child
  10. func _ready():
  11. child.fn = funcref(self, "print_me")
  12. child.my_method()
  13. func print_me():
  14. print(name)
  1. // Child.cs
  2. public class Child : Node
  3. {
  4. public FuncRef FN = null;
  5. public void MyMethod()
  6. {
  7. Debug.Assert(FN != null);
  8. FN.CallFunc();
  9. }
  10. }
  11. // Parent.cs
  12. public class Parent : Node
  13. {
  14. public Node Child;
  15. public void _Ready()
  16. {
  17. Child = GetNode("Child");
  18. Child.Set("FN", GD.FuncRef(this, "PrintMe"));
  19. Child.MyMethod();
  20. }
  21. public void PrintMe() {
  22. {
  23. GD.Print(GetClass());
  24. }
  25. }

这些策略有助于Godot的灵活设计.通过它们,用户可以使用多种工具来满足他们的特定需求.