Renders typed descriptions of each node in the scene files (.tscn) of a Godot project. Provides an access function to get a reference to the nodes called node(). This tool is intended for use with Miguel de Icaza's SwiftGodot bindings and generates Swift code that depends on SwiftGodot being available.
In SwiftGodot a node is referenced as follows:
let marker = getNodeOrNull("Sprite2D/Marker2D") as? Marker2D
This requires the programmer to ensure that the path to the node, and its type, are correct. If there is a mismatch, the marker variable will be nil.
If we run SceneGen on this project, our root Player type will be extended with typed descriptions of each node. These can then be accessed in a type-safe way:
let marker = node(.sprite2D_marker2d)
The programmer is no longer responsible for maintaining the types and the paths. This will lead to fewer run-time bugs and crashes, provide helpful code completion suggestions in your IDE, and allow faster iteration cycles.
I'm still figuring out the Swift PM story for how to run this, but in the meantime, here's an approach that works well:
- Install Mint (
brew install mint) if you don't already have it. - Add a file named
Mintfileto your project and putPadraigK/SceneGen@0.1.2(or whatever the latest release tag is) in there. - Run
mint bootstrap(takes a while, maybe 5 mins) - Run code generation using
mint run scenegen <project-path> <output-path>— note that output path will be deleted each time this is run before code is generated. This is necessary to clean up if you remove or rename a scene.
The recommended usage of SceneGen is with a watcher, like entr, which can be used re-run the generation anytime one of the scene files changes.
I suggest making a shell script like this:
#!/bin/zsh
# loop because the `-d` flag on `entr` makes it exit when it
# detects a new or deleted file in any of the folders its watching,
# otherwise it would only detect modifications to existing files
while sleep 0.1; do
find ../ -name '*.tscn' -not -path '*/.*' | entr -d -s 'mint run <project-path> <output-path>'
done
and then leaving it running in a terminal window as you work.
- IDE code suggestions include the names of all available nodes in your context.
- Run-time crashes due to typos in node path accessors can’t happen anymore.
- When you rename or reorganize node paths in the Godot Editor, the compiler will emit errors at build time in your swift code, giving you precise hints about what to fix, instead of run-time crashes.
- Generates a resource path to the tscn file so you can safely instantiate scenes in code — if you reorganize your tscn files into folders in Godot, a re-compile will fix all of these references with no code changes required on your part.
- As well as node accessors, SceneGen also generates:
- Typed animation names which are played using this syntax:
enemy.playAnimation(.explode) - Typed Input names from the InputMap in project settings, so you can do
let jump = Input.isActionJustPressed(.jump)
- Typed animation names which are played using this syntax:
- Supports “Access as Unique Name” to generate shorter named paths.
- Generator works independently of the built swift GDExtension — it just works off the Godot project file and tscn files. It’s not necessary that your extension code be buildable at code-generation time.