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 对象。虽然用户经常以这种方式访问 Node 和 Resource，还可以采取其他措施。

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

GDScript

C#

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

请注意以下几点：

  1. 一种语言可以通过多种方式加载这些资源。
  2. 在设计对象如何访问数据时，不要忘记，还可以将资源作为引用传递。
  3. 请记住，加载资源将获取引擎维护的缓存资源实例。要获取一个新对象，必须 复制 一个现有引用，或者使用 new() 从头实例化一个引用。

节点也有一个可选的访问点：场景树。

GDScript

C#

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

从对象访问数据或逻辑

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

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

  • 如果对象附加了脚本，它将尝试通过脚本设置属性。通过覆盖属性的 setter 方法，这为脚本提供了覆盖基础对象上定义的属性的机会。
  • 如果脚本没有该属性，它在 ClassDB 中对 CanvasItem 类及其所有继承的类型执行 visible 属性的哈希表查找。如果找到，它将调用绑定的 setter 或 getter。有关哈希表的更多信息，参见 数据偏好 文档。
  • 如果没有找到，它会进行显式检查，以查看用户是否要访问 script 或 meta 属性。
  • 如果没有，它将在 CanvasItem 及其继承的类型中检查 _set/_get 实现（取决于访问类型）。这些方法可以执行逻辑，从而给人一种对象具有属性的印象。_get_property_list 方法也是如此。
    • 请注意，即使对于非合法的符号名称，例如 TileSet 的 1/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)
    4. # Using a symbol accessor, rather than a string in the method call,
    5. # will implicitly call the `set` method which, in turn, calls the
    6. # setter method bound to the property through the property lookup
    7. # sequence.
    8. get_parent().visible = false
    10. # Note that if one defines a _set and _get that describe a property's
    11. # existence, but the property isn't recognized in any _get_property_list
    12. # method, then the set() and get() methods will work, but the symbol
    13. # 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);
    4. // C# is a static language, so it has no dynamic symbol access, e.g.
    5. // `GetParent().Visible = false` won't work.

  • 一个方法检查。在 CanvasItem.visible 的情况下，我们可以像访问任何其他方法一样，访问这些方法，set_visible 和 is_visible 。

    GDScript

    C#

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

  • 将访问权限外包给 FuncRef。在人们需要最大程度地摆脱依赖的情况下，这些方法可能会很有用。在这种情况下，需要依靠外部上下文来设置此方法。

GDScript

C#

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

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