From 2c13257e0f3bf8f28238e0a555db07067e6a8850 Mon Sep 17 00:00:00 2001 From: Jan Haller Date: Sat, 10 Jan 2026 11:16:44 +0100 Subject: [PATCH 1/2] Readme: concrete versions for `cargo install` --- ReadMe.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/ReadMe.md b/ReadMe.md index ec006f6..7608b82 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -1,8 +1,7 @@ # The godot-rust book -This book is a user guide for **godot-rust**, the Rust bindings to Godot 4. -It covers a large part of the concepts and complements [the API docs][gdext-docs]. -There is also [gdnative-book] for Godot 3. +This book is a user guide for **godot-rust**, the Rust bindings to Godot 4.[^gdnative-book] +It covers a large part of the concepts and complements [the API docs][api-docs]. > [!Tip] > The book is deployed at **[godot-rust.github.io/book][book-web]**. @@ -10,10 +9,11 @@ There is also [gdnative-book] for Godot 3. ## Local setup -The book is built with [mdBook] and the plugins [mdbook-toc] and [mdbook-admonish]. To install them and build the book locally, you can run: +The book is built with [mdBook] and the plugins [mdbook-toc] and [mdbook-admonish].[^mdbook] +To install them and build the book locally, you can run: ```bash -cargo install mdbook mdbook-toc mdbook-admonish +cargo install mdbook@^0.4 mdbook-toc@^0.14 mdbook-admonish@1.18.0 mdbook build ``` @@ -51,7 +51,7 @@ oxipng --strip safe --alpha -r src ## Contributing This repository is for documentation only. For changes in the library itself, please open pull requests and issues in the [main repo][gdext], -and read the [contributing guidelines][gdext-contribute]. +and read the [contributing guidelines][contribute]. ## License @@ -60,8 +60,8 @@ Like godot-rust itself, the godot-rust book is licensed under [MPL 2.0][mpl]. [book-web]: https://godot-rust.github.io/book [gdext]: https://github.com/godot-rust/gdext -[gdext-docs]: https://godot-rust.github.io/docs/gdext/master/godot -[gdext-contribute]: https://github.com/godot-rust/gdext/blob/master/Contributing.md +[api-docs]: https://godot-rust.github.io/docs/gdext/master/godot +[contribute]: https://github.com/godot-rust/gdext/blob/master/Contributing.md [gdnative-book]: https://github.com/godot-rust/gdnative-book [markdownlint]: https://github.com/DavidAnson/markdownlint [mdbook-admonish]: https://github.com/tommilligan/mdbook-admonish @@ -70,3 +70,7 @@ Like godot-rust itself, the godot-rust book is licensed under [MPL 2.0][mpl]. [mpl]: https://www.mozilla.org/en-US/MPL [oxipng]: https://github.com/shssoichiro/oxipng +
+ +[^gdnative-book]: For Godot 3, there is the older [gdnative-book]. +[^mdbook]: mdBook 0.5 contains breaking changes, and we can't support it until plugins catch up. Right now it offers no features that would benefit us. From a5b0ac61b62846ea655ca887c73d8e45371a7f34 Mon Sep 17 00:00:00 2001 From: Jan Haller Date: Sat, 10 Jan 2026 13:20:02 +0100 Subject: [PATCH 2/2] Update properties page according to recent `Var` changes --- src/register/properties.md | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/src/register/properties.md b/src/register/properties.md index d14addf..c14f866 100644 --- a/src/register/properties.md +++ b/src/register/properties.md @@ -105,12 +105,19 @@ You can also declare both attributes on the same field. This is in fact necessar ## Enums -You can export Rust enums as properties. An exported enum appears as a drop-down field in the editor, with all available options. +You can export Rust enums as properties, as long as they are C style enums (no associated data per variant). +An exported enum appears as a drop-down field in the editor, with all available options. In order to do that, you need to derive three traits: -- `GodotConvert` to define how the type is converted from/to Godot. -- `Var` to allow using it as a `#[var]` property, so it can be accessed from Godot. -- `Export` to allow using it as a `#[export]` property, so it appears in the editor UI. +- [`GodotConvert`][api-godotconvert] to define how the type is converted from/to Godot. +- [`Var`][api-var] to allow using it as a `#[var]` property, so it can be accessed from Godot. +- [`Export`][api-export] to allow using it as a `#[export]` property, so it appears in the editor UI. + +Additionally, it can make sense to derive following standard traits: + +- `Clone`: it is possible without, but then you need to implement `Var` manually. The reason is that `Var` also provides Rust getters when + used with `#[var(pub)]`, which require cloning the value. +- `Default`: if there is a meaningful default value. If not, use `#[init(val = ...)]` on the field declarations to provide an initial value. Godot does not have dedicated enum types, so you can map them either as integers (e.g. `i64`) or strings (`GString`). This can be configured using the `via` key of the `#[godot]` attribute. @@ -118,10 +125,11 @@ configured using the `via` key of the `#[godot]` attribute. Exporting an enum can be done as follows: ```rust -#[derive(GodotConvert, Var, Export)] +#[derive(GodotConvert, Var, Export, Default, Clone)] #[godot(via = GString)] pub enum Planet { - Earth, // first enumerator is default. + #[default] // Rust standard attribute, not godot-rust. + Earth, Mars, Venus, } @@ -210,6 +218,9 @@ As a general rule, try to stay close to Godot's own types, e.g. `Array`, `Dictio ``` +[api-godotconvert]: https://godot-rust.github.io/docs/gdext/master/godot/meta/trait.GodotConvert.html +[api-var]: https://godot-rust.github.io/docs/gdext/master/godot/register/property/trait.Var.html +[api-export]: https://godot-rust.github.io/docs/gdext/master/godot/register/property/trait.Export.html [api-derive-export]: https://godot-rust.github.io/docs/gdext/master/godot/register/derive.Export.html [api-derive-var]: https://godot-rust.github.io/docs/gdext/master/godot/register/derive.Var.html [api-var-export]: https://godot-rust.github.io/docs/gdext/master/godot/register/derive.GodotClass.html#properties-and-exports