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