class Godot::Object

Overview

Base class for all Godot engine objects and extension classes. Provides identity, lifecycle dispatch hooks, and signal emission functionality.

Direct Known Subclasses

Defined in:

lapis/dsl/frame_arena_dsl.cr
lapis/gd_extras/node_queries.cr
libgodot/classes/object.cr
libgodot/extensions.cr
libgodot/extensions/primitives.cr
libgodot/generated/classes/classes_part1.cr
libgodot/variant.cr

Constant Summary

NOTIFICATION_EXTENSION_RELOADED = 2_i64
NOTIFICATION_POSTINITIALIZE = 0_i64
NOTIFICATION_PREDELETE = 1_i64

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from class Object

try?(&)
try? try?

Constructor Detail

def self.~ : self #

Class unary ~ returns typed instance looked up from active NodeContext (by name first, then searching children)


def self.create : self #

Class-level constructor returning a new native Godot instance


def self.create(&block : self -> ) : self #

Class-level constructor configuring a new native Godot instance in a block


def self.new(pointer : Pointer(Void) = Pointer(Void).null) #

def self.new(&block : self -> ) : self #

Instantiates a new native Godot object and configures it in a block


Class Method Detail

def self._godot_has_virtual_method(method_name : String) : Bool #

Checks if this object class overrides a generic virtual method.


def self.cast_to(obj : Object, type : T.class) : T forall T #

Class-level casting helper raising TypeCastError


def self.cast_to?(obj : Object, type : T.class) : T | Nil forall T #

Class-level casting helper


def self.find_script_info_for_node(node : Godot::Object) : NamedTuple(path: String, line: Int32, class_name: String, parent_name: String, is_tool: Bool) | Nil #

Resolves the Crystal script path, 1-based line number, class name, parent class, and tool flag for a SceneTree node


def self.find_script_location_for_class(target_cls : String) : Tuple(String, Int32) #

Discovers the .cr source file and 1-based line number corresponding to a custom node/resource class


def self.find_script_path_for_class(target_cls : String) : String #

Discovers a .cr source file corresponding to a custom node/class


def self.is_instance_id_valid(id : Int | UInt64) : Bool #

Checks if a 64-bit instance ID is currently valid in Godot's ObjectDB


def self.is_internal_or_brush_class?(cls_name : String) : Bool #

Returns true if the given class name is a built-in engine class, internal Lapis class, or UniBuilder brush class


Instance Method Detail

def ==(other : Godot::Object) : Bool #

Value equality based on Godot engine identity (instance ID, underlying pointer, or reference identity)


def ==(other : Nil) : Bool #

def _enter_tree : Void #

Lifecycle callback called when the node enters the tree hierarchy.


def _exit_tree : Void #

Lifecycle callback called when the node exits the tree hierarchy.


def _godot_bind_static_signals(force : Bool = false) : Void #

Binds declarative class-level on_signal and @[OnSignal] callbacks to StaticSignalTable slots. Invokes #_godot_bind_static_signals_impl synthesized by the node and gmodule macros.


def _godot_bind_static_signals_impl(tid : UInt64) : Void #

Internal hook overridden by node and gmodule macros to bind compile-time typed procs to StaticSignalTable.


def _godot_call_tool_button(button_name : String) : Void #

Dispatches inspector tool button clicks on this object.


def _godot_call_virtual(method_name : String, delta : Float64) : Void #

Virtual method and property dispatch hooks overridden by class registration macros. Delta timestep is received with 64-bit precision (Float64).


def _godot_call_virtual_with_data(method_name : String, args : Pointer(Pointer(Void)), ret : Pointer(Void)) : Void #

Dispatches generic virtual methods with raw arguments and return buffer.


def _godot_get_property(prop_name : String, ret_ptr : Pointer(Void)) : Void #

Invoked by the GDExtension bridge when retrieving an exposed @export property.


def _godot_set_property(prop_name : String, val_ptr : Pointer(Void)) : Void #

Invoked by the GDExtension bridge when setting an exposed @export property.


def _mark_destroyed_by_engine! : Void #

Internal helper invoked by Bridge free_fn when Godot C++ deallocates a Crystal object.


def _physics_process(delta : Float64) : Void #

Fixed-rate physics process callback receiving delta timestep in seconds (Float64).


def _process(delta : Float64) : Void #

Per-frame process callback receiving delta timestep in seconds (Float64).


def _ready : Void #

Lifecycle callback called when the node enters the active scene tree.


def ~ : self #

Instance unary ~ returns self, allowing ~self or nested unary chaining


def active? : Bool #

Returns true if the object is active and not destroyed (works in both engine and standalone unit specs)


def add_user_signal(signal : String, arguments : Pointer(Void)) : Void #

def alive? : Bool #

Returns true if this object instance has a valid engine pointer and is alive in Godot's ObjectDB


def as_a(type : T.class) : T forall T #

Re-wraps or downcasts this Godot object pointer to the requested Godot wrapper class T, raising TypeCastError if incompatible.


def as_a?(type : T.class) : T | Nil forall T #

Re-wraps or downcasts this Godot object pointer to the requested Godot wrapper class T, verifying that the underlying native object inherits from T. Returns nil if invalid or incompatible.


def as_g(type : T.class) : T forall T #

def as_g?(type : T.class) : T | Nil forall T #

Ergonomic aliases for polymorphic downcasting


def as_t(type : T.class) : T forall T #

Shorthand alias matching Variant#as_t(T)


def as_t?(type : T.class) : T | Nil forall T #

Shorthand alias for as_t?(T)


def await_signal(signal_name : String | Symbol, timeout_sec : Float64 | Nil = nil) : AwaitStatus(Array(Variant)) #

Cooperatively awaits a signal emitted on this object. Returns AwaitStatus(Array(Variant)) indicating completion or timeout.


def await_signal(signal_name : String | Symbol, timeout_sec : Number) : AwaitStatus(Array(Variant)) #

def await_signal!(signal_name : String | Symbol, timeout_sec : Float64 | Nil = nil) : Array(Variant) #

Cooperatively awaits a signal emitted on this object, raising TimeoutError if timeout expires.


def await_signal!(signal_name : String | Symbol, timeout_sec : Number) : Array(Variant) #

def await_signal?(signal_name : String | Symbol, timeout_sec : Float64 | Nil = nil) : Array(Variant) | Nil #

Cooperatively awaits a signal emitted on this object, returning nil if timeout expires.


def await_signal?(signal_name : String | Symbol, timeout_sec : Number) : Array(Variant) | Nil #

def bind_property_list_changed(callback : Proc(R), once : Bool = false) : UInt64 forall R #

def bind_property_list_changed(once : Bool = false, &block : -> Void) : UInt64 #

def bind_script_changed(callback : Proc(R), once : Bool = false) : UInt64 forall R #

def bind_script_changed(once : Bool = false, &block : -> Void) : UInt64 #

def bind_static_signal(signal_name : String, callback : Proc(*T, R), once : Bool = false) : UInt64 forall T, R #

Binds a compile-time typed Proc(*T, R) directly to this object's StaticSignalTable slot.


def bind_static_signal(signal_name : Symbol, callback : Proc(*T, R), once : Bool = false) : UInt64 forall T, R #

Binds a compile-time typed Proc(*T, R) directly to this object's StaticSignalTable slot (Symbol overload).


def blocking_signals? : Bool #

Predicate alias for #is_blocking_signals


def build(&block : self -> Void) : self #

Fluent inline configuration block yielding self and returning self


def call(method : String, args : Array(Variant)) : Pointer(Void) #

Calls the named method on the object with an array of Variants.


def call(method : String, *args) : Pointer(Void) #

Calls the named method on the object with variable arguments.


def call_bool(method : String, *args) : Bool #

Calls the named method and returns the result as Bool


def call_deferred(method : String, *args) : Pointer(Void) #

Calls the named method on the object during idle time.


def call_f64(method : String, *args) : Float64 #

Calls the named method and returns the result as Float64


def call_i64(method : String, *args) : Int64 #

Calls the named method and returns the result as Int64


def call_obj(method : String, *args) : Node | Nil #

Calls the named method and returns an Object/Node (or nil if null)


def call_obj_as(type : T.class, method : String, *args) : T | Nil forall T #

Calls the named method and returns the result cast to T (or nil if null)


def call_str(method : String, *args) : String #

Calls the named method and returns the result as String


def callv(method : String, arg_array : Pointer(Void)) : Pointer(Void) #

def can_translate_messages : Bool #

def can_translate_messages? : Bool #

Predicate alias for #can_translate_messages


def cancel_free : Void #

def cast_to(type : T.class) : T forall T #

Shorthand alias for as_a(T)


def cast_to?(type : T.class) : T | Nil forall T #

Shorthand alias for as_a?(T)


def check_alive! : Void #

Validates that the underlying engine object is still alive before executing bridge calls. Raises DisposedObjectError if the object was destroyed by GDScript, engine, or Crystal.


def class?(godot_class : String) : Bool #

Predicate alias for #is_class


def configure(&block : self -> Void) : self #

Fluent configuration block alias


def connect(signal_name : String, flags : Godot::ConnectFlags = ::Godot::ConnectFlags::None, callback : Proc(Array(Variant), Void) | Nil = nil, receiver : Godot::Object | Nil = nil) : SignalSubscription #

Connects a callback proc to the named signal.


def connect(signal_name : String, flags : Godot::ConnectFlags = ::Godot::ConnectFlags::None, receiver : Godot::Object | Nil = nil, &block : Array(Variant) -> Void) : SignalSubscription #

Connects a callback block accepting Array(Variant) to the named signal.


def connect(signal_name : Symbol, flags : Godot::ConnectFlags = ::Godot::ConnectFlags::None, &block : Array(Variant) -> Void) : SignalSubscription #

Connects a callback block to the named signal symbol.


def connect(signal_name : String, listener_target : Godot::Object, method_name : Symbol, flags : Godot::ConnectFlags = ::Godot::ConnectFlags::None) : SignalSubscription #

Connects the named signal to a method call on a listener target by symbol name.


def connect(signal : String, callable : Pointer(Void), flags : Int64 = 0_i64) : Godot::Error #

def connect_one_shot(signal_name : String, &block : Array(Variant) -> Void) : SignalSubscription #

Connects a one-shot callback block to the named signal (backwards compatibility).


def connected?(signal : String, callable : Pointer(Void)) : Bool #

Predicate alias for #is_connected


def destroy : Void #

Destroys this Object in the Godot engine and invalidates the Crystal pointer.


def destroyed? : Bool #

def disconnect(signal : String, callable : Pointer(Void)) : Void #

def disconnect(signal_name : String) : Void #

Disconnects all signal subscriptions for the named signal on this object.


def disconnect(signal_name : Symbol) : Void #

Disconnects all subscriptions for the specified signal (Symbol overload)


def disconnect_all(signal_name : String | Symbol) : self #

Disconnects all subscriptions for the specified signal, returning self


def disconnect_all : self #

Disconnects all subscriptions across ALL signals on this object, returning self


def editor_hint? : Bool #

Returns true if running inside the Godot Editor


def emit(signal_name : String | Symbol, *args) : self #

Emits the named signal with arguments, returning self


def emit(signal : BoundSignal, *args) : self #

Emits a bound or typed signal with arguments, returning self


def emit_property_list_changed : Void #

def emit_script_changed : Void #

def emit_signal(name : String) : Void #

Emits a parameterless signal on this Godot object with zero GC heap allocations.


def emit_signal(name : String, *args) : Void #

Emits a signal with variable arguments on this Godot object.


def emit_static_signal(signal_name : String, *args : *T) : Int32 forall T #

Emits a typed signal directly through StaticSignalTable.global with zero GC heap allocations.


def emit_static_signal(signal_name : Symbol, *args : *T) : Int32 forall T #

Emits a typed signal directly through StaticSignalTable.global (Symbol overload).


def explicitly_freed? : Bool #

def frame_arena : Lapis::Core::FrameArena #

Returns the active Lapis::Core::FrameArena scratchpad for the current frame.


def frame_buffer(type : T.class, max_elements : Int32) : Lapis::Core::ArenaBuffer(T) forall T #

Allocates a per-frame appendable ArenaBuffer(T) of max_elements from FrameArena.current.


def frame_scope(&block : Lapis::Core::FrameArena -> _) #

Executes a temporary scratch allocation scope on the current FrameArena that automatically rewinds when the block finishes.


def frame_slice(type : T.class, count : Int32) : Slice(T) forall T #

Allocates a per-frame scratch Slice(T) of count elements from FrameArena.current.


def free : Void #

Destroys this Object in the Godot engine (alias to #destroy).


def get(property : String) : Pointer(Void) #

def get_class : String #

def get_incoming_connections : Pointer(Void) #

def get_indexed(property_path : NodePath | String) : Pointer(Void) #

def get_instance_id : Int64 #

def get_meta(name : String, default : Pointer(Void) | Nil = nil) : Pointer(Void) #

def get_meta(key : Symbol, default : Pointer(Void) | Nil = nil) : Pointer(Void) #

def get_meta(name : String, default : Pointer(Void) | Nil = nil) : Pointer(Void) #

def get_meta(name : String, default : Pointer(Void) | Nil = nil) : Pointer(Void) #

Overrides auto-generated raw Pointer(Void) metadata getter to avoid passing an 8-byte stack Void* as a 24-byte Variant default argument in godot_ptrcall.


def get_meta(key : Symbol, default : Pointer(Void) | Nil = nil) : Pointer(Void) #

def get_meta(name : String, default : Pointer(Void) | Nil = nil) : Pointer(Void) #

def get_meta_color(key : String | Symbol) : Color #

def get_meta_f64(key : String | Symbol) : Float64 #

Retrieves floating-point metadata stored on this object as a Float64.

Example:

multiplier = node.get_meta_f64(:difficulty_multiplier)

def get_meta_i64(key : String | Symbol) : Int64 #

Retrieves integer metadata stored on this object as an Int64.

Example:

tier = node.get_meta_i64(:enemy_tier)

def get_meta_list : Pointer(Void) #

def get_meta_str(key : String | Symbol) : String #

Retrieves string metadata stored on this object.

Example:

id = node.get_meta_str(:spawner_id)

def get_meta_transform3d(key : String | Symbol) : Transform3D #

def get_meta_vector2(key : String | Symbol) : Vector2 #

def get_meta_vector3(key : String | Symbol) : Vector3 #

def get_method_argument_count(method : String) : Int64 #

def get_method_list : Pointer(Void) #

def get_property_list : Pointer(Void) #

def get_script : Pointer(Void) #

def get_signal_connection_list(signal : String) : Pointer(Void) #

def get_signal_list : Pointer(Void) #

def get_translation_domain : String #

def godot_as(type : T.class) : T forall T #

def godot_as?(type : T.class) : T | Nil forall T #

def has_connections(signal : String) : Bool #

def has_connections?(signal : String) : Bool #

Predicate alias for #has_connections


def has_meta(name : String) : Bool #

def has_meta(key : String | Symbol) : Bool #

Returns true if this object has metadata stored under key.

Example:

if node.has_meta(:quest_target)
  highlight_target(node)
end

def has_meta?(name : String) : Bool #

Predicate alias for #has_meta


def has_method(method : String) : Bool #

def has_method?(method : String) : Bool #

Predicate alias for #has_method


def has_signal(signal : String) : Bool #

def has_signal?(signal_name : String) : Bool #

Returns true if this object or its registered class defines the given signal.


def has_user_signal(signal : String) : Bool #

def has_user_signal?(signal : String) : Bool #

Predicate alias for #has_user_signal


def hash(hasher) #

Hashing based on engine instance ID for use in Sets and Hash keys


def if_alive : self | Nil #

Convenient nil-coalescing helper: returns self if alive, otherwise nil


def inspect(io : IO) : Void #
Description copied from class Reference

Appends a String representation of this object which includes its class name, its object address and the values of all instance variables.

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).inspect # => #<Person:0x10fd31f20 @name="John", @age=32>

def instance_id : UInt64 #

def is_blocking_signals : Bool #

def is_blocking_signals? : Bool #

Predicate alias for #is_blocking_signals


def is_class(godot_class : String) : Bool #

def is_class?(godot_class : String) : Bool #

Predicate alias for #is_class


def is_connected(signal : String, callable : Pointer(Void)) : Bool #

def is_connected?(signal : String, callable : Pointer(Void)) : Bool #

Predicate alias for #is_connected


def is_queued_for_deletion : Bool #

def is_queued_for_deletion? : Bool #

Predicate alias for #is_queued_for_deletion


def is_valid? : Bool #

def link_class_script : Void #

Automatically links this node's registered CrystalScript resource if running inside the Godot Editor


def not_null? : Bool #

Returns true if the underlying engine pointer is non-null and currently valid


def notification(what : Int64, reversed : Bool = false) : Void #

def notify_property_list_changed : Void #

def null? : Bool #

Returns true if the underlying engine pointer is null or invalid


def pointer : Pointer(Void) #

def pointer=(val : Pointer(Void)) #

def print(*args) #

Prints a message to Godot's debug console.


def printerr(*args) #

Prints an error message to Godot's error console.


def property_can_revert(property : String) : Bool #

def property_can_revert?(property : String) : Bool #

Predicate alias for #property_can_revert


def property_get_revert(property : String) : Pointer(Void) #

def property_list_changed : Godot::TypedSignal() #

def property_list_changed=(val : Godot::BoundSignal) : Godot::BoundSignal #

Identity setter enabling compound operator sugar (node.property_list_changed += ->handler, node.property_list_changed -= ->handler)


def property_list_changed_signal_hash : UInt64 #

def property_list_changed_slot : Lapis::Core::StaticSignalSlot() #

def puts(*args) #

Prints a message to Godot's debug console.


def queued_for_deletion? : Bool #

Predicate alias for #is_queued_for_deletion


def queued_for_deletion_fast? : Bool #

Fast check if this object is queued for deletion (queue_free) or already destroyed.


def rebind_static_signals! : Void #

Explicitly rebinds all declarative on_signal and @[OnSignal] callbacks to StaticSignalTable slots.


def remove_meta(name : String) : Void #

def remove_meta(key : String | Symbol) : Void #

Removes the metadata entry under key from this object.

Example:

node.remove_meta(:temporary_status)

def remove_user_signal(signal : String) : Void #

def script_changed : Godot::TypedSignal() #

def script_changed=(val : Godot::BoundSignal) : Godot::BoundSignal #

Identity setter enabling compound operator sugar (node.script_changed += ->handler, node.script_changed -= ->handler)


def script_changed_signal_hash : UInt64 #

def script_changed_slot : Lapis::Core::StaticSignalSlot() #

def set(property : String, value : Pointer(Void)) : Void #

def set(property : String | Symbol, value : T) : Void forall T #

Dynamically sets a property value on this object.


def set_block_signals(enable : Bool) : Void #

def set_deferred(property : String, value : Pointer(Void)) : Void #

def set_indexed(property_path : NodePath | String, value : Pointer(Void)) : Void #

def set_message_translation(enable : Bool) : Void #

def set_meta(key : String | Symbol, value : String | Int32 | Int64 | Float32 | Float64 | Bool | Symbol | Vector2 | Vector2i | Vector3 | Vector3i | Color | Transform3D | Basis | AABB | Quaternion | Plane | Rect2) : Void #

Sets arbitrary metadata on this object with automatic Variant conversion.

Supports both String and Symbol keys.

Example:

node.set_meta(:enemy_tier, 3)
node.set_meta("spawner_id", "wave_01")

def set_meta(key : String | Symbol, value : Godot::Object) : Void #

def set_meta(name : String, value : Pointer(Void)) : Void #

Overrides auto-generated raw Pointer(Void) metadata setter so value is stored safely as a 64-bit integer address via Variant::INT rather than passing an 8-byte stack Void* to godot_ptrcall_void expecting a 24-byte Variant.


def set_meta(key : Symbol, value : Pointer(Void)) : Void #

def set_meta(key : String | Symbol, value : Variant) : Void #

def set_script(script : Pointer(Void)) : Void #

def set_translation_domain(domain : String) : Void #

def signal(name : String) : Godot::BoundSignal #

Returns a bound signal representation for the named signal. Enables idiomatic usage: enemy.signal("died").await or button.signal(:pressed).connect { ... }.


def signal(sym : Symbol) : Godot::BoundSignal #

Returns a bound signal representation for the named signal symbol.


def signal_connection_count(signal_name : String) : Int32 #

Returns the count of active subscriptions for the given signal on this object.


def signal_target_id : UInt64 #

Identifier used for signal routing and lifecycle tracking (engine instance ID or Crystal object_id)


def static_signal_slot(signal_name : String, *types : *T) forall T #

Returns a compile-time typed StaticSignalSlot(*T) bound to this object in StaticSignalTable.global.


def static_signal_slot(signal_name : Symbol, *types : *T) forall T #

Returns a compile-time typed StaticSignalSlot(*T) bound to this object by symbol name.


def to_s(io : IO) : Void #
Description copied from class Reference

Appends a short String representation of this object which includes its class name and its object address.

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).to_s # => #<Person:0x10a199f20>

def to_string : String #

def to_unsafe : Pointer(Void) #

Idiomatic Crystal pointer conversion


def tr(message : String, context : String = "") : String #

def tr_n(message : String, plural_message : String, n : Int64, context : String = "") : String #

def try? : self | Nil #

Safe nil-coalescing check: returns self if alive in Godot's ObjectDB, otherwise nil.


def try?(&) #

Evaluates the given block with self if this object is alive and valid in Godot's ObjectDB. Returns nil if this object has been destroyed or freed, preventing dead pointer crashes.


def unbind_property_list_changed(callback : Proc(R)) : Bool forall R #

def unbind_property_list_changed(token : UInt64) : Bool #

def unbind_script_changed(callback : Proc(R)) : Bool forall R #

def unbind_script_changed(token : UInt64) : Bool #

def unbind_static_signal(signal_name : String, callback : Proc(*T, R)) : Bool forall T, R #

Unbinds a matching compile-time typed Proc(*T, R) from this object's StaticSignalTable slot.


def unbind_static_signal(signal_name : Symbol, callback : Proc(*T, R)) : Bool forall T, R #

Unbinds a matching compile-time typed Proc(*T, R) from this object's StaticSignalTable slot (Symbol overload).


def unbind_static_signal(token : UInt64) : Bool #

Unbinds a StaticSignalTable listener token.