Godot interfaces

    1. Acquiring a reference to the object that presumably has the features.
    2. Accessing the data or logic from the object.

    The rest of this tutorial outlines the various ways of doing all this.

    For all s, the most basic way of referencing them is to get a reference to an existing object from another acquired instance.

    GDScript

    C#

    2. Object obj = node.GetObject(); // Method access.

    The same principle applies for Reference objects. While users often access and Resource this way, alternative measures are available.

    Instead of property or method access, one can get Resources by load access.

    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. There are many ways in which a language can load such resources.
    2. When designing how objects will access data, don’t forget that one can pass resources around as references as well.
    3. Keep in mind that loading a resource fetches the cached resource instance maintained by the engine. To get a new object, one must an existing reference or instantiate one from scratch with new().

    Nodes likewise have an alternative access point: the SceneTree.

    GDScript

    C#

    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.     public void Method2()
    16.     {
    17.         GD.Print(Child);
    20.     // Delegate reference assignment to an external source
    21.     // Con: need to perform a validation check
    22.     // Pro: node makes no requirements of its external structure.
    23.     //      'prop' can come from anywhere.
    24.     public object Prop;
    25.     public void CallMeAfterPropIsInitializedByParent()
    26.     {
    27.         // Validate prop in one of three ways.
    29.         // Fail with no notification.
    30.         if (prop == null)
    31.         {
    32.             return;
    33.         }
    35.         // Fail with an error message.
    36.         if (prop == null)
    37.         {
    38.             GD.PrintErr("'Prop' wasn't initialized");
    39.             return;
    40.         }
    42.         // Fail and terminate.
    43.         Debug.Assert(Prop, "'Prop' wasn't initialized");
    44.     }
    46.     // Use an autoload.
    47.     // Dangerous for typical nodes, but useful for true singleton nodes
    48.     // that manage their own data and don't interfere with other objects.
    49.     public void ReferenceAGlobalAutoloadedVariable()
    50.     {
    51.         Node globals = GetNode(NodePath("/root/Globals"));
    52.         GD.Print(globals);
    53.         GD.Print(globals.prop);
    54.         GD.Print(globals.my_getter());
    55.     }
    56. };

    Accessing data or logic from an object

    Godot’s scripting API is duck-typed. This means that if a script executes an operation, Godot doesn’t validate that it supports the operation by type. It instead checks that the object implements the individual method.

    For example, the CanvasItem class has a visible property. All properties exposed to the scripting API are in fact a setter and getter pair bound to a name. If one tried to access , then Godot would do the following checks, in order:

    • If the object has a script attached, it will attempt to set the property through the script. This leaves open the opportunity for scripts to override a property defined on a base object by overriding the setter method for the property.
    • If the script does not have the property, it performs a HashMap lookup in the ClassDB for the “visible” property against the CanvasItem class and all of its inherited types. If found, it will call the bound setter or getter. For more information about HashMaps, see the data preferences docs.
    • If not found, it does an explicit check to see if the user wants to access the “script” or “meta” properties.
    • If not, it checks for a _set/_get implementation (depending on type of access) in the CanvasItem and its inherited types. These methods can execute logic that gives the impression that the Object has a property. This is also the case with the _get_property_list method.
      • Note that this happens even for non-legal symbol names such as in the case of ‘s “1/tile_name” property. This refers to the name of the tile with ID 1, i.e. TileSet.tile_get_name(1).

    As a result, this duck-typed system can locate a property either in the script, the object’s class, or any class that object inherits, but only for things which extend Object.

    Godot provides a variety of options for performing runtime checks on these accesses:

    • A duck-typed property access. These will property check (as described above). If the operation isn’t supported by the object, execution will halt.

      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.

    • A method check. In the case of , one can access the methods, set_visible and is_visible like any other method.

      GDScript

      C#

      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. {
      29.     // useful when you need to make multiple safe calls to the class
      30.     ci.ShowOnTop = true;
      31. }
      33. // If one does not wish to fail these checks without notifying users, one
      34. // can use an assert instead. These will trigger runtime errors
      35. // immediately if not true.
      36. Debug.Assert(child.HasMethod("set_visible"));
      37. Debug.Assert(child.IsInGroup("offer"));
      38. Debug.Assert(CanvasItem.InstanceHas(child));
      40. // Can also use object labels to imply an interface, i.e. assume it implements certain methods.
      41. // There are two types, both of which only exist for Nodes: Names and Groups
      43. // Assuming...
      44. // A "Quest" object exists and 1) that it can "Complete" or "Fail" and
      45. // that it will have Text available before and after each state...
      47. // 1. Use a name.
      48. Node quest = GetNode("Quest");
      49. GD.Print(quest.Get("Text"));
      50. quest.Call("Complete"); // or "Fail".
      51. GD.Print(quest.Get("Text")); // Implied new text content.
      53. // 2. Use a group.
      54. foreach (Node AChild in GetChildren())
      55. {
      56.     if (AChild.IsInGroup("quest"))
      57.     {
      58.       GD.Print(quest.Get("Text"));
      59.       quest.Call("Complete"); // or "Fail".
      60.       GD.Print(quest.Get("Text")); // Implied new text content.
      61.     }
      62. }
      64. // Note that these interfaces are project-specific conventions the team
      65. // defines (which means documentation! But maybe worth it?)..
      66. // Any script that conforms to the documented "interface" of the
      67. // name/group can fill in for it. Also note that in C#, these methods
      68. // will be slower than static accesses with traditional interfaces.

    • Outsource the access to a FuncRef. These may be useful in cases where one needs the max level of freedom from dependencies. In this case, one relies on an external context to setup the method.

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

    These strategies contribute to Godot’s flexible design. Between them, users have a breadth of tools to meet their specific needs.