Interfaces de Godot

Souvent, on a besoin de scripts qui s’appuient sur d’autres objets pour des fonctionnalités. Il y a 2 parties à ce processus :

  1. Acquisition d’une référence à l’objet qui possède vraisemblablement les fonctionnalités.
  2. Accès aux données ou à la logique à partir de l’objet.

La suite de ce tutoriel décrit les différentes façons de faire tout cela.

Acquisition de références d’objets

Pour tous les Objects, la façon la plus simple de les référencer est d’obtenir une référence à un objet existant depuis une autre instance acquise.

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

Le même principe s’applique aux objets Référence. Bien que les utilisateurs accèdent souvent à Node et Resource de cette façon, des mesures alternatives sont disponibles.

Au lieu de l’accès à la propriété ou à la méthode, on peut obtenir des ressources par accès par chargement.

var preres = preload(path) # Load resource during scene load
var res = load(path) # Load resource when program reaches statement

# Note that users load scenes and scripts, by convention, with PascalCase
# names (like typenames), often into constants.
const MyScene : = preload("my_scene.tscn") as PackedScene # Static load
const MyScript : = preload("my_script.gd") as Script

# This type's value varies, i.e. it is a variable, so it uses snake_case.
export(Script) var script_type: Script

# If need an "export const var" (which doesn't exist), use a conditional
# setter for a tool script that checks if it's executing in the editor.
tool # Must place at top of file.

# Must configure from the editor, defaults to null.
export(Script) var const_script setget set_const_script
func set_const_script(value):
    if Engine.is_editor_hint():
        const_script = value

# Warn users if the value hasn't been set.
func _get_configuration_warning():
    if not const_script:
        return "Must initialize property 'const_script'."
    return ""
// Tool script added for the sake of the "const [Export]" example.
[Tool]
public MyType : extends Object
{
    // Property initializations load during Script instancing, i.e. .new().
    // No "preload" loads during scene load exists in C#.

    // Initialize with a value. Editable at runtime.
    public Script MyScript = GD.Load<Script>("MyScript.cs");

    // Initialize with same value. Value cannot be changed.
    public readonly Script MyConstScript = GD.Load<Script>("MyScript.cs");

    // Like 'readonly' due to inaccessible setter.
    // But, value can be set during constructor, i.e. MyType().
    public Script Library { get; } = GD.Load<Script>("res://addons/plugin/library.gd");

    // If need a "const [Export]" (which doesn't exist), use a
    // conditional setter for a tool script that checks if it's executing
    // in the editor.
    private PackedScene _enemyScn;

    [Export]
    public PackedScene EnemyScn
    {
        get { return _enemyScn; }
        set
        {
            if (Engine.IsEditorHint())
            {
                _enemyScn = value;
            }
        }
    };

    // Warn users if the value hasn't been set.
    public String _GetConfigurationWarning()
    {
        if (EnemyScn == null)
            return "Must initialize property 'EnemyScn'.";
        return "";
    }
}

Notez ce qui suit :

  1. Il existe de nombreuses façons pour un langage de charger de telles ressources.
  2. Lors de la conception de la manière dont les objets accéderont aux données, n’oubliez pas qu’il est également possible de faire circuler des ressources comme références.
  3. Gardez à l’esprit que le chargement d’une ressource récupère l’instance de ressource mise en cache maintenue par le moteur. Pour obtenir un nouvel objet, il faut duplicate une référence existante ou en instancier une à partir de zéro avec new().

Les nœuds ont également un autre point d’accès : le SceneTree.

extends Node

# Slow.
func dynamic_lookup_with_dynamic_nodepath():
    print(get_node("Child"))

# Faster. GDScript only.
func dynamic_lookup_with_cached_nodepath():
    print($Child)

# Fastest. Doesn't break if node moves later.
# Note that `onready` keyword is GDScript only.
# Other languages must do...
#     var child
#     func _ready():
#         child = get_node("Child")
onready var child = $Child
func lookup_and_cache_for_future_access():
    print(child)

# Delegate reference assignment to an external source
# Con: need to perform a validation check
# Pro: node makes no requirements of its external structure.
#      'prop' can come from anywhere.
var prop
func call_me_after_prop_is_initialized_by_parent():
    # Validate prop in one of three ways.

    # Fail with no notification.
    if not prop:
        return

    # Fail with an error message.
    if not prop:
        printerr("'prop' wasn't initialized")
        return

    # Fail and terminate.
    # Compiled scripts in final binary do not include assert statements
    assert prop.

# Use an autoload.
# Dangerous for typical nodes, but useful for true singleton nodes
# that manage their own data and don't interfere with other objects.
func reference_a_global_autoloaded_variable():
    print(globals)
    print(globals.prop)
    print(globals.my_getter())
public class MyNode
{
    // Slow, dynamic lookup with dynamic NodePath.
    public void Method1()
    {
        GD.Print(GetNode(NodePath("Child")));
    }

    // Fastest. Lookup node and cache for future access.
    // Doesn't break if node moves later.
    public Node Child;
    public void _Ready()
    {
        Child = GetNode(NodePath("Child"));
    }
    public void Method2()
    {
        GD.Print(Child);
    }

    // Delegate reference assignment to an external source
    // Con: need to perform a validation check
    // Pro: node makes no requirements of its external structure.
    //      'prop' can come from anywhere.
    public object Prop;
    public void CallMeAfterPropIsInitializedByParent()
    {
        // Validate prop in one of three ways.

        // Fail with no notification.
        if (prop == null)
        {
            return;
        }

        // Fail with an error message.
        if (prop == null)
        {
            GD.PrintErr("'Prop' wasn't initialized");
            return;
        }

        // Fail and terminate.
        Debug.Assert(Prop, "'Prop' wasn't initialized");
    }

    // Use an autoload.
    // Dangerous for typical nodes, but useful for true singleton nodes
    // that manage their own data and don't interfere with other objects.
    public void ReferenceAGlobalAutoloadedVariable()
    {
        Node globals = GetNode(NodePath("/root/Globals"));
        GD.Print(globals);
        GD.Print(globals.prop);
        GD.Print(globals.my_getter());
    }
};

Accès aux données ou à la logique à partir d’un objet

L’API de script de Godot est duck-typed. Cela signifie que si un script exécute une opération, Godot ne valide pas qu’il supporte l’opération par type. Au lieu de cela, il vérifie que l’objet implémente la méthode individuelle.

Par exemple, la classe CanvasItem a une propriété visible. Toutes les propriétés exposées à l’API de script sont en fait une paire setter et getter liée à un nom. Si on essayait d’accéder à CanvasItem.visible, alors Godot ferait les vérifications suivantes, dans l’ordre :

  • Si l’objet a un script attaché, il tentera de définir la propriété à travers le script. Ceci laisse la possibilité pour les scripts de substituer une propriété définie sur un objet de base en substituant la méthode setter de la propriété.
  • Si le script n’a pas la propriété, il effectue une recherche HashMap dans la ClassDB pour la propriété « visible » envers la classe CanvasItem et tous ses types hérités. S’il est trouvé, il appellera le setter ou le getter lié. Pour plus d’informations sur HashMaps, consultez data preferences.
  • S’il n’est pas trouvé, il vérifie explicitement si l’utilisateur veut accéder aux propriétés « script » ou « meta ».
  • Si ce n’est pas le cas, il vérifie la présence d’une implémentation _set`/``_get (selon le type d’accès) dans l’élément CanvasItem et ses types hérités. Ces méthodes peuvent exécuter une logique qui donne l’impression que l’Objet possède une propriété. C’est également le cas avec la méthode _get_property_list.
    • Notez que cela se produit même pour les noms de symboles non légaux comme dans le cas de TileSet.

En conséquence, ce système duck-typed peut localiser une propriété soit dans le script, soit dans la classe de l’objet, soit dans n’importe quelle classe dont l’objet hérite, mais seulement pour les choses qui étendent de Object.

Godot fournit une variété d’options pour effectuer des contrôles d’exécution sur ces accès :

  • Un accès à des propriétés de façon duck-typed. Celles-ci feront l’objet d’un contrôle de propriété (tel que décrit ci-dessus). Si l’opération n’est pas supportée par l’objet, l’exécution s’arrête.

    # All Objects have duck-typed get, set, and call wrapper methods.
    get_parent().set("visible", false)
    
    # Using a symbol accessor, rather than a string in the method call,
    # will implicitly call the `set` method which, in turn, calls the
    # setter method bound to the property through the property lookup
    # sequence.
    get_parent().visible = false
    
    # Note that if one defines a _set and _get that describe a property's
    # existence, but the property isn't recognized in any _get_property_list
    # method, then the set() and get() methods will work, but the symbol
    # access will claim it can't find the property.
    
    // All Objects have duck-typed Get, Set, and Call wrapper methods.
    GetParent().Set("visible", false);
    
    // C# is a static language, so it has no dynamic symbol access, e.g.
    // `GetParent().Visible = false` won't work.
    
  • Un contrôle de méthode. Dans le cas de CanvasItem.visible, on peut accéder aux méthodes, set_visible et is_visible comme toute autre méthode.

    var child = get_child(0)
    
    # Dynamic lookup.
    child.call("set_visible", false)
    
    # Symbol-based dynamic lookup.
    # GDScript aliases this into a 'call' method behind the scenes.
    child.set_visible(false)
    
    # Dynamic lookup, checks for method existence first.
    if child.has("set_visible"):
        child.set_visible(false)
    
    # Cast check, followed by dynamic lookup
    # Useful when you make multiple "safe" calls knowing that the class
    # implements them all. No need for repeated checks.
    # Tricky if one executes a cast check for a user-defined type as it
    # forces more dependencies.
    if child is CanvasItem:
        child.set_visible(false)
        child.show_on_top = true
    
    # If one does not wish to fail these checks without notifying users, one
    # can use an assert instead. These will trigger runtime errors
    # immediately if not true.
    assert child.has("set_visible")
    assert child.is_in_group("offer")
    assert child is CanvasItem
    
    # Can also use object labels to imply an interface, i.e. assume it implements certain methods.
    # There are two types, both of which only exist for Nodes: Names and Groups
    
    # Assuming...
    # A "Quest" object exists and 1) that it can "complete" or "fail" and
    # that it will have text available before and after each state...
    
    # 1. Use a name.
    var quest = $Quest
    print(quest.text)
    quest.complete() # or quest.fail()
    print(quest.text) # implied new text content
    
    # 2. Use a group.
    for a_child in get_children():
        if a_child.is_in_group("quest"):
            print(quest.text)
            quest.complete() # or quest.fail()
            print(quest.text) # implied new text content
    
    # Note that these interfaces are project-specific conventions the team
    # defines (which means documentation! But maybe worth it?).
    # Any script that conforms to the documented "interface" of the name/group can fill in for it.
    
    Node child = GetChild(0);
    
    // Dynamic lookup.
    child.Call("SetVisible", false);
    
    // Dynamic lookup, checks for method existence first.
    if (child.HasMethod("SetVisible"))
    {
        child.Call("SetVisible", false);
    }
    
    // Use a group as if it were an "interface", i.e. assume it implements certain methods
    // requires good documentation for the project to keep it reliable (unless you make
    // editor tools to enforce it at editor time.
    // Note, this is generally not as good as using an actual interface in C#,
    // but you can't set C# interfaces from the editor since they are
    // language-level features.
    if (child.IsInGroup("Offer"))
    {
        child.Call("Accept");
        child.Call("Reject");
    }
    
    // Cast check, followed by static lookup.
    CanvasItem ci = GetParent() as CanvasItem;
    if (ci != null)
    {
        ci.SetVisible(false);
    
        // useful when you need to make multiple safe calls to the class
        ci.ShowOnTop = true;
    }
    
    // If one does not wish to fail these checks without notifying users, one
    // can use an assert instead. These will trigger runtime errors
    // immediately if not true.
    Debug.Assert(child.HasMethod("set_visible"));
    Debug.Assert(child.IsInGroup("offer"));
    Debug.Assert(CanvasItem.InstanceHas(child));
    
    // Can also use object labels to imply an interface, i.e. assume it implements certain methods.
    // There are two types, both of which only exist for Nodes: Names and Groups
    
    // Assuming...
    // A "Quest" object exists and 1) that it can "Complete" or "Fail" and
    // that it will have Text available before and after each state...
    
    // 1. Use a name.
    Node quest = GetNode("Quest");
    GD.Print(quest.Get("Text"));
    quest.Call("Complete"); // or "Fail".
    GD.Print(quest.Get("Text")); // Implied new text content.
    
    // 2. Use a group.
    foreach (Node AChild in GetChildren())
    {
        if (AChild.IsInGroup("quest"))
        {
          GD.Print(quest.Get("Text"));
          quest.Call("Complete"); // or "Fail".
          GD.Print(quest.Get("Text")); // Implied new text content.
        }
    }
    
    // Note that these interfaces are project-specific conventions the team
    // defines (which means documentation! But maybe worth it?)..
    // Any script that conforms to the documented "interface" of the
    // name/group can fill in for it. Also note that in C#, these methods
    // will be slower than static accesses with traditional interfaces.
    
  • Externaliser l’accès à un FuncRef. Celles-ci peuvent être utiles dans les cas où l’on a besoin d’un niveau maximum de liberté des dépendances. Dans ce cas, on s’appuie sur un contexte externe pour configurer la méthode.

# child.gd
extends Node
var fn = null

func my_method():
    if fn:
        fn.call_func()

# parent.gd
extends Node

onready var child = $Child

func _ready():
    child.fn = funcref(self, "print_me")
    child.my_method()

func print_me():
    print(name)
// Child.cs
public class Child extends Node
{
    public FuncRef FN = null;

    public void MyMethod()
    {
        Debug.Assert(FN != null);
        FN.CallFunc();
    }
}

// Parent.cs
public class Parent extends Node
{
    public Node Child;

    public void _Ready()
    {
        Child = GetNode("Child");
        Child.Set("FN", GD.FuncRef(this, "PrintMe"));
        Child.MyMethod();
    }

    public void PrintMe() {
    {
        GD.Print(GetClass());
    }
}

Ces stratégies contribuent à la souplesse de conception de Godot. Entre elles, les utilisateurs disposent d’un large éventail d’outils pour répondre à leurs besoins spécifiques.