Migrate #[export] -> #[method] (#78)

Merging, now that gdnative 0.10.1 has been released.

Author: Bromeon

src/faq/code.md

@@ -30,10 +30,10 @@ struct MyNode {
 
 #[methods]
 impl MyNode {
-    #[export]
-    fn _ready(&self, owner: TRef<Node>) {
+    #[method]
+    fn _ready(&self, #[base] base: TRef<Node>) {
         let node = Node::new();
-        owner.add_child(node);
+        base.add_child(node);
         self.node_ref = Some(node.claim());
     }
 }
@@ -67,18 +67,20 @@ impl SignalEmitter {
         builder.signal("updated").done();
     }
 
-    fn new(_owner: &Node) -> Self {
+    fn new(_base: &Node) -> Self {
         SignalEmitter {
             data: "initial",
         }
     }
-    #[export]
-    fn update_data(&mut self, owner: TRef<Node>, data: LargeData) {
+    
+    #[method]
+    fn update_data(&mut self, #[base] base: TRef<Node>, data: LargeData) {
         self.data = data;
-        owner.emit_signal("updated", &[]);
+      base.emit_signal("updated", &[]);
     }
-    #[export]
-    fn get_data(&self, owner: TRef<Node>) -> &LargeData {
+    
+    #[method]
+    fn get_data(&self) -> &LargeData {
         &self.data
     }
 }
@@ -94,13 +96,14 @@ There are two ways to solve it.
 2. Store `data` in a `RefCell<LargeData>` if it should only be accessed from the same thread (such as with signals) or `Mutex<LargeData>` if you need thread-safety. Then you can modify `update_data()` to the following snippet:
 
 ```rust
-    fn update_data(&self, owner: TRef<Node>, data: LargeData) {
-        // If using RefCell
-        self.data.replace(data);
-        // If using Mutex
-        // *self.data.lock().expect("this should work") = data;
-        owner.emit_signal("updated", &[]);
-    }
+#[method]
+fn update_data(&self, #[base] base: TRef<Node>, data: LargeData) {
+    // If using RefCell
+    self.data.replace(data);
+    // If using Mutex
+    // *self.data.lock().expect("this should work") = data;
+    base.emit_signal("updated", &[]);
+}
 ```
 
 In both instances you will not encounter the reentrant errors.
@@ -128,9 +131,9 @@ One of the ways that godot-rust avoids large `unsafe` blocks is by using the [Ty
 Here is an example of some common `unsafe` usage that you will often see and use in your own games.
 
 ```rust
-fn get_a_node(&self, owner: TRef<Node>) {
+fn get_a_node(&self, #[base] base: TRef<Node>) {
     // This is safe because it returns an option that Rust knows how to check.
-    let child = owner.get_child("foo");
+    let child = base.get_child("foo");
     // This is safe because Rust panics if the returned `Option` is None.
     let child = child.expect("I know this should exist");
     // This is also safe because Rust panics if the returned `Option` is None.
@@ -177,14 +180,14 @@ struct Enemy {
 
 #[methods]
 impl Enemy {
-    fn new(_owner: &Object) -> Self {
+    fn new(_base: &Object) -> Self {
         Enemy {
             data: None,
         }
     }
 
-    #[export]
-    fn set_data(&mut self, _owner: &Object, name: String, health: f32) {
+    #[method]
+    fn set_data(&mut self, name: String, health: f32) {
         self.data = Some(EnemyData { name, health });
     }
 }
@@ -215,8 +218,8 @@ struct EntityFactory {}
 
 #[methods]
 impl EntityFactory {
-    #[export]
-    fn enemy(&self, _owner: &Reference, name: String, health: f32)
+    #[method]
+    fn enemy(&self, name: String, health: f32)
     -> Instance<Enemy, Unique> {
         Enemy { name, health }.emplace()
     }
@@ -240,8 +243,8 @@ pub struct StaticUtil;
 
 #[methods]
 impl StaticUtil {
-    #[export]
-    fn compute_something(&self, _owner: &Object, input: i32) -> i32 {
+    #[method]
+    fn compute_something(&self, input: i32) -> i32 {
         godot_print!("pseudo-static computation");
         2 * input
     }
@@ -277,8 +280,8 @@ pub struct AnotherNativeScript;
 
 #[methods]
 impl AnotherNativeScript {
-    #[export]
-    pub fn method_accepting_my_node(&self, _owner: &Reference, my_node: Variant) {
+    #[method]
+    pub fn method_accepting_my_node(&self, my_node: Variant) {
         // 1. Cast Variant to Ref of associated Godot type, and convert to TRef.
         let my_node = unsafe {
             my_node
@@ -294,7 +297,7 @@ impl AnotherNativeScript {
 
         // 3. Map over the RefInstance to process the underlying user data.
         my_node
-            .map(|my_node, _owner| {
+            .map(|my_node, _base| {
                 // Now my_node is of type MyNode2D.
             })
             .expect("Failed to map over my_node instance");
@@ -397,10 +400,10 @@ struct MyNode {
 
 #[methods]
 impl MyNode {
-    #[export]
-    fn _ready(&self, owner: TRef<Node>) {
+    #[method]
+    fn _ready(&self, #[base] base: TRef<Node>) {
         // Get an existing child node that is a Godot class.
-        let node2d = owner
+        let node2d = base
             .get_node("Node2D")
             .expect("this node must have a child with the path `Node2D`");
         let node2d = unsafe { node2d.assume_safe() };
@@ -409,7 +412,7 @@ impl MyNode {
         self.node2d = Some(node2d.claim());
 
         // Get an existing child node that is a Rust class.
-        let instance = owner
+        let instance = base
             .get_node("MyClass")
             .expect("this node must have a child with the path `MyClass`");
         let instance = unsafe { instance.assume_safe() };
@@ -447,7 +450,7 @@ For more information about the Godot profiler, please refer to the [official doc
 In order for Godot to profile your function, all the following must be true:
 - The function belongs to a struct that derives `NativeClass`.
 - The function is included in an `impl` block that is attributed with the `#[methods]` attribute.
-- The function is attributed with `#[export]` attribute.
+- The function is attributed with `#[method]` attribute.
 
 As such, this method is _only_ useful for exported code and is subject to the Godot profiler's limitations, such as millisecond accuracy in profiler metrics.
 
@@ -460,13 +463,13 @@ struct MyClass {}
 
 #[methods]
 impl MyClass {
-    fn new(_owner: &Node) -> Self {
+    fn new(_base: &Node) -> Self {
         Self {}
     }
 
-    #[export]
+    #[method]
     #[gdnative::profiled]
-    fn my_profiled_function(&self, _owner: &Node) {
+    fn my_profiled_function(&self, #[base] _base: &Node) {
         // Any code in this function will be profiled.
     }
 }

src/faq/configuration.md

@@ -85,7 +85,7 @@ Yes, any Rust struct that inherits from `NativeClass` can be also used as a tool
 stuct MyTool {}
 #[methods]
 impl MyTool {
-    fn new (_owner: &Node) -> Self {
+    fn new (_base: &Node) -> Self {
         Self {}
     }
 }

src/gdnative-overview/wrappers.md

@@ -78,7 +78,7 @@ pub struct Player {
 
 #[methods]
 impl Player {
-    fn new(_owner: &Reference) -> Self {
+    fn new(_base: &Reference) -> Self {
         Self {
             name: "New player".to_string(),
             score: 0

src/getting-started/hello-world.md

@@ -118,7 +118,7 @@ Unfortunately, this won't compile just yet: Rust will complain about the lack of
 // You may add any number of ordinary `impl` blocks as you want. However, ...
 impl HelloWorld {
     /// The "constructor" of the class.
-    fn new(_owner: &Node) -> Self {
+    fn new(_base: &Node) -> Self {
         HelloWorld
     }
 }
@@ -156,24 +156,24 @@ You can now run your project from the editor! If all goes correctly, it should l
 #[methods]
 impl HelloWorld {
 
-    // To make a method known to Godot, use the #[export] attribute.
+    // To make a method known to Godot, use the #[method] attribute.
     // In Godot, script "classes" do not actually inherit the parent class.
-    // Instead, they are "attached" to the parent object, called the "owner".
+    // Instead, they are "attached" to the parent object, called the "base".
     //
-    // In order to enable access to the owner, it is passed as the second
-    // argument to every single exposed method. As a result, all exposed
-    // methods MUST have `owner: &BaseClass` as their second arguments,
-    // before all other arguments in the signature.
-    #[export]
-    fn _ready(&self, _owner: &Node) {
+    // If access to the base instance is desired, the 2nd parameter can be
+    // annotated with #[base]. It must have type `&T` or `TRef<T>`, where `T`
+    // is the base type specified in #[inherit]. If you don't need this parameter,
+    // feel free to omit it entirely.
+    #[method]
+    fn _ready(&self, #[base] base: &Node) {
         // The `godot_print!` macro works like `println!` but prints to the Godot-editor
         // output tab as well.
-        godot_print!("Hello, world!");
+        godot_print!("Hello world from node {}!", base.to_string());
     }
 }
 ```
 
-Here, the `#[export]` attribute is used to tell godot-rust to expose your methods to Godot. In this case, we are overriding [`_ready`](https://docs.godotengine.org/en/stable/classes/class_node.html#class-node-method-ready) and printing a line of text.
+Here, the `#[method]` attribute is used to tell godot-rust to expose your methods to Godot. In this case, we are overriding [`_ready`](https://docs.godotengine.org/en/stable/classes/class_node.html#class-node-method-ready) and printing a line of text.
 
 Now, re-compile the crate using `cargo build` and copy the resulting binary to the Godot project. Launch the project from the editor, and you should see `Hello, world!` in the Godot console!
 

src/recipes/async-tokio.md

@@ -61,7 +61,7 @@ struct AsyncExecutorDriver {
 }
 
 impl AsyncExecutorDriver {
-	fn new(_owner: &Node) -> Self {
+	fn new(_base: &Node) -> Self {
 		AsyncExecutorDriver {
 			runtime: Builder::new_current_thread()
 				.enable_io() 	// optional, depending on your needs
@@ -78,8 +78,8 @@ In the `_process` call of our `AsyncExecutorDriver`, we can block on `run_until`
 ```rust
 #[methods]
 impl AsyncExecutorDriver {
-	#[export]
-	fn _process(&self, _owner: &Node, _delta: f64) {
+	#[method]
+	fn _process(&self, #[base] _base: &Node, _delta: f64) {
 		EXECUTOR.with(|e| {
 			self.runtime
 				.block_on(async {

src/recipes/logging.md

@@ -134,24 +134,24 @@ impl DebugLogger {
     fn new(_: &Node) -> Self {
         Self {}
     }
-    #[export]
-    fn error(&self, _owner: &Node, target: String, message: String) {
+    #[method]
+    fn error(&self, target: String, message: String) {
         log::error!(target: &target, "{}", message);
     }
-    #[export]
-    fn warn(&self, _: &Node, target: String, message: String) {
+    #[method]
+    fn warn(&self, target: String, message: String) {
         log::warn!(target: &target, "{}", message);
     }
-    #[export]
-    fn info(&self, _: &Node, target: String, message: String) {
+    #[method]
+    fn info(&self, target: String, message: String) {
         log::info!(target: &target, "{}", message);
     }
-    #[export]
-    fn debug(&self, _: &Node, target: String, message: String) {
+    #[method]
+    fn debug(&self, target: String, message: String) {
         log::debug!(target: &target, "{}", message);
     }
-    #[export]
-    fn trace(&self, _: &Node, target: String, message: String) {
+    #[method]
+    fn trace(&self, target: String, message: String) {
         log::trace!(target: &target, "{}", message);
     }
 }

src/rust-binding/calling-gdscript.md

@@ -36,8 +36,8 @@ pub struct Enemy {
 
 #[methods]
 impl Enemy {
-    #[export]
-    fn _to_string(&self, _owner: &Reference) -> String {
+    #[method]
+    fn _to_string(&self) -> String {
         format!("{:?}", self) // calls Debug::fmt()
     }
 }
@@ -51,16 +51,13 @@ fn init(handle: InitHandle) {
 ```
 Now, it's not possible to directly return `Enemy` instances in exported methods, so this won't work:
 ```rust
-#[export]
-fn create_enemy(&mut self, _owner: &Node) -> Enemy {...}
+#[method]
+fn create_enemy(&mut self) -> Enemy {...}
 ```
 Instead, you can wrap the object in a `Instance<Enemy, Unique>`, using `emplace()`. For an in-depth explanation of the `Instance` class, read [this section](../gdnative-overview/wrappers.md#instance-reference-with-attached-rust-class).
 ```rust
-#[export]
-fn create_enemy(
-    &self,
-    _owner: &Node
-) -> Instance<Enemy, Unique> {
+#[method]
+fn create_enemy(&self) -> Instance<Enemy, Unique> {
     let enemy = Enemy {
         pos: Vector2::new(7.0, 2.0),
         health: 100.0,
@@ -177,7 +174,7 @@ When calling GDScript functions from Rust, a few things need to be kept in mind.
 
 **Safety:** Since the calls are dynamic, it is possible to invoke any other functions through them, including unsafe ones like `free()`. As a result, `call()` and its alternatives are unsafe.
 
-**Re-entrancy:** When calling from Rust to GDScript, your Rust code is usually already running in an exported `#[export]` method, meaning that it has bound its receiver object via `&T` or `&mut T` reference. In the GDScript code, you must not invoke any method on the same Rust receiver, which would violate safety rules (aliasing of `&mut`).
+**Re-entrancy:** When calling from Rust to GDScript, your Rust code is usually already running in an exported `#[method]` method, meaning that it has bound its receiver object via `&T` or `&mut T` reference. In the GDScript code, you must not invoke any method on the same Rust receiver, which would violate safety rules (aliasing of `&mut`).
 
 
 ## Signal emissions

src/rust-binding/classes.md

@@ -52,15 +52,15 @@ pub struct GodotApi {}
 #[methods]
 impl GodotApi {
     // Constructor, either:
-    fn new(owner: &Node) -> Self { ... }
+    fn new(base: &Node) -> Self { ... }
     // or:
-    fn new(owner: TRef<Node>) -> Self { ... }
+    fn new(base: TRef<Node>) -> Self { ... }
 }
 ```
 
 The [`#[derive(NativeClass)]` macro](https://docs.rs/gdnative/latest/gdnative/derive.NativeClass.html) enables a Rust type to be usable as a _native class_ in Godot. It implements [the `NativeClass` trait](https://docs.rs/gdnative/latest/gdnative/nativescript/trait.NativeClass.html), which fills in the glue code required to make the class available in Godot. Among other information, this includes class name and registry of exported methods and properties. For the user, the utility methods `new_instance()` and `emplace()` are provided for constructing `Instance` objects.
 
-The function `new()` corresponds to `_init()` in GDScript. The _owner_ is the base object of the script, and must correspond to the class specified in the `#[inherit]` attribute (or `Reference` if the attribute is absent). The parameter can be a shared reference `&T` or a `TRef<T>`.
+The function `new()` corresponds to `_init()` in GDScript. The _base_ is the base object of the script, and must correspond to the class specified in the `#[inherit]` attribute (or `Reference` if the attribute is absent). The parameter can be a shared reference `&T` or a `TRef<T>`.
 
 With a `new()` method, you are able to write `GodotApi.new()` in GDScript. If you don't need this, you can add the `#[no_constructor]` attribute to the struct declaration.