Struct BaseMut
pub struct BaseMut<'a, T>where
T: GodotClass,{ /* private fields */ }
Expand description
Mutable/exclusive reference guard for a Base
pointer.
This can be used to call methods on the base object of a Rust object, which takes &self
or &mut self
as the receiver.
See WithBaseField::base_mut()
for usage.
Methods from Deref<Target = Gd<<T as GodotClass>::Base>>§
pub fn bind(&self) -> GdRef<'_, T>
pub fn bind(&self) -> GdRef<'_, T>
Hands out a guard for a shared borrow, through which the user instance can be read.
The pattern is very similar to interior mutability with standard RefCell
.
You can either have multiple GdRef
shared guards, or a single GdMut
exclusive guard to a Rust
GodotClass
instance, independently of how many Gd
smart pointers point to it. There are runtime
checks to ensure that Rust safety rules (e.g. no &
and &mut
coexistence) are upheld.
Drop the guard as soon as you don’t need it anymore. See also Bind guards.
§Panics
- If another
Gd
smart pointer pointing to the same Rust instance has a liveGdMut
guard bound. - If there is an ongoing function call from GDScript to Rust, which currently holds a
&mut T
reference to the user instance. This can happen through re-entrancy (Rust -> GDScript -> Rust call).
pub fn bind_mut(&mut self) -> GdMut<'_, T>
pub fn bind_mut(&mut self) -> GdMut<'_, T>
Hands out a guard for an exclusive borrow, through which the user instance can be read and written.
The pattern is very similar to interior mutability with standard RefCell
.
You can either have multiple GdRef
shared guards, or a single GdMut
exclusive guard to a Rust
GodotClass
instance, independently of how many Gd
smart pointers point to it. There are runtime
checks to ensure that Rust safety rules (e.g. no &mut
aliasing) are upheld.
Drop the guard as soon as you don’t need it anymore. See also Bind guards.
§Panics
- If another
Gd
smart pointer pointing to the same Rust instance has a liveGdRef
orGdMut
guard bound. - If there is an ongoing function call from GDScript to Rust, which currently holds a
&T
or&mut T
reference to the user instance. This can happen through re-entrancy (Rust -> GDScript -> Rust call).
pub fn instance_id(&self) -> InstanceId
pub fn instance_id(&self) -> InstanceId
⚠️ Returns the instance ID of this object (panics when dead).
§Panics
If this object is no longer alive (registered in Godot’s object database).
pub fn instance_id_unchecked(&self) -> InstanceId
pub fn instance_id_unchecked(&self) -> InstanceId
Returns the last known, possibly invalid instance ID of this object.
This function does not check that the returned instance ID points to a valid instance!
Unless performance is a problem, use instance_id()
instead.
This method is safe and never panics.
pub fn is_instance_valid(&self) -> bool
pub fn is_instance_valid(&self) -> bool
Checks if this smart pointer points to a live object (read description!).
Using this method is often indicative of bad design – you should dispose of your pointers once an object is destroyed. However, this method exists because GDScript offers it and there may be rare use cases.
Do not use this method to check if you can safely access an object. Accessing dead objects is generally safe and will panic in a defined manner. Encountering such panics is almost always a bug you should fix, and not a runtime condition to check against.
pub fn upcast_ref<Base>(&self) -> &Base
pub fn upcast_ref<Base>(&self) -> &Base
Upcast shared-ref: access this object as a shared reference to a base class.
This is semantically equivalent to multiple applications of Self::deref()
. Not really useful on its own, but combined with
generic programming:
fn print_node_name<T>(node: &Gd<T>)
where
T: Inherits<Node>,
{
println!("Node name: {}", node.upcast_ref().get_name());
}
Note that this cannot be used to get a reference to Rust classes, for that you should use Gd::bind()
. For instance this
will fail:
#[derive(GodotClass)]
#[class(init, base = Node)]
struct SomeClass {}
#[godot_api]
impl INode for SomeClass {
fn ready(&mut self) {
let other = SomeClass::new_alloc();
let _ = other.upcast_ref::<SomeClass>();
}
}
pub fn upcast_mut<Base>(&mut self) -> &mut Base
pub fn upcast_mut<Base>(&mut self) -> &mut Base
Upcast exclusive-ref: access this object as an exclusive reference to a base class.
This is semantically equivalent to multiple applications of Self::deref_mut()
. Not really useful on its own, but combined with
generic programming:
fn set_node_name<T>(node: &mut Gd<T>, name: &str)
where
T: Inherits<Node>,
{
node.upcast_mut().set_name(name.into());
}
Note that this cannot be used to get a mutable reference to Rust classes, for that you should use Gd::bind_mut()
. For instance this
will fail:
#[derive(GodotClass)]
#[class(init, base = Node)]
struct SomeClass {}
#[godot_api]
impl INode for SomeClass {
fn ready(&mut self) {
let mut other = SomeClass::new_alloc();
let _ = other.upcast_mut::<SomeClass>();
}
}
pub fn callable<S>(&self, method_name: S) -> Callablewhere
S: Into<StringName>,
pub fn callable<S>(&self, method_name: S) -> Callablewhere
S: Into<StringName>,
Returns a callable referencing a method from this object named method_name
.
This is shorter syntax for Callable::from_object_method(self, method_name)
.