|
1 | | - |
| 1 | + |
2 | 2 |
|
3 | | -# Rust bindings for Godot 4 |
| 3 | +# Example projects for godot-rust |
4 | 4 |
|
5 | | -_**[Website]** | **[Book][book]** | **[API Docs]** | [Discord] | [Mastodon] | [Twitter] | [Sponsor]_ |
| 5 | +_**[Website]** | **[Main repo]** | [Book] | [API Docs] | [Sponsor]_ |
6 | 6 |
|
7 | | -**gdext** is a library to integrate the Rust language with Godot 4. |
| 7 | +This repository collects official examples for the **[gdext][Main repo]** library. There are few examples at the moment, and we don't |
| 8 | +intend to showcase every aspect of the library here. Instead, examples are designed to be more "real-world" oriented, while |
| 9 | +keeping in mind a small scope that is approachable. |
8 | 10 |
|
9 | | -[Godot] is an open-source game engine, focusing on a productive and batteries-included 2D and 3D experience. |
10 | | -Its _GDExtension_ API allows integrating third-party languages and libraries. |
| 11 | +Examples do not replace the book and API docs, but are meant to be read in addition. If you're encountering concepts in the |
| 12 | +code that seem strange, please check both book and docs first! |
11 | 13 |
|
12 | | -Rust bindings for Godot 3 (GDNative API) are available in [`gdnative`]. |
13 | 14 |
|
| 15 | +## Current examples |
14 | 16 |
|
15 | | -## Philosophy |
| 17 | +We currently feature the following example projects: |
16 | 18 |
|
17 | | -The Rust binding is an alternative to GDScript, with a focus on type safety, scalability and performance. |
| 19 | +- [**Dodge the Creeps**](examples/dodge-the-creeps) |
| 20 | + A simple game where you dodge enemies. Ported from the official Godot tutorial. |
18 | 21 |
|
19 | | -The primary goal of gdext is to provide a [**pragmatic Rust API**][philosophy] for game developers. |
| 22 | +- [**Hot reload**](examples/hot-reload) |
| 23 | + Showcases how classes and their state can be hot-reloaded in the Godot editor. |
20 | 24 |
|
21 | | -Recurring workflows should be simple and require minimal boilerplate. APIs are designed to be safe and idiomatic Rust wherever possible. |
22 | | -Due to interacting with Godot as a C++ engine, we sometimes follow unconventional approaches to provide a good user experience. |
23 | 25 |
|
| 26 | +## Contributions |
24 | 27 |
|
25 | | -## Development status |
| 28 | +If you would like to contribute an example, please open an issue **before** submitting a big pull request. |
| 29 | +Keep in mind that this repo is not a collection of user projects, but an educational resource to complement |
| 30 | +the book and API docs of the library. Therefore, examples need to follow certain standards regarding code quality, |
| 31 | +documentation and maintainability. But don't worry, if you open an issue, we can guide you through! 🙂 |
26 | 32 |
|
27 | | -The gdext library has evolved a lot during 2023 and 2024 and is now in a usable state for smaller projects. |
28 | | -However, there are still certain things to keep in mind. |
| 33 | +Like the library, all contributions are subject to the [Mozilla Public License 2.0][mpl]. |
29 | 34 |
|
30 | | -> [!WARNING] |
31 | | -> The public API introduces breaking changes from time to time, primarily motivated by new features and improved ergonomics. |
32 | | -> Our [crates.io releases][crates-io] adhere to SemVer, but may lag behind the `master` branch. See also [API stability] in the book. |
33 | | -
|
34 | | -**Features:** Most Godot APIs have been mapped at this point. The current focus lies on a more natural Rust experience and enable more design |
35 | | -patterns that come in handy for day-to-day game development. See [#24] for an up-to-date feature overview. |
36 | | - |
37 | | -At the moment, there is experimental support for [Wasm], [Android] and [iOS], but documentation and tooling is still lacking. Contributions are very welcome! |
38 | | - |
39 | | -**Bugs:** Most undefined behavior related to the FFI layer has been ironed out, but there may still be occasional safety issues. Apart from that, |
40 | | -new additions to the library are typically not feature-complete from the start, but become more robust with feedback and testing over time. |
41 | | -To counter bugs, we have an elaborate CI suite including clippy, unit tests, engine integration tests and memory sanitizers. Even hot-reload is tested! |
42 | | - |
43 | | - |
44 | | -## Getting started |
45 | | - |
46 | | -To dive into Rust development with gdext, check out [the godot-rust book][book]. The book is still under construction, |
47 | | -but already covers a _Hello World_ setup as well as several more in-depth chapters. |
48 | | - |
49 | | -To consult the API reference, have a look at the online [API Docs]. |
50 | | - |
51 | | -Furthermore, we provide a small example game in the [`examples/dodge-the-creeps` directory][dodge-the-creeps]. |
52 | | -The example [`examples/hot-reload`][hot-reload] demonstrates hot-reloading in the Godot editor. |
53 | | - |
54 | | -If you need help, join our [Discord] server and ask in the `#help` channel! |
55 | | - |
56 | | - |
57 | | -## License |
58 | | - |
59 | | -We use the [Mozilla Public License 2.0][mpl]. MPL tries to find a balance between permissive (MIT, Apache, Zlib) and copyleft licenses (GPL, LGPL). |
60 | | - |
61 | | -The license provides a lot of freedom: you can use the library commercially and keep your own code closed-source, |
62 | | -i.e. game development is not restricted. The main condition is that if you change gdext _itself_, you need to make |
63 | | -those changes available (and only those, no surrounding code). |
64 | | - |
65 | | - |
66 | | -## Contributing |
67 | | - |
68 | | -Contributions are very welcome! If you want to help out, see [`Contributing.md`](Contributing.md) for some pointers on getting started. |
69 | | - |
70 | | -[#24]: https://github.com/godot-rust/gdext/issues/24 |
| 35 | +[Main repo]: https://github.com/godot-rust/gdext |
71 | 36 | [API Docs]: https://godot-rust.github.io/docs/gdext |
72 | | -[API stability]: https://godot-rust.github.io/book/toolchain/compatibility.html#rust-api-stability |
73 | | -[Android]: https://github.com/godot-rust/gdext/issues/470 |
74 | | -[Discord]: https://discord.gg/aKUCJ8rJsc |
75 | | -[Godot]: https://godotengine.org |
76 | | -[Mastodon]: https://mastodon.gamedev.place/@GodotRust |
77 | 37 | [Sponsor]: https://github.com/sponsors/Bromeon |
78 | | -[Twitter]: https://twitter.com/GodotRust |
79 | | -[WASM]: https://godot-rust.github.io/book/toolchain/export-web.html |
80 | 38 | [Website]: https://godot-rust.github.io |
81 | | -[`gdnative`]: https://github.com/godot-rust/gdnative |
82 | | -[book]: https://godot-rust.github.io/book |
83 | | -[dodge-the-creeps]: examples/dodge-the-creeps |
84 | | -[hot-reload]: examples/hot-reload |
85 | | -[iOS]: https://github.com/godot-rust/gdext/issues/498 |
| 39 | +[Book]: https://godot-rust.github.io/book |
86 | 40 | [mpl]: https://www.mozilla.org/en-US/MPL |
87 | | -[philosophy]: https://godot-rust.github.io/book/contribute/philosophy.html |
88 | | -[crates-io]: https://crates.io/crates/godot |
0 commit comments