Trait gdnative_core::object::GodotObject

pub unsafe trait GodotObject: Sized + Sealed {
    type RefKind: RefKind;
    fn class_name() -> &'static str;

    fn null() -> Null<Self> { ... }
    fn new() -> Ref<Self, Unique>
    where
        Self: Instanciable,
    { ... }
    fn cast<T>(&self) -> Option<&T>
    where
        T: GodotObject + SubClass<Self>,
    { ... }
    fn upcast<T>(&self) -> &T
    where
        T: GodotObject,
        Self: SubClass<T>,
    { ... }
    unsafe fn assume_shared(&self) -> Ref<Self, Shared>
    where
        Self: Sized,
    { ... }
    unsafe fn assume_thread_local(&self) -> Ref<Self, ThreadLocal>
    where
        Self: Sized + GodotObject<RefKind = RefCounted>,
    { ... }
    unsafe fn assume_unique(&self) -> Ref<Self, Unique>
    where
        Self: Sized,
    { ... }
    unsafe fn try_from_instance_id<'a>(
        id: i64
    ) -> Option<TRef<'a, Self, Shared>> { ... }
    unsafe fn from_instance_id<'a>(id: i64) -> TRef<'a, Self, Shared> { ... }
}

Trait for Godot API objects. This trait is sealed, and implemented for generated wrapper types.

Bare GodotObject references, like &Node, can be used safely, but do not track thread access states, which limits their usefulness to some extent. It's not, for example, possible to pass a &Node into an API method because it might have came from a Unique reference. As such, it's usually better to use Ref and TRefs whenever possible.

For convenience. it's possible to use bare references as owner arguments in exported methods when using NativeScript, but the limitations above should be kept in mind. See the OwnerArg for more information.

IF it's ever needed to obtain persistent references out of bare references, the assume_ methods can be used.

Associated Types

type RefKind: RefKind

The memory management kind of this type. This modifies the behavior of the Ref smart pointer. See its type-level documentation for more information.

Loading content...

Required methods

fn class_name() -> &'static str

Loading content...

Provided methods

fn null() -> Null<Self>

Creates an explicitly null reference of Self as a method argument. This makes type inference easier for the compiler compared to Option.

fn new() -> Ref<Self, Unique> where
    Self: Instanciable, 

Creates a new instance of Self using a zero-argument constructor, as a Unique reference.

fn cast<T>(&self) -> Option<&T> where
    T: GodotObject + SubClass<Self>, 

Performs a dynamic reference downcast to target type.

The cast method can only be used for downcasts. For statically casting to a supertype, use upcast instead.

This method is only for conversion between engine types. To downcast to a NativeScript type from its base type, see Ref::cast_instance and TRef::cast_instance.

fn upcast<T>(&self) -> &T where
    T: GodotObject,
    Self: SubClass<T>, 

Performs a static reference upcast to a supertype that is guaranteed to be valid.

This is guaranteed to be a no-op at runtime.

unsafe fn assume_shared(&self) -> Ref<Self, Shared> where
    Self: Sized, 

Creates a persistent reference to the same Godot object with shared thread access.

Safety

There must not be any Unique or ThreadLocal references of the object when this is called. This causes undefined behavior otherwise.

unsafe fn assume_thread_local(&self) -> Ref<Self, ThreadLocal> where
    Self: Sized + GodotObject<RefKind = RefCounted>, 

Creates a persistent reference to the same Godot object with thread-local thread access.

Safety

There must not be any Unique or Shared references of the object when this is called. This causes undefined behavior otherwise.

unsafe fn assume_unique(&self) -> Ref<Self, Unique> where
    Self: Sized, 

Creates a persistent reference to the same Godot object with unique access.

Safety

Use with care. Unique is a very strong assumption that can easily be violated. Only use this when you are absolutely sure you have the only reference.

There must be no other references of the object when this is called. This causes undefined behavior otherwise.

unsafe fn try_from_instance_id<'a>(id: i64) -> Option<TRef<'a, Self, Shared>>

Recovers a instance ID previously returned by Object::get_instance_id if the object is still alive. See also TRef::try_from_instance_id.

Safety

During the entirety of 'a, the thread from which try_from_instance_id is called must have exclusive access to the underlying object, if it is still alive.

unsafe fn from_instance_id<'a>(id: i64) -> TRef<'a, Self, Shared>

Recovers a instance ID previously returned by Object::get_instance_id if the object is still alive, and panics otherwise. This does NOT guarantee that the resulting reference is safe to use.

Panics

Panics if the given id refers to a destroyed object. For a non-panicking version, see try_from_instance_id.

Safety

During the entirety of 'a, the thread from which try_from_instance_id is called must have exclusive access to the underlying object, if it is still alive.

Loading content...

Implementors

Loading content...