Struct OnEditor

pub struct OnEditor<T> { /* private fields */ }

Exported property that must be initialized in the editor (or associated code) before use.

Allows to use Gd<T>, which by itself never holds null objects, as an #[export] that should not be null during runtime. As such, it can be used as a more ergonomic way of Option<Gd<T>> which assumes initialization.

Panics during access if uninitialized. When used inside a node class, OnEditor checks if a value has been set before ready() is run, and panics otherwise. Once initialized, it can be used almost as if it was a T value itself, due to Deref/DerefMut impls.

OnEditor<T> should always be used as a property, preferably in tandem with an #[export] or #[var]. Initializing OnEditor values via code before the first use is supported but should be limited to use cases involving builder or factory patterns.

Option<Gd<T>> and OnReady<Gd<T>> should be used for any other late initialization logic.

Using OnEditor<T> with Gd<T> and DynGd<T, D>

Example - auto-generated init

 use godot::prelude::*;

#[derive(GodotClass)]
#[class(init, base = Node)]
struct MyClass {
    #[export]
    editor_property: OnEditor<Gd<Resource>>,
}

#[godot_api]
impl INode for MyClass {
    fn ready(&mut self) {
        // Will always be valid and **must** be set via editor.
        // Additional check is being run before ready()
        // to ensure that given value can't be null.
        let some_variant = self.editor_property.get_meta("SomeName");
    }
}

Example - user-generated init

Uninitialized OnEditor<Gd<T>> and OnEditor<DynGd<T, D>> can be created with OnEditor<...>::default().

 use godot::prelude::*;

#[derive(GodotClass)]
#[class(base = Node)]
struct MyClass {
    #[export]
    required_node: OnEditor<Gd<Node>>,

    base: Base<Node>
}

#[godot_api]
impl INode for MyClass {
    fn init(base: Base<Node>) -> Self {
       Self {
           base,
           required_node: OnEditor::default(),
       }
    }
}

Example - factory pattern

use godot::prelude::*;

#[derive(GodotClass)]
#[class(init, base = Node)]
struct SomeClass {
    #[export]
    required_node: OnEditor<Gd<Node>>,
}

fn create_and_add(
    mut this: Gd<Node>,
    some_class_scene: Gd<PackedScene>,
    some_node: Gd<Node>,
) -> Gd<SomeClass> {
    let mut my_node = some_class_scene.instantiate_as::<SomeClass>();

    // Would cause the panic:
    // this.add_child(&my_node);

    // Note: Remember that nodes are manually managed.
    // They will leak memory if not added to tree and/or pruned.
    my_node.bind_mut().required_node.init(some_node);

    // Will not cause the panic.
    this.add_child(&my_node);

    my_node
}

Using OnEditor<T> with other GodotTypes

OnEditor<T> can be used with other built-ins to provide extra validation logic and making sure that given properties has been set. Example usage might be checking if entities has been granted properly generated id.

In such cases the value which will be deemed invalid must be specified with #[init(uninit = val)]. Given val will be used to represent uninitialized OnEditor<T> in the Godot editor. Accessing uninitialized value will cause the panic.

Example - using OnEditor with primitives

 use godot::prelude::*;

#[derive(GodotClass)]
#[class(init, base = Node)]
struct SomeClassThatCanBeInstantiatedInCode {
    // Uninitialized value will be represented by `42` in the editor.
    // Will cause panic if not set via the editor or code before use.
    #[export]
    #[init(invalid = 42)]
    some_primitive: OnEditor<i64>,
}

fn create_and_add(mut this: Gd<Node>, val: i64) -> Gd<SomeClassThatCanBeInstantiatedInCode> {
    let mut my_node = SomeClassThatCanBeInstantiatedInCode::new_alloc();

    // Would cause the panic:
    // this.add_child(&my_node);

    my_node.bind_mut().some_primitive.init(val);

    // Will not cause the panic.
    this.add_child(&my_node);

    my_node
}

Implementations

impl<T> OnEditor<T>

where T: GodotConvert + FromGodot + PartialEq,

pub fn init(&mut self, val: T)

Initializes invalid OnEditor<T> with given value.

Panics

If init() was called before.

pub fn new_invalid(val: T) -> OnEditor<T>

where T: BuiltinExport,

Creates new OnEditor<T> with a value that is considered invalid.

If this value is not changed in the editor, accessing it from Rust will cause a panic.

Trait Implementations

impl<T, D> Default for OnEditor<DynGd<T, D>>

where T: GodotClass, D: 'static + ?Sized,

fn default() -> OnEditor<DynGd<T, D>>

Returns the “default value” for a type.

impl<T> Default for OnEditor<Gd<T>>

where T: GodotClass,

fn default() -> OnEditor<Gd<T>>

Returns the “default value” for a type.

impl<T> Deref for OnEditor<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &<OnEditor<T> as Deref>::Target

Dereferences the value.

impl<T> DerefMut for OnEditor<T>

fn deref_mut(&mut self) -> &mut <OnEditor<T> as Deref>::Target

Mutably dereferences the value.

impl<T, D> Export for OnEditor<DynGd<T, D>>

where T: GodotClass<Exportable = Yes, Declarer = DeclEngine> + Bounds, OnEditor<DynGd<T, D>>: Var, D: 'static + ?Sized,

#[export] for OnEditor<DynGd<T, D>> is available only for T being Engine class (such as Node or Resource).

Consider exporting OnEditor<Gd<T>> instead of OnEditor<DynGd<T, D>> for user-declared GDExtension classes.

fn export_hint() -> PropertyHintInfo

The export info to use for an exported field of this type, if no other export info is specified.

impl<T> Export for OnEditor<Gd<T>>

where T: GodotClass<Exportable = Yes> + Bounds, OnEditor<Gd<T>>: Var,

fn export_hint() -> PropertyHintInfo

The export info to use for an exported field of this type, if no other export info is specified.

impl<T> Export for OnEditor<T>

where OnEditor<T>: Var, T: GodotConvert<Via = T> + BuiltinExport + Export,

fn export_hint() -> PropertyHintInfo

The export info to use for an exported field of this type, if no other export info is specified.

impl<T, D> GodotConvert for OnEditor<DynGd<T, D>>

where T: GodotClass, D: ?Sized,

type Via = Option<<DynGd<T, D> as GodotConvert>::Via>

The type through which Self is represented in Godot.

impl<T> GodotConvert for OnEditor<Gd<T>>

where T: GodotClass, Option<<Gd<T> as GodotConvert>::Via>: GodotType,

type Via = Option<<Gd<T> as GodotConvert>::Via>

The type through which Self is represented in Godot.

impl<T> GodotConvert for OnEditor<T>

where T: GodotType<Via = T> + GodotConvert + BuiltinExport,

type Via = <T as GodotConvert>::Via

The type through which Self is represented in Godot.

impl<T, D> Var for OnEditor<DynGd<T, D>>

where T: GodotClass, D: 'static + ?Sized,

fn get_property(&self) -> <OnEditor<DynGd<T, D>> as GodotConvert>::Via

fn set_property(&mut self, value: <OnEditor<DynGd<T, D>> as GodotConvert>::Via)

fn var_hint() -> PropertyHintInfo

Specific property hints, only override if they deviate from GodotType::property_info, e.g. for enums/newtypes.

impl<T> Var for OnEditor<Gd<T>>

where T: GodotClass, OnEditor<Gd<T>>: GodotConvert<Via = Option<<Gd<T> as GodotConvert>::Via>>,

fn get_property(&self) -> <OnEditor<Gd<T>> as GodotConvert>::Via

fn set_property(&mut self, value: <OnEditor<Gd<T>> as GodotConvert>::Via)

fn var_hint() -> PropertyHintInfo

Specific property hints, only override if they deviate from GodotType::property_info, e.g. for enums/newtypes.

impl<T> Var for OnEditor<T>

where T: GodotConvert<Via = T> + BuiltinExport + Var + FromGodot + PartialEq, OnEditor<T>: GodotConvert<Via = T>,

fn get_property(&self) -> <OnEditor<T> as GodotConvert>::Via

fn set_property(&mut self, value: T)

fn var_hint() -> PropertyHintInfo

Specific property hints, only override if they deviate from GodotType::property_info, e.g. for enums/newtypes.

impl<T> BuiltinExport for OnEditor<T>