Sync `.tscn` files with Rust code

[anup-the-magic]

Edit bromeon: Rust tags for syntax highlighting

I love Godot (for a variety of reasons), but its reliance on non-typesafe scene files, and (similarly) runtime crashes caused by misconfiguration, is not one of them. I'd love to do away with this, and the easiest way to do this in my mind is to enshrine the .tscn files into my nice, typesafe, rust code.

Theoretical example that I have:

The Goal

I want this node hierarchy, where MyCustomType is a rust class, which needs a reference to Gd<Camera3D> and Gd<Sprite3d>:

MyCustomType
|- Camera3D
|- Sprite3D

The Options

The Bad

I could create a .tscn file, and then just load it everywhere (using OnEditor in the examples below to nab a reference automatically), but then any change of the root type of my tscn now needs a corresponding change in my rust code, otherwise the cast fails at runtime. Less than ideal.

The Ugly

I could generate the hierarchy manually...

// my_custom_type.rs
#[derive(GodotClass)]
#[class(base=Node3D)]
pub struct MyCustomType {
    camera: OnReady<Gd<Camera3D>>,
    sprite: OnReady<Gd<Sprite3D>>,
    base: Base<Node3D>,
}

#[godot_api]
impl INode3D for MyCustomType{
    fn init(base: Base<Node3D>) -> Self {
        Self {
            base,
            camera: OnReady::manual(),
            sprite: OnReady::manual(),
        }
    }

    fn ready(&mut self) -> () {
        let camera = Camera3D::new_alloc();
        self.camera.init(camera);

        let sprite = Sprite3D::new_alloc();
        self.sprite.init(sprite);

        let camera = self.camera.clone();
        let sprite = self.sprite.clone();

        {
            let mut base = self.base_mut();
            base.add_child(&camera);
            base.add_child(&sprite);
        }
    }
}

But this is a bit overly verbose, and if I forget to initialize sprite in ready? Well we're panicking again.

The alternative

(disclaimer, I am a rust novice, but I think something like this is theoretically doable?)

static Scene: Scene<MyCustomType> = scene!({
  Camera3D {
    transform: Transform { origin: Vector3 { x: 1, ..default() }, ..default() },
  }
  Sprite3D {
  }
});

#[derive(GodotClass)]
#[class(base=Node3D)]
pub struct MyCustomType {
    camera: InScene<Gd<Camera3D>>,
    sprite: InScene<Gd<Sprite3D>>,
    base: Base<Node3D>,
}

impl INode3D for MyCustomType {
    fn init(base: Base<Node3D>) -> Self {
        Self {
            base,
            camera: Scene.Camera3D,
            sprite: Scene.Sprite3D,
        }
    }
}

Notably, behind the scenes (heh), we'd have godot-rust run the machinery to add the children to the tree, with the specified overrides (here, a different position). Hell, if it's performant, we could even emit a tscn file and load behind the scenes, but I think that gets a bit wonky and is definitely out of scope.

InScene would work similarly to OnReady, except the initialization in init would take in the path in the scene hierarchy, and every further call would be already resolved and realized?

Closing remarks

This is notably incredibly handwavy, and doesn't take into account a few key problems (scene tree modification, nodes with different names, up casting, base types + specialized scenes), but I figured this was enough of a formed idea rolling around in my head to at least start the discussion here.

Would love to keep spitballing ideas / help with implementation as needed

[Bromeon]

Maybe first, are you aware of the #[init(node)] attribute? You can use it to automatically resolve nodes in the tree. You don't need a ready() function, let alone manual .add_child() calls if you have a pre-existing .tscn file. It still means changing the tree comes with a sync of the Rust code, but it's quite straightforward.

---

Regarding automated sync of scenes, this is a valid request and has come up in the past. I do think it is out-of-scope for the core library though. Like you suspect, there are several things to consider (when to invoke sync, how to generate code, etc.) and a cdylib might be the wrong place to handle it.

My plan is to add a command-line tool that helps with synchronizing Godot state to Rust:

• Scene files
• Collision masks
• Input actions
• Commonly used project configuration
• GDScript APIs, see Type-safe API for external classes (GDScript, GDExtension, C#) #372

But the data flow would strictly be Godot -> Rust, i.e. there would be a code-generated API for existing scene files. I do not plan to mix this with a DSL in Rust code, as scene post-initialization can be relatively easily added through procedural means like ready(). Having yet another API for that invites potentially unbounded customization requests.

---

Small nitpick: please use ```rs tags for syntax highlighting, and a more descriptive title next time 🙂

[anup-the-magic]

Thanks for the reply! Sorry if it was a bit scattered, this is what I get for drafting something at 2am...

Yes, should definitely have called out init(node) as well, though I think the pain points with that are not dissimilar to using OnEditor, right? And you're still stuck loading this as a .tscn file reference that can go stale (instead of a class import that cargo can validate)?

---

Agreed that CLI to sync godot state plus some auto-gen classes might go a long way towards mitigating this -- that was the first thought, but then ended up being a bit more inspired by Bevy's BSN. If you think that code gen is a more reasonable direction, I'd be happy to start drafting up some proof of concepts here or elsewhere?

If you feel like this is also out of scope for the core lib that's fair, but at a glance, I feel like it'd fit nicely in eg godot-codegen? perhaps with an opt-in feature that is gated in the build.rs (and appropriately scoped to rerun-if-changed in the godot directory?). Definitely agree that the biggest short-term wins would be:

• scenes
• collisions
• input maps
• I'd also add animations

... though I'd hope we come up with something that scales relatively easily if we want to add more.

[Bromeon]

Agreed that CLI to sync godot state plus some auto-gen classes might go a long way towards mitigating this -- that was the first thought, but then ended up being a bit more inspired by Bevy's BSN.

Bevy is Rust-first, 100% code driven, with no editor -- a very different paradigm from Godot. As such I think godot-rust as a core library should lean into Godot's way of managing scenes rather than reinvent the scene format in Rust. But that doesn't mean that third party projects cannot do that, we have several extensions already.

---

If you feel like this is also out of scope for the core lib that's fair, but at a glance, I feel like it'd fit nicely in eg godot-codegen?

Currently godot-core depends on godot-codegen and compiles very slowly (due to traits + large Godot API). This is OK in practice because it's only used in cold builds. But it implies that godot-codegen cannot itself be recompiled based on often-changing input like .tscn -- it could however just provide the codegen machinery and be invoked downstream of godot-core (e.g. in godot or another crate... or even in the CLI tool).

Another point is that today, you can compile godot-rust entirely without a running Godot engine. If we wanted to keep doing this, we'd need to manually parse all the Godot files, which increases complexity and maintenance of such a generator. This could still be done later, but maybe a PoC should use Godot for it.

It would be interesting to look at a concrete workflow first. Is rerun-if-changed fully robust with Godot? Doesn't the engine sometimes touch files even if they're unchanged (and thus trigger unnecessary recompilations).