godot-rust / gdnative-book Goto Github PK

Description in title. The link is broken. Also the file is missing even if the link wasn't broken.

I'm just starting with gdnative-rust and focusing on this FAQ:

#[derive(NativeClass)]
#[inherit(Node)]
#[no_constructor]
struct MyNode {
    node_ref: Option<Ref<Node>>
}

#[methods]
impl MyNode {
    #[method]
    fn _ready(&self, #[base] base: TRef<Node>) {
        let node = Node::new();
        base.add_child(node);
        self.node_ref = Some(node.claim());
    }
}

Note: As TRef<T> is a temporary pointer, it will be necessary to get the base pointer Ref<T> in order to continue to hold this value.

This can be done with the [TRef<T>::claim()](https://docs.rs/gdnative/latest/gdnative/struct.TRef.html#method.claim) function that returns the persistent version of the pointer, which you can store in your class.

I'm not able to replicate this proposal:

1- Seems like claim() method is not available in Ref<Node, Unique>.

Seems that Node::new() is actually returning a Ref instead of TRef.

Is this example obsolete?

It appears that the versions of LLVM used in rustc and emscripten have drifted out of sync again. Although the guide does specify a pair of known good versions of the tools, the commands simply use nightly and tot instead, and as a result some linking issues may arise when commands are blindly copied.

There are several steps we can take here. Firstly, the commands should be modified to use pinned versions. Longer term, we should see if there's a consistent way to tell the compatible version of emscripten from any given rustc version, or if we have to stick to manually finding known good pairs for the foreseeable future.

We should also see if #87 is still viable and if it can be merged into the current guide.

This sample here appears to be out of date as the setting that was changed no longer exists.

https://godot-rust.github.io/book/faq/configuration.html#how-do-i-get-code-auto-completion-with-rust-analyzer

It's possible that it is no longer necessary or that the necessary settings have changed. Eitherway the documentation should be updated to reflect this.

This would be a possible candidate as an FAQ entry: How to implement polymorphic functions?

For instance, the goal is to implement a free-floating helper function that can operate on any Control like:

pub fn set_anchor_full_rect_non_polymorphic(control: &Ref<Control, Unique>) {
    control.set_anchor(GlobalConstants::MARGIN_RIGHT, 0.0, false, true);
    control.set_anchor(GlobalConstants::MARGIN_BOTTOM, 0.0, false, true);
    control.set_anchor(GlobalConstants::MARGIN_RIGHT, 1.0, false, true);
    control.set_anchor(GlobalConstants::MARGIN_BOTTOM, 1.0, false, true);
}

Due to the explicit use of Control this isn't polymorphic though.

I assume this can be solved using SubClass. My naive attempt

pub fn set_anchor_full_rect<T>(control: &Ref<T, Unique>)
where
    T: GodotObject<RefKind = ManuallyManaged> + SubClass<Control>,
{
    control.set_anchor(GlobalConstants::MARGIN_RIGHT, 0.0, false, true);
    control.set_anchor(GlobalConstants::MARGIN_BOTTOM, 0.0, false, true);
    control.set_anchor(GlobalConstants::MARGIN_RIGHT, 1.0, false, true);
    control.set_anchor(GlobalConstants::MARGIN_BOTTOM, 1.0, false, true);
}

doesn't quite work though (no method named set_anchor found for reference &godot::Ref<T, godot::prelude::Unique>), and probably using Unique isn't ideal in terms of re-usability.

Somebody in ##rust on irc had issues due to using a pre-2021 edition of rustc/cargo, turned out they were following the Recipe: Nix as development environment chapter of the godot-rust book which pins a specific version of nixpkgs:

let
    # Get an up-to-date package for enabling OpenGL support in Nix
    nixgl = import (fetchTarball "https://github.com/guibou/nixGL/archive/master.tar.gz") {};

    # Pin the version of the nix package repository that has Godot 3.2.3 and compatible with godot-rust 0.9.3
    # You might want to update the commit hash into the one that have your desired version of Godot
    # You could search for the commit hash of a particular package by using this website https://lazamar.co.uk/nix-versions
    pkgs = import (fetchTarball "https://github.com/nixos/nixpkgs/archive/5658fadedb748cb0bdbcb569a53bd6065a5704a9.tar.gz") {};
in
    # Configure the dependency of your shell
    # Add support for clang for bindgen in godot-rust
    pkgs.mkShell.override { stdenv = pkgs.clangStdenv; } {
        buildInputs = [
            # Rust related dependencies
            pkgs.rustc
            pkgs.cargo
            pkgs.rustfmt
            pkgs.libclang

            # Godot Engine Editor
            pkgs.godot

            # The support for OpenGL in Nix
            nixgl.nixGLDefault
        ];

        # Point bindgen to where the clang library would be
        LIBCLANG_PATH = "${pkgs.libclang.lib}/lib";
        # Make clang aware of a few headers (stdbool.h, wchar.h)
        BINDGEN_EXTRA_CLANG_ARGS = with pkgs; ''
          -isystem ${llvmPackages.libclang.lib}/lib/clang/${lib.getVersion clang}/include
          -isystem ${llvmPackages.libclang.out}/lib/clang/${lib.getVersion clang}/include
          -isystem ${glibc.dev}/include
        '';

        # For Rust language server and rust-analyzer
        RUST_SRC_PATH = "${pkgs.rust.packages.stable.rustPlatform.rustLibSrc}";

        # Alias the godot engine to use nixGL
        shellHook = ''
            alias godot="nixGL godot -e"
        '';
    }

The gdnative-core crate of the godot-rust project depends on indexmap = "1.6.0", this resolves to indexmap 1.9.1 which uses 2021 edition.

Hey there, I'm running into an error when running make run on a clean setup of the initial hello world setup.
https://godot-rust.github.io/book/getting-started/setup.html#usage

$ cargo generate --git https://github.com/godot-rust/godot-rust-template --name my-awesome-game
$ cd my-awesome-game
$ make run

➜  my-awesome-game git:(master) ✗ make run
make build-x86_64-apple-darwin-debug
cargo build --target x86_64-apple-darwin
    Finished dev [unoptimized + debuginfo] target(s) in 0.13s
mv -b ./target/x86_64-apple-darwin/debug/*.dylib ./lib/x86_64-apple-darwin
mv: illegal option -- b
usage: mv [-f | -i | -n] [-v] source target
       mv [-f | -i | -n] [-v] source ... directory
make[1]: *** [build-x86_64-apple-darwin-debug] Error 64
make: *** [run] Error 2

It appears that the macOS mv does not support the -b command. Seeing as this guide was written for MacOS, I'm surprised that this is here. Curious what the workaround is for this?

Computer information:

                   'c.          [email protected]
                 ,xNMM.          ---------------------------------------
               .OMMMMo           OS: macOS 11.5.1 20G80 x86_64
               OMMM0,            Host: MacBookPro15,2
     .;loddo:' loolloddol;.      Kernel: 20.6.0
   cKMMMMMMMMMMNWMMMMMMMMMM0:    Uptime: 17 days, 3 hours, 45 mins
 .KMMMMMMMMMMMMMMMMMMMMMMMWd.    Packages: 80 (brew)
 XMMMMMMMMMMMMMMMMMMMMMMMX.      Shell: zsh 5.8
;MMMMMMMMMMMMMMMMMMMMMMMM:       Resolution: 1440x900@2x
:MMMMMMMMMMMMMMMMMMMMMMMM:       DE: Aqua
.MMMMMMMMMMMMMMMMMMMMMMMMX.      WM: Rectangle
 kMMMMMMMMMMMMMMMMMMMMMMMMWd.    Terminal: iTerm2
 .XMMMMMMMMMMMMMMMMMMMMMMMMMMk   Terminal Font: Monaco 12
  .XMMMMMMMMMMMMMMMMMMMMMMMMK.   CPU: Intel i5-8279U (8) @ 2.40GHz
    kMMMMMMMMMMMMMMMMMMMMMMd     GPU: Intel Iris Plus Graphics 655
     ;KMMMMMMMWXXWMMMMMMMk.      Memory: 10532MiB / 16384MiB
       .cooc,.    .,coo:.

Property access hooks is no longer valid. As per godot-rust/gdnative#874

The new way to register is with the with #[property(get|set)]

It probably makes sense to explicitly mention library limitations out of our control, as mentioned by @chitoyuu in godot-rust/gdnative#905 (comment).

Examples:

• godot-rust/book#20
• 2nd-class-citizen native types: godot-rust/gdnative#905 (comment)

Let's use this issue to collect more candidates for such a page.

• Installation and hello world (#3)
• dodge-the-creeps scenes, introducing concepts along the way?
• Finish dodge-the-creeps example

While a large part of the implementation can be in Rust, users will need to write the entry point in GDScript to work around a bug in the engine that true abstract classes are not differentiated from classes that are intended to be extended by scripts.

In general godot-rust allows to use e.g. either owner: &Node or owner: TRef<Node> on exported methods, as noted in the Class registration section:

The parameter can be a shared reference &T or a TRef.

Unless I have missed something, the book doesn't go into details why one would chose one over the other. In practice this means that most developers go for &T because it's simpler. This is probably the reason why many people run into problems when trying to set up signals, in particular because this example suggest that passing owner should just work. Searching the discord history shows many cases of failed attempts to get signal connection to work, because owner.connect takes a target: AsArg which only works with owner: TRef<T> but not with owner: &T (unless falling back to unsafe { owner.assume_shared() }). I'm not sure if this limitation is by design or can perhaps be avoided eventually (c.f. godot-rust/gdnative#749). So far this is the only difference I'm aware of, but there may be further differences. Regarding the book I'd suggest:

• In case one form is a strict superset of the other, the book should probably recommend using only the more powerful one. I.e, if the AsArg limitation is the only difference, it would make sense to recommend using TRef<T> because it can do strictly more than &T.
• If there are things that can only be done by one form, but not by the other and vice versa, it would be nice to list these pros/cons of both forms to help with the decision.

M1 is not a tier-1 platform for Rust yet, and it seems that rustup may default to a x86_64 installation even on M1 Macs (See godot-rust/gdnative#742 (comment)). We might want to mention this in the FAQ.

libgcc was removed in Android NDK version r23-beta3 and Rust was updated accordingly (see this issue). However, this change does not seem to be available in stable Rust yet (2023-03-04). This is should be mentioned in exporting for Android section.

I will make a PR for this but I'm not sure where we should mention it. My idea is to add a "Troubleshooting" section similar to "Errors you might encounter" in HTML5 export page. But I think it should be included at the start as well since users start following instructions before reading the troubleshooting.

The section How do I get auto-completion with rust-analyzer? seems outdated, because rust-analyzer.cargo.loadOutDirsFromCheck no longer exists.

In practice this is impacting my productivity quite a lot, because auto-completion within a native class exported function doesn't seem to work at all. Often, my IDE is in a state reporting simply "all broken"

... and if this happens when I'm having a weak moment it can take a while to spot the actual error.

To avoid getting impacted by this issue I have now started to implement more complex methods as free floating functions like

fn process(this: &mut MyClass, delta: f64) -> Option<()> {
    // ...
}

and forward calls from the methods, which is of course unnecessary boilerplate.

To narrow down the problem we probably need to answer the questions:

1. Is this just something broken with my setup, or is everyone using rust-analyzer facing these issues?

2. If it is setup related, what are the tricks to get it going, which we could update in the book?

3. If it turns out that it is fundamentally not working, the question may be if we can do something on library / macro side to improve it. Following the links posted by the rust-analyzer maintainer leads to a similar issue for tokio-tracing, caused by the usage of syn and this proposal to solve it on their side. @Bromeon Is this proposal applicable to godot-rust as well?

Write a page about style-related topics that cannot easily be automated and covered by rustfmt/clippy.

APIs:

• proc-macro attribute structure
• redundancy / when to use multiple methods
• #[must_use]

Implementation:

• order of symbols within a file
• order of #[derive(...)] traits
• use statements

This issue serves as a collection of more topics, as they come up in PR reviews.

Some users seem to have trouble with auto-completion. Setting "rust-analyzer.cargo.loadOutDirsFromCheck": true might resolve the problem as mentioned in many rust-analyzer issues.

Hi 😄 I apologize in advance if Im posting it here since this is not an issue. I recently created a godot-rust project template. It just basically bootstraps your godot-rust project directory. You could find the the project here and check out the wiki on how to use it. I would also like to add this on the book and maybe somebody might find this useful...

In "Using custom builds of Godot" section, the book should provide instructions on how to update the automatically generated api.json file after upgrading the custom build.

I solved this problem by going to ~/.cargo/git/checkouts/godot-rust-1005fa777d499fc2/ and executing

find -name "api.json" -delete

After that, I removed the target folder in my Rust project to trigger a clean build from scratch. Not sure whether this is the best method. Please let me know if there's a better alternative.

I think it would be a good idea to do this so users could see all the different common code answers in one look and easily click on them in the menu. It might be a good idea for other sections as well.

What do you think?

Need to be updated: https://godot-rust.github.io/book/gdnative/recipes/async-tokio.html

Related PR: godot-rust/gdnative#975, released to crates in 0.11.1

Over time, the godot-rust library grows, and the intricacies of the project can no longer fit in a simple README file. While there is the API documentation, it is very technical and hard to navigate for new users. The presence of multiple community-written "getting started" tutorials is evidence that the learning curve is problematic and we really need an expanded user guide.

Topics that should be covered

• Detailed "getting started" tutorial (tracked in #4)
  • That should include instructions for installing Godot, Rust, and other dependencies.
• Quick refresher of Godot's Scene/Node architecture
• Overview of GDNative and the Godot scripting system, including the mechanisms of "inheritance" (#326)
  • Exposing "static" functions using autoloads and ZSTs (#380).
  • Detailed safety assumptions
• Using the official reference
• Replacing GDScript-specific APIs (yield, preload, etc.) (#400)
• Testing code that depends on the engine ("Godot tests")
• Instructions for exporting to mobile platforms (#238, godot-rust/gdnative#285)
  • Android (#335)
  • iOS
• MSVC vs GNU for Windows
• Instance downcasting API (frequently asked question, example issues: godot-rust/gdnative#328, godot-rust/gdnative#273, and a lot more) (tracked in #5)

Contributing to the book

Since the book is still a very early work-in-progress and mostly blank, please leave a comment here before going ahead to write a section, to avoid duplication of work. PRs for the book should be made against the book branch, instead of master.

If there are other topics that you think should be covered in the book, please feel free to suggest them in the comments here.

Supersedes godot-rust/gdnative#209.

• Instance
• User-data errors (BorrowFailed, DifferentThread)

...and more?

Currently, the getting started guide does a great job at outlining a lot of the ways we can use the functionality of the code, but there aren't any solid examples for how to manually register functions or (more importantly) properties in the inspector.

This can lead to some unexpected behavior, especially when working with enums or custom filepaths (not to be confused with NodePath which works perfectly fine).

This should also demonstrate how to register enums with Godot since it currently registers Enums as a dictionary instead of a u32 as I initially expected.

Specific topics I will include:

• using the class builder to register properties
• Implementing Export, ToVariant and FromVariant for an enum type
• Implementing Export, ToVariant and FromVariant for a Native class type

This will also help me not forget how to do this in the future 😆

There has been discussion about this here godot-rust/#770

The idea is to write a tutorial so as to be able to do this from the gdscript side

extends Node

func _ready():
        var x = MyNativeClass.new() # this is written in rust and can be a reference for instance
        x.native_hello_world()

This has been mentioned to be a starting point.

I would be interested to do this and have some inputs unless @jacobsky is already on it?

Edit Bromeon: fixed links

Hi there, i have found a very interesting tool that i think we should mention in the book.
gdnative-doc parses the documentation in the rust code and generate the documentation in markdown (that can be shipped with an addon you're developping for instance)
It can also take your doc test in ```gdscript and put them into a test_file so they can be run by Gut.
Its also flawlessly integrated into cargo

It is used in a project i contributed to

It would be pertinent to look at

1. the build.rs file
2. the structure exported to godot
3. the generated doc
4. the generated Test

This could all be part of a section about developping addons in godot-rust for instance (which i would be interested in writing) what do you think?

There is instruction on the hello-world page (https://godot-rust.github.io/book/getting-started/hello-world.html) which states that gdnative should be added with version 0.9. This results in this error:

failed to select a version for the requirement gdnative = "^0.9"
  candidate versions found which didn't match: 0.8.1, 0.8.0, 0.7.0, ...

I just tried it with gdnative 8.0 and it solved the issue, but I suggest tips for other users to make it work.