From bd25c344b2dccdef7baf7b3b95db396b52c78b24 Mon Sep 17 00:00:00 2001 From: Jan Haller Date: Sat, 29 Jul 2023 17:29:14 +0200 Subject: [PATCH] ReadMe --- ReadMe.md | 87 ++++++++++++++----------------------------------------- 1 file changed, 21 insertions(+), 66 deletions(-) diff --git a/ReadMe.md b/ReadMe.md index 3d6abebe2..a271b89a0 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -4,84 +4,38 @@ _**[Website]** | **[API Docs]** | [Discord] | [Mastodon] | [Twitter]_ -**gdext** is an early-stage library to bind the **Rust** language to **Godot 4**. +**gdext** is a library to bind the **Rust** language to **Godot 4**. -[Godot] is an open-source game engine, whose upcoming version 4.0 brings several improvements. +[Godot] is an open-source game engine, whose version 4 has brought large-scale improvements. Its _GDExtension_ API allows integrating third-party languages and libraries. > **Note**: if you are looking for a Rust binding for GDNative (Godot 3), checkout [`gdnative`]. -> **Warning**: this library is experimental and rapidly evolving. In particular, this means: -> * Lots of bugs. A lot of the scaffolding is still being ironed out. -> There are known safety issues, possible undefined behavior as well as other potential problems. -> * Lots of missing features. The priority is to get basic interactions working; -> as such, edge case APIs are deliberately neglected at this stage. -> * No stability guarantees. APIs will break frequently (for releases, we try to take SemVer seriously though). -> Resolving the above two points has currently more weight than a stable API. +> **Warning**: The gdext library has evolved a lot during 2023 and is now in a state where it's usable for smaller projects. +> When using it, you need to keep in mind: +> * While most Godot features are available, some less commonly used ones are missing. +> See [#24] for an up-to-date view. +> * We have an elaborate test suite, but bugs and UB is still possible. Please report issues! +> * The public API will introduce breaking changes from time to time. Most of these are motivated by new features and +> improved ergonomics for existing ones. Once we are on crates.io, we will take SemVer seriously though. +> * At this point, there is **no** support for Android, iOS or WASM. Contributions are very welcome! -We do not recommend building a larger project in gdext yet. -However, the library can serve as a playground for experimenting. -To get an overview of currently supported features, consult [#24](https://github.com/godot-rust/gdext/issues/24). -At this point, there is **no** support for Android, iOS or WASM. Contributions are very welcome! +## Philosophy +The primary goal of gdext is to provide a **pragmatic API** for game developers. Recurring workflows should be easy and without excessive +boilerplate. At the same time, the API should be safe and idiomatic Rust wherever possible. -## Getting started - -An elaborate tutorial is available [in the book] (still under construction), here is the short version. - -To find a version of Godot 4, the library expects either an executable of name `godot4` in the PATH, or an environment variable `GODOT4_BIN` -containing the path to the executable (including filename). -We currently only have a GitHub version, crates.io releases are planned once more of the foundation is ready. - -In your Cargo.toml, add: - -```toml -[lib] -crate-type = ["cdylib"] - -[dependencies] -godot = { git = "https://github.com/godot-rust/gdext", branch = "master" } -``` -To get the latest changes, you can regularly run a `cargo update` (possibly breaking). Keep your `Cargo.lock` file under version control, so that it's easy to revert updates. -To register the GDExtension library with Godot, you need to create two files relative to your Godot project folder: - -1. First, add `res://MyExt.gdextension`, which is the equivalent of `.gdnlib` for GDNative. - - The `[configuration]` section should be copied as-is. - The `[libraries]` section should be updated to match the paths of your dynamic Rust libraries. - `{my-ext}` can be replaced with the name of your crate. - ```ini - [configuration] - entry_symbol = "gdext_rust_init" - - [libraries] - linux.debug.x86_64 = "res://../rust/target/debug/lib{my-ext}.so" - linux.release.x86_64 = "res://../rust/target/release/lib{my-ext}.so" - windows.debug.x86_64 = "res://../rust/target/debug/{my-ext}.dll" - windows.release.x86_64 = "res://../rust/target/release/{my-ext}.dll" - macos.debug = "res://../rust/target/debug/{my-ext}.dylib" - macos.release = "res://../rust/target/release/{my-ext}.dylib" - macos.debug.arm64 = "res://../rust/target/debug/{my-ext}.dylib" - macos.release.arm64 = "res://../rust/target/release/{my-ext}.dylib" - ``` - > **Note**: for exporting your project, you'll need to use paths inside `res://` - - > **Note**: If you specify your cargo compilation target via the `--target` flag or a `.cargo/config.toml` file, the rust library will be placed in a path name that includes target architecture, and the `.gdextension` library paths will need to match. E.g. for M1 Macs (`macos.debug.arm64` and `macos.release.arm64`) the path would be `"res://../rust/target/aarch64-apple-darwin/debug/{my-ext}.dylib"` - -2. A second file `res://.godot/extension_list.cfg` should be generated once you open the Godot editor for the first time. - If not, you can also manually create it, simply containing the Godot path to your `.gdextension` file: - ``` - res://MyExt.gdextension - ``` +## Getting started -### Examples +To dive into Rust development with gdext, have a look at [the godot-rust book][book]. The book is still under construction but includes +already a tutorial to set up a simple working example. -We highly recommend to have a look at a working example in the `examples/dodge-the-creeps` directory. -This integrates a small game with Godot and has all the necessary steps set up. +To consult an API reference, check out the online [API Docs]. +API documentation can also be generated locally using `./check.sh doc` (use `dok` instead of `doc` to open the page in the browser). -API documentation can be generated locally using `./check.sh doc` (use `dok` instead of `doc` to open the page in the browser). +We also provide a small example game in the `examples/dodge-the-creeps` directory. If you need help, join our [Discord] server and ask in the `#help-gdext` channel! @@ -107,4 +61,5 @@ Contributions are very welcome! If you want to help out, see [`Contributing.md`] [Discord]: https://discord.gg/aKUCJ8rJsc [Mastodon]: https://mastodon.gamedev.place/@GodotRust [Twitter]: https://twitter.com/GodotRust -[in the book]: https://godot-rust.github.io/book/gdext/intro \ No newline at end of file +[#24]: https://github.com/godot-rust/gdext/issues/24 +[book]: https://godot-rust.github.io/book/gdext/intro \ No newline at end of file