godot/lib.rs
1#![cfg_attr(published_docs, feature(doc_cfg))]
2/*
3 * Copyright (c) godot-rust; Bromeon and contributors.
4 * This Source Code Form is subject to the terms of the Mozilla Public
5 * License, v. 2.0. If a copy of the MPL was not distributed with this
6 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
7 */
8
9//! # Rust bindings for Godot 4
10//!
11//! The **gdext** library implements Rust bindings for the [Godot](https://godotengine.org) engine, more precisely its version 4.
12//! It does so using the GDExtension API, a C interface to integrate third-party language bindings with the engine.
13//!
14//! This API doc is accompanied by the [book](https://github.com/godot-rust/book), which provides tutorials
15//! that guide you along the way.
16//!
17//! An overview of fundamental types and concepts can be found on [this page](__docs).
18//!
19//!
20//! ## Module organization
21//!
22//! The contains generated code, which is derived from the GDExtension API specification. This code spans the official Godot API and
23//! is mostly the same as the API you would use in GDScript.
24//!
25//! The Godot API is divided into several modules:
26//!
27//! * [`builtin`]: Built-in types, such as `Vector2`, `Color`, and `String`.
28//! * [`classes`]: Godot classes, such as `Node`, `RefCounted` or `Resource`.
29//! * [`global`]: Global functions and enums, such as `godot_print!`, `smoothstep` or `JoyAxis`.
30//!
31//! In addition to generated code, we provide a framework that allows you to easily interface the Godot engine.
32//! Noteworthy modules in this context are:
33//!
34//! * [`register`], used to register **your own** Rust symbols (classes, methods, constants etc.) with Godot.
35//! * [`obj`], everything related to handling Godot objects, such as the `Gd<T>` type.
36//! * [`tools`], higher-level utilities that extend the generated code, e.g. `load<T>()`.
37//! * [`meta`], fundamental information about types, properties and conversions.
38//! * [`init`], entry point and global library configuration.
39//! * [`task`], integration with async code.
40//!
41//! The [`prelude`] contains often-imported symbols; feel free to `use godot::prelude::*` in your code.
42//! <br><br>
43//!
44//!
45//! ## Public API
46//!
47//! Some symbols in the API are not intended for users, however Rust's visibility feature is not strong enough to express that in all cases
48//! (for example, proc-macros and separated crates may need access to internals).
49//!
50//! The following API symbols are considered private:
51//!
52//! * Symbols annotated with `#[doc(hidden)]`.
53//! * Any of the dependency crates (crate `godot` is the only public interface).
54//! * Modules named `private` and all their contents.
55//!
56//! This means there are **no guarantees** regarding API stability, robustness or correctness. Problems arising from using private APIs are
57//! not considered bugs, and anything relying on them may stop working without announcement. Please refrain from using undocumented and
58//! private features; if you are missing certain functionality, bring it up for discussion instead. This allows us to improve the library!
59//! <br><br>
60//!
61//!
62//! ## Cargo features
63//!
64//! The following features can be enabled for this crate. All of them are off by default.
65//!
66//! Avoid `default-features = false` unless you know exactly what you are doing; it will disable some required internal features.
67//!
68//! _Godot version and configuration:_
69//!
70//! * **`api-4-{minor}`**
71//! * **`api-4-{minor}-{patch}`**
72//! * **`api-custom`**
73//! * **`api-custom-json`**
74//!
75//! Sets the [**API level**](https://godot-rust.github.io/book/toolchain/godot-version.html) to the specified Godot version,
76//! or a custom-built local binary.
77//! You can use at most one `api-*` feature. If absent, the current Godot minor version is used, with patch level 0.
78//!
79//! `api-custom` feature requires specifying `GODOT4_BIN` environment variable with a path to your Godot4 binary.
80//!
81//! The `api-custom-json` feature requires specifying `GODOT4_GDEXTENSION_JSON` environment variable with a path
82//! to your custom-defined `extension_api.json`.<br><br>
83//!
84//! * **`double-precision`**
85//!
86//! Use `f64` instead of `f32` for the floating-point type [`real`][type@builtin::real]. Requires Godot to be compiled with the
87//! scons flag `precision=double`.<br><br>
88//!
89//! * **`experimental-godot-api`**
90//!
91//! Access to `godot::classes` APIs that Godot marks "experimental". These are under heavy development and may change at any time.
92//! If you opt in to this feature, expect breaking changes at compile and runtime.
93//!
94//! _Rust functionality toggles:_
95//!
96//! * **`lazy-function-tables`**
97//!
98//! Instead of loading all engine function pointers at startup, load them lazily on first use. This reduces startup time and RAM usage, but
99//! incurs additional overhead in each FFI call. Also, you lose the guarantee that once the library has booted, all function pointers are
100//! truly available. Function calls may thus panic only at runtime, possibly in deeply nested code paths.
101//! This feature is not yet thread-safe and can thus not be combined with `experimental-threads`.<br><br>
102//!
103//! * **`experimental-threads`**
104//!
105//! Experimental threading support. This adds synchronization to access the user instance in `Gd<T>` and disables several single-thread checks.
106//! The safety aspects are not ironed out yet; there is a high risk of unsoundness at the moment.
107//! As this evolves, it is very likely that the API becomes stricter.<br><br>
108//!
109//! * **`experimental-wasm`**
110//!
111//! Support for WebAssembly exports is still a work-in-progress and is not yet well tested. This feature is in place for users
112//! to explicitly opt in to any instabilities or rough edges that may result.
113//!
114//! Please read [Export to Web](https://godot-rust.github.io/book/toolchain/export-web.html) in the book.
115//!
116//! By default, Wasm threads are enabled and require the flag `"-C", "link-args=-pthread"` in the `wasm32-unknown-unknown` target.
117//! This must be kept in sync with Godot's Web export settings (threading support enabled). To disable it, use **additionally* the feature
118//! `experimental-wasm-nothreads`.<br><br>
119//!
120//! It is recommended to use this feature in combination with `lazy-function-tables` to reduce the size of the generated Wasm binary.
121//!
122//! * **`experimental-wasm-nothreads`**
123//!
124//! Requires the `experimental-wasm` feature. Disables threading support for WebAssembly exports. This needs to be kept in sync with
125//! Godot's Web export setting (threading support disabled), and must _not_ use the `"-C", "link-args=-pthread"` flag in the
126//! `wasm32-unknown-unknown` target.<br><br>
127//!
128//! * **`codegen-rustfmt`**
129//!
130//! Use rustfmt to format generated binding code. Because rustfmt is so slow, this is detrimental to initial compile time.
131//! Without it, we use a lightweight and fast custom formatter to enable basic human readability.<br><br>
132//!
133//! * **`register-docs`**
134//!
135//! Generates documentation for your structs from your Rust documentation.
136//! Documentation is visible in Godot via `F1` -> searching for that class.
137//! This feature requires at least Godot 4.3.
138//! See also: [`#[derive(GodotClass)]`](register/derive.GodotClass.html#documentation)
139//!
140//! _Integrations:_
141//!
142//! * **`serde`**
143//!
144//! Implement the [serde](https://serde.rs/) traits `Serialize` and `Deserialize` traits for certain built-in types.
145//! The serialized representation underlies **no stability guarantees** and may change at any time, even without a SemVer-breaking change.
146//!
147
148#![doc(
149 html_logo_url = "https://raw.githubusercontent.com/godot-rust/assets/master/gdext/ferris.svg"
150)]
151
152#[cfg(doc)]
153pub mod __docs;
154
155// ----------------------------------------------------------------------------------------------------------------------------------------------
156// Validations
157
158// Many validations are moved to godot-ffi. #[cfg]s are not emitted in this crate, so move checks for those up to godot-core.
159
160#[cfg(all(target_family = "wasm", not(feature = "experimental-wasm")))]
161compile_error!(
162 "Wasm target requires opt-in via `experimental-wasm` Cargo feature;\n\
163 keep in mind that this is work in progress."
164);
165
166// See also https://github.com/godotengine/godot/issues/86346.
167// Could technically be moved to godot-codegen to reduce time-to-failure slightly, but would scatter validations even more.
168#[cfg(all(
169 feature = "double-precision",
170 not(feature = "api-custom"),
171 not(feature = "api-custom-json")
172))]
173compile_error!("The feature `double-precision` currently requires `api-custom` or `api-custom-json` due to incompatibilities in the GDExtension API JSON. \
174See: https://github.com/godotengine/godot/issues/86346");
175
176// ----------------------------------------------------------------------------------------------------------------------------------------------
177// Modules
178
179#[doc(hidden)]
180pub use godot_core::possibly_docs as docs;
181#[doc(hidden)]
182pub use godot_core::sys;
183#[doc(inline)]
184pub use godot_core::{builtin, classes, global, meta, obj, task, tools};
185
186/// Entry point and global init/shutdown of the library.
187pub mod init {
188 pub use godot_core::init::*;
189 // Re-exports
190 pub use godot_macros::gdextension;
191}
192
193/// Register/export Rust symbols to Godot: classes, methods, enums...
194pub mod register {
195 pub use godot_core::registry::property;
196 pub use godot_core::registry::signal::re_export::*;
197 #[cfg(feature = "__codegen-full")]
198 pub use godot_core::registry::RpcConfig;
199 pub use godot_macros::{godot_api, godot_dyn, Export, GodotClass, GodotConvert, Var};
200
201 /// Re-exports used by proc-macro API.
202 #[doc(hidden)]
203 pub mod private {
204 #[cfg(feature = "__codegen-full")]
205 pub use godot_core::registry::class::auto_register_rpcs;
206 pub use godot_core::registry::godot_register_wrappers::*;
207 pub use godot_core::registry::{constant, method};
208 }
209}
210
211/// Testing facilities (unstable).
212#[doc(hidden)]
213pub mod test {
214 pub use godot_macros::{bench, itest};
215}
216
217#[doc(hidden)]
218pub use godot_core::__deprecated;
219#[doc(hidden)]
220pub use godot_core::private;
221
222/// Often-imported symbols.
223pub mod prelude;