ReckfellObject

public ReckfellObject();

Constructs a new ReckfellObject.

public IntPtr NativeInstance { get; }

The pointer to the native instance of this ReckfellObject.

public void AddUserSignal(string signal, Reckfell.Collections.Array arguments = null);

Adds a dynamic signal to this instance. The name must not conflict with an existing signal/built-in member; this does not register it for every instance of the class.

public Variant Call(StringName method, params Variant[] args);

Dynamically calls an instance method with Variant arguments. Prefer the typed API for known types; use an exact method name and compatible arguments.

public Variant Call(StringName method, ReadOnlySpan<Variant> args);

Calls the method on the object and returns the result. This method supports a variable number of arguments, so parameters can be passed as a comma separated list.

var node = new Entity3D();
node.Call(Entity3D.MethodName.Rotate, new Vector3(1f, 0f, 0f), 1.571f);

Note: In C#, method must be in snake_case when referring to built-in Reckfell methods. Prefer using the names exposed in the MethodName class to avoid allocating a new StringName on each call.

public Variant CallDeferred(StringName method, params Variant[] args);

Queues a method call instead of running it immediately. Processing is not guaranteed to be exactly the next frame; the returned Variant is not the eventual call result.

public Variant CallDeferred(StringName method, ReadOnlySpan<Variant> args);

Calls the method on the object during idle time. Always returns null, not the method's result. Idle time happens mainly at the end of process and physics frames. In it, deferred calls will be run until there are none left, which means you can defer calls from other deferred calls and they'll still be run in the current idle time cycle. This means you should not call a method deferred from itself (or from a method called by it), as this causes infinite recursion the same way as if you had called the method directly. This method supports a variable number of arguments, so parameters can be passed as a comma separated list.

var node = new Entity3D();
node.CallDeferred(Entity3D.MethodName.Rotate, new Vector3(1f, 0f, 0f), 1.571f);

For methods that are deferred from the same thread, the order of execution at idle time is identical to the order in which [code skip-lint]call_deferred was called. See also [Callable.CallDeferred](/en/docs/api/callable#member-calldeferred-6eb547e57a). **Note:** In C#, methodmust be in snake_case when referring to built-in Reckfell methods. Prefer using the names exposed in theMethodName class to avoid allocating a new [StringName](/en/docs/api/stringname) on each call. **Note:** If you're looking to delay the function call by a frame, refer to the [EntityTree.ProcessFrame](/en/docs/api/entitytree#member-processframe-42ca8a2523) and [EntityTree.PhysicsFrame`](/en/docs/api/entitytree#member-physicsframe-194dd11175) signals.

public Variant Callv(StringName method, Reckfell.Collections.Array argArray);

Calls the method on the object and returns the result. Unlike ReckfellObject.Call, this method expects all parameters to be contained inside arg_array.

var node = new Entity3D();
node.Callv(Entity3D.MethodName.Rotate, [new Vector3(1f, 0f, 0f), 1.571f]);

Note: In C#, method must be in snake_case when referring to built-in Reckfell methods. Prefer using the names exposed in the MethodName class to avoid allocating a new StringName on each call.

public bool CanTranslateMessages();

Returns true if the object is allowed to translate messages with ReckfellObject.Tr and ReckfellObject.TrN. See also ReckfellObject.SetMessageTranslation.

public void CancelFree();

If this method is called during ReckfellObject.NotificationPredelete, this object will reject being freed and will remain allocated. This is mostly an internal function used for error handling to avoid the user from freeing objects when they are not intended to.

public Error Connect(StringName signal, Callable callable, uint flags = 0);

Connects a Callable to the signal using the flags. Normal delivery is synchronous; Deferred queues the callback and OneShot disconnects after its first call. Retain the Callable for later disconnection.

public void Disconnect(StringName signal, Callable callable);

Disconnects an existing connection with the same Callable. Check IsConnected when needed; an unrelated new lambda does not replace the retained callback.

public void Dispose();

Disposes of this ReckfellObject.

public Error EmitSignal(StringName signal, params Variant[] args);

Emits a signal with arguments matching its declaration. Normal connections are invoked immediately; successful emission does not prove each callback logic is correct.

public Error EmitSignal(StringName signal, ReadOnlySpan<Variant> args);

Emits the given signal by name. The signal must exist, so it should be a built-in signal of this class or one of its inherited classes, or a user-defined signal (see ReckfellObject.AddUserSignal). This method supports a variable number of arguments, so parameters can be passed as a comma separated list. Returns ERR_UNAVAILABLE if signal does not exist or the parameters are invalid.

EmitSignal(SignalName.Hit, "sword", 100);
EmitSignal(SignalName.GameOver);

Note: In C#, signal must be in snake_case when referring to built-in Reckfell signals. Prefer using the names exposed in the SignalName class to avoid allocating a new StringName on each call.

public void Free();

Deletes the object from memory. Pre-existing references to the object become invalid, and any attempt to access them will result in a runtime error. Checking the references with @GlobalScope.is_instance_valid will return false. This is equivalent to the memdelete function in ReckfellExtension C++.

public Variant Get(StringName property);

Reads an instance property by its native/script name. This is a dynamic Variant value, not reflection of every CLR property; use GetPropertyList and the object contract.

public string GetClass();

Returns the native class name, such as Entity2D, not the attached C# script managed type name. Use GetType for the CLR type.

public Reckfell.Collections.Array<Reckfell.Collections.Dictionary> GetIncomingConnections();

Returns an Reckfell.Collections.Array of signal connections received by this object. Each connection is represented as a Reckfell.Collections.Dictionary that contains three entries:

• signal is a reference to the Signal;
• callable is a reference to the Callable;
• flags is a combination of ReckfellObject.ConnectFlags.

public Variant GetIndexed(EntityPath propertyPath);

Reads a nested property component through EntityPath, such as position:x. This is a property path, not a child Entity lookup.

public ulong GetInstanceId();

Returns a live object transient identifier for InstanceFromId lookup. Does not extend object lifetime or provide a persistent save-file ID.

public Variant GetMeta(StringName name, Variant @default = default);

Reads metadata. For an absent name use HasMeta or an explicit non-Nil default; a missing entry with default=Nil reports an error instead of silently probing presence.

public Reckfell.Collections.Array<StringName> GetMetaList();

Returns current metadata names, including entries hidden from normal Inspector display. This is not a class property list.

public int GetMethodArgumentCount(StringName method);

Returns the number of arguments of the given method by name. Note: In C#, method must be in snake_case when referring to built-in Reckfell methods. Prefer using the names exposed in the MethodName class to avoid allocating a new StringName on each call.

public Reckfell.Collections.Array<Reckfell.Collections.Dictionary> GetMethodList();

Returns instance method metadata, including its supported script context. This is not a universal list of every special language-wrapper operation.

public Reckfell.Collections.Array<Reckfell.Collections.Dictionary> GetPropertyList();

Returns property metadata dictionaries for this instance, including supported native and dynamic/script declarations. Describes the object API, not an arbitrary CLR graph.

public Variant GetScript();

Returns the object's Script instance, or null if no script is attached.

public Reckfell.Collections.Array<Reckfell.Collections.Dictionary> GetSignalConnectionList(StringName signal);

Returns an Reckfell.Collections.Array of connections for the given signal name. Each connection is represented as a Reckfell.Collections.Dictionary that contains three entries:

• Signal;
• callable is a reference to the connected Callable;
• flags is a combination of ReckfellObject.ConnectFlags.

public Reckfell.Collections.Array<Reckfell.Collections.Dictionary> GetSignalList();

Returns metadata for instance signals, including those added by AddUserSignal. Distinct from a registered-class-only list.

public StringName GetTranslationDomain();

Returns the name of the translation domain used by ReckfellObject.Tr and ReckfellObject.TrN. See also TranslationServer.

public bool HasConnections(StringName signal);

Returns true if any connection exists on the given signal name. Note: In C#, signal must be in snake_case when referring to built-in Reckfell methods. Prefer using the names exposed in the SignalName class to avoid allocating a new StringName on each call.

public bool HasMeta(StringName name);

Tests metadata presence without reading a missing value. After SetMeta with Nil the entry is absent.

public bool HasMethod(StringName method);

Checks method availability on this instance, including its script context. Built-in string names are case-sensitive: set_position is not SetPosition.

public bool HasSignal(StringName signal);

Tests signal availability on the instance, including inherited and supported dynamic declarations.

public bool HasUserSignal(StringName signal);

Tests an instance dynamic user signal, distinguishing it from a regular inherited class declaration.

public static ReckfellObject? InstanceFromId(ulong instanceId);

Resolves a current ID to an object, or null after destruction. An ID does not retain an Entity or replace current lifetime validation.

public bool IsBlockingSignals();

Returns true if the object is blocking its signals from being emitted. See ReckfellObject.SetBlockSignals.

public bool IsClass(StringName @class);

Checks the native type and its base classes by exact ClassDB name. Does not test an arbitrary CLR class or the object tree position.

public bool IsClass(string @class);

Checks the native type and its base classes by exact ClassDB name. Does not test an arbitrary CLR class or the object tree position.

public bool IsConnected(StringName signal, Callable callable);

Tests the specific signal/Callable pair, not merely whether any listener exists.

public static bool IsInstanceIdValid(ulong id);

Returns true if the ReckfellObject that corresponds to id is a valid object (e.g. has not been deleted from memory). All Objects have a unique instance ID.

public static bool IsInstanceValid(ReckfellObject? instance);

Tests whether the wrapper has a valid native object; null or a freed wrapper returns false. An Entity already marked QueueFree can remain valid until deletion.

public bool IsQueuedForDeletion();

Returns true if the methods Entity.QueueFree or EntityTree.QueueDelete was called for the object. Note: This method does not return true on children of the node that Entity.QueueFree has been called on, even though they will be freed together with the parent.

public void Notification(int what, bool reversed = false);

Delivers a notification number. Sending a system number does not perform the complete object attachment/deletion protocol.

public void NotifyPropertyListChanged();

Emits the ReckfellObject.PropertyListChanged signal. This is mainly used to refresh the editor, so that the Inspector and editor plugins are properly updated.

public bool PropertyCanRevert(StringName property);

Override this method to customize the given property's revert behavior. Should return true if the property has a custom default value and is revertible in the Inspector dock. Use ReckfellObject.PropertyGetRevert to specify the property's default value. Note: This method must return consistently, regardless of the current value of the property. Note: Unlike other virtual methods, this method is called automatically for every script that overrides it. This means that the base implementation should not be called via super in C# or its equivalents in other languages. The bottom-most sub-class will be called first, with subsequent calls ascending the class hierarchy. The call chain will stop on the first class that returns true.

public Variant PropertyGetRevert(StringName property);

Override this method to customize the given property's revert behavior. Should return the default value for the property. If the default value differs from the property's current value, a revert icon is displayed in the Inspector dock. Note: ReckfellObject.PropertyCanRevert must also be overridden for this method to be called. Note: Unlike other virtual methods, this method is called automatically for every script that overrides it. This means that the base implementation should not be called via super in C# or its equivalents in other languages. The bottom-most sub-class will be called first, with subsequent calls ascending the class hierarchy. The call chain will stop on the first class that returns a non-null value.

public void RemoveMeta(StringName name);

Removes the named metadata entry. Corresponds to SetMeta with Nil and does not change the native class definition.

public void RemoveUserSignal(StringName signal);

Removes the given user signal signal from the object. See also ReckfellObject.AddUserSignal and ReckfellObject.HasUserSignal.

public void Set(StringName property, Variant value);

Writes an instance property through its dynamic setter. Name and type must match the object; position addresses the native Entity2D property.

public void SetBlockSignals(bool enable);

If set to true, the object becomes unable to emit signals. As such, ReckfellObject.EmitSignal and signal connections will not work, until it is set to false.

public void SetDeferred(StringName property, Variant value);

Queues a property assignment. The current value need not change inline; this does not promise a specific following frame number.

public void SetIndexed(EntityPath propertyPath, Variant value);

Writes a nested property component through EntityPath while updating the original value. In the checked position:x case X changes and Y is preserved.

public void SetMessageTranslation(bool enable);

If set to true, allows the object to translate messages with ReckfellObject.Tr and ReckfellObject.TrN. Enabled by default. See also ReckfellObject.CanTranslateMessages.

public void SetMeta(StringName name, Variant value);

Sets a named metadata Variant; Nil removes the entry. The name must be a valid identifier. A leading underscore hides it from normal Inspector display, not from code.

public void SetScript(Variant script);

Attaches script to the object, and instantiates it. As a result, the script's _init is called. A Script is used to extend the object's functionality. If a script already exists, its instance is detached, and its property values and state are lost. Built-in property values are still kept.

public void SetTranslationDomain(StringName domain);

Sets the name of the translation domain used by ReckfellObject.Tr and ReckfellObject.TrN. See also TranslationServer.

public SignalAwaiter ToSignal(ReckfellObject source, StringName signal);

Returns a new SignalAwaiter awaiter configured to complete when the instance source emits the signal specified by the signal parameter.

public override string ToString();

Override this method to customize the return value of ReckfellObject.ToString, and therefore the object's representation as a string.

public string Tr(StringName message, StringName context = null);

Translates a message, using the translation catalogs configured in the Project Settings. Further context can be specified to help with the translation. Note that most Control nodes automatically translate their strings, so this method is mostly useful for formatted strings or custom drawn text. If ReckfellObject.CanTranslateMessages is false, or no translation is available, this method returns the message without changes. See ReckfellObject.SetMessageTranslation. For detailed examples, see Internationalizing games. Note: This method can't be used without an ReckfellObject instance, as it requires the ReckfellObject.CanTranslateMessages method. To translate strings in a static context, use TranslationServer.Translate.

public string TrN(StringName message, StringName pluralMessage, int n, StringName context = null);

Translates a message or plural_message, using the translation catalogs configured in the Project Settings. Further context can be specified to help with the translation. If ReckfellObject.CanTranslateMessages is false, or no translation is available, this method returns message or plural_message, without changes. See ReckfellObject.SetMessageTranslation. The n is the number, or amount, of the message's subject. It is used by the translation system to fetch the correct plural form for the current language. For detailed examples, see Localization using gettext. Note: Negative and ReckfellObject.Tr. Note: This method can't be used without an ReckfellObject instance, as it requires the ReckfellObject.CanTranslateMessages method. To translate strings in a static context, use TranslationServer.TranslatePlural.

public static WeakRef? WeakRef(ReckfellObject? obj);

Returns a weak reference to an object, or null if the argument is invalid. A weak reference to an object is not enough to keep the object alive: when the only remaining references to a referent are weak references, garbage collection is free to destroy the referent and reuse its memory for something else. However, until the object is actually destroyed the weak reference may return the object even if there are no strong references to it.

public virtual Variant _Get(StringName property);

Override this method to customize the behavior of ReckfellObject.Get. Should return the given property's value, or null if the property should be handled normally. Combined with ReckfellObject.Set and ReckfellObject.GetPropertyList, this method allows defining custom properties, which is particularly useful for editor plugins. Note: This method is not called when getting built-in properties of an object, including properties defined with [annotation @C#.@export].

public override Variant _Get(StringName property)
{
    if (property == "FakeProperty")
    {
        ReckfellApi.Print("Getting my property!");
        return 4;
    }
    return default;
}

public override Reckfell.Collections.Array<Reckfell.Collections.Dictionary> _GetPropertyList()
{
    return
    [
        new Reckfell.Collections.Dictionary()
        {
            { "name", "FakeProperty" },
            { "type", (int)Variant.Type.Int },
        },
    ];
}

Note: Unlike other virtual methods, this method is called automatically for every script that overrides it. This means that the base implementation should not be called via super in C# or its equivalents in other languages. The bottom-most sub-class will be called first, with subsequent calls ascending the class hierarchy. The call chain will stop on the first class that returns a non-null value. Warning: This method must be thread-safe if overridden. Otherwise, the engine may crash when trying to save a resource containing the object.

public virtual Reckfell.Collections.Array<Reckfell.Collections.Dictionary> _GetPropertyList();

Override this method to provide a custom list of additional properties to handle by the engine. Should return a property list, as an Reckfell.Collections.Array of dictionaries. The result is added to the array of ReckfellObject.GetPropertyList, and should be formatted in the same way. Each Reckfell.Collections.Dictionary must at least contain the name and type entries. You can use ReckfellObject.PropertyCanRevert and ReckfellObject.PropertyGetRevert to customize the default values of the properties added by this method. The example below displays a list of numbers shown as words going from ZERO to FIVE, with number_count controlling the size of the list:

[Tool]
public partial class MyNode : Entity
{
    private int _numberCount;

    [Export]
    public int NumberCount
    {
        get => _numberCount;
        set
        {
            _numberCount = value;
            _numbers.Resize(_numberCount);
            NotifyPropertyListChanged();
        }
    }

    private Reckfell.Collections.Array<int> _numbers = [];

    public override Reckfell.Collections.Array<Reckfell.Collections.Dictionary> _GetPropertyList()
    {
        Reckfell.Collections.Array<Reckfell.Collections.Dictionary> properties = [];

        for (int i = 0; i < _numberCount; i++)
        {
            properties.Add(new Reckfell.Collections.Dictionary()
            {
                { "name", $"number_{i}" },
                { "type", (int)Variant.Type.Int },
                { "hint", (int)PropertyHint.Enum },
                { "hint_string", "Zero,One,Two,Three,Four,Five" },
            });
        }

        return properties;
    }

    public override Variant _Get(StringName property)
    {
        string propertyName = property.ToString();
        if (propertyName.StartsWith("number_"))
        {
            int index = int.Parse(propertyName.Substring("number_".Length));
            return _numbers[index];
        }
        return default;
    }

    public override bool _Set(StringName property, Variant value)
    {
        string propertyName = property.ToString();
        if (propertyName.StartsWith("number_"))
        {
            int index = int.Parse(propertyName.Substring("number_".Length));
            _numbers[index] = value.As<int>();
            return true;
        }
        return false;
    }
}

Note: This method is intended for advanced purposes. For most common use cases, the scripting languages offer easier ways to handle properties. See ReckfellObject._ValidateProperty. Note: If the object's script is not [annotation @C#.@tool], this method will not be called in the editor. Note: Unlike other virtual methods, this method is called automatically for every script that overrides it. This means that the base implementation should not be called via super in C# or its equivalents in other languages. The bottom-most sub-class will be called first, with subsequent calls ascending the class hierarchy. Warning: This method must be thread-safe if overridden. Otherwise, the engine may crash when trying to save a resource containing the object.

public virtual Variant _IterGet(Variant iter);

Returns the current iterable value. iter stores the iteration state, but unlike ReckfellObject._IterInit and ReckfellObject._IterNext the state is supposed to be read-only, so there is no Reckfell.Collections.Array wrapper. Tip: In C#, you can use a subtype of Variant as the return type for ReckfellObject._IterGet. The specified type will be used to set the type of the iterator variable in for loops, enhancing type safety.

public virtual bool _IterInit(Reckfell.Collections.Array iter);

Initializes the iterator. iter stores the iteration state. Since C# does not support passing arguments by reference, a single-element array is used as a wrapper. This array should not be resized. Returns true so long as the iterator has not reached the end.

Note: Avoid storing iterator state in a member variable, use the iter parameter instead. Otherwise, you won't be able to reuse the same iterator instance in nested loops. See also online docs.

public virtual bool _IterNext(Reckfell.Collections.Array iter);

Moves the iterator to the next iteration. iter stores the iteration state. Since C# does not support passing arguments by reference, a single-element array is used as a wrapper. This array should not be resized. Returns true so long as the iterator has not reached the end.

public virtual void _Notification(int what);

Handles an event code. Prefer dedicated Entity lifecycle callbacks when appropriate. In the checked bridge C# RefCounted scripts do not receive Predelete.

public virtual bool _PropertyCanRevert(StringName property);

Override this method to customize the given property's revert behavior. Should return true if the property has a custom default value and is revertible in the Inspector dock. Use ReckfellObject.PropertyGetRevert to specify the property's default value. Note: This method must return consistently, regardless of the current value of the property. Note: Unlike other virtual methods, this method is called automatically for every script that overrides it. This means that the base implementation should not be called via super in C# or its equivalents in other languages. The bottom-most sub-class will be called first, with subsequent calls ascending the class hierarchy. The call chain will stop on the first class that returns true.

public virtual Variant _PropertyGetRevert(StringName property);

Override this method to customize the given property's revert behavior. Should return the default value for the property. If the default value differs from the property's current value, a revert icon is displayed in the Inspector dock. Note: ReckfellObject.PropertyCanRevert must also be overridden for this method to be called. Note: Unlike other virtual methods, this method is called automatically for every script that overrides it. This means that the base implementation should not be called via super in C# or its equivalents in other languages. The bottom-most sub-class will be called first, with subsequent calls ascending the class hierarchy. The call chain will stop on the first class that returns a non-null value.

public virtual bool _Set(StringName property, Variant value);

Override this method to customize the behavior of ReckfellObject.Set. Should set the property to value and return true, or false if the property should be handled normally. The exact way to set the property is up to this method's implementation. Combined with ReckfellObject.Get and ReckfellObject.GetPropertyList, this method allows defining custom properties, which is particularly useful for editor plugins. Note: This method is not called when setting built-in properties of an object, including properties defined with [annotation @C#.@export].

private Reckfell.Collections.Dictionary _internalData = new Reckfell.Collections.Dictionary();

public override bool _Set(StringName property, Variant value)
{
    if (property == "FakeProperty")
    {
        // Storing the value in the fake property.
        _internalData["FakeProperty"] = value;
        return true;
    }

    return false;
}

public override Reckfell.Collections.Array<Reckfell.Collections.Dictionary> _GetPropertyList()
{
    return
    [
        new Reckfell.Collections.Dictionary()
        {
            { "name", "FakeProperty" },
            { "type", (int)Variant.Type.Int },
        },
    ];
}

Note: Unlike other virtual methods, this method is called automatically for every script that overrides it. This means that the base implementation should not be called via super in C# or its equivalents in other languages. The bottom-most sub-class will be called first, with subsequent calls ascending the class hierarchy. The call chain will stop on the first class that returns true.

public virtual void _ValidateProperty(Reckfell.Collections.Dictionary property);

Override this method to customize existing properties. Every property info goes through this method, except properties added with ReckfellObject.GetPropertyList. The dictionary contents is the same as in ReckfellObject.GetPropertyList.

[Tool]
public partial class MyNode : Entity
{
    private bool _isNumberEditable;

    [Export]
    public bool IsNumberEditable
    {
        get => _isNumberEditable;
        set
        {
            _isNumberEditable = value;
            NotifyPropertyListChanged();
        }
    }

    [Export]
    public int Number { get; set; }

    public override void _ValidateProperty(Reckfell.Collections.Dictionary property)
    {
        if (property["name"].AsStringName() == PropertyName.Number && !IsNumberEditable)
        {
            var usage = property["usage"].As<PropertyUsageFlags>() | PropertyUsageFlags.ReadOnly;
            property["usage"] = (int)usage;
        }
    }
}

public event Action PropertyListChanged;

Emitted when ReckfellObject.NotifyPropertyListChanged is called.

public event Action ScriptChanged;

Emitted when the object's script is changed. Note: When this signal is emitted, the new script is not initialized yet. If you need to access the new script, defer connections to this signal with ReckfellObject.ConnectFlags.Deferred.

public const long NotificationExtensionReloaded = 2;

Notification received when the object finishes hot reloading. This notification is only sent for extensions classes and derived.

public const long NotificationPostinitialize = 0;

Notification received when the object is initialized, before its script is attached. Used internally.

public const long NotificationPredelete = 1;

Notification received when the object is about to be deleted. Can be used like destructors in object-oriented programming languages. This notification is sent in reversed order.