godot/

lib.rs

#![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.
//! * [`signal`], machinery for type-safe signals.
//! * [`tools`], higher-level utilities that extend the generated code, e.g. `load<T>()`.
//! * [`meta`], fundamental information about types and conversions.
//! * [`init`], entry point and global library configuration.
//! * [`task`], integration with async code.
//!
//! 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>
//!
//!
//! ## Safeguard levels
//!
//! godot-rust uses three tiers that differ in the amount of runtime checks and validations that are performed.  \
//! They can be configured via [Cargo features](#cargo-features).
//!
//! - 🛡️ **Strict** (default for dev builds)
//!
//!   Lots of additional, sometimes expensive checks. Detects many bugs during development.
//!   - `Gd::bind/bind_mut()` provides extensive diagnostics to locate runtime borrow errors.
//!   - `Array` safe conversion checks (for types like `Array<i8>`).
//!   - RTTI checks on object access (protect against type mismatch edge cases).
//!   - Geometric invariants (e.g. normalized quaternions).
//!   - Access to engine APIs outside valid scope.<br><br>
//!
//! - ⚖️ **Balanced** (default for release builds)
//!
//!   Basic validity and invariant checks, reasonably fast. Within this level, you should not be able to encounter undefined behavior (UB)
//!   in safe Rust code. Invariant violations may however cause panics and logic errors.
//!   - Object liveness checks.
//!   - `Gd::bind/bind_mut()` cause panics on borrow errors.<br><br>
//!
//! - ☣️ **Disengaged**
//!
//!   Most checks disabled, sacrifices safety for raw speed. This renders a large part of the godot-rust API `unsafe` without polluting the
//!   code; you opt in via `unsafe impl ExtensionLibrary`.
//!
//!   Before using this, measure to ensure you truly need the last bit of performance (balanced should be fast enough for most cases; if not,
//!   consider bringing it up). Also test your code thoroughly using the other levels first. Undefined behavior and crashes arising
//!   from using this level are your full responsibility. When reporting a bug, make sure you can reproduce it under the balanced level.
//!   - Unchecked object access -> instant UB if an object is dead.
//!   - `Gd::bind/bind_mut()` are unchecked -> UB if mutable aliasing occurs.
//!
//! <div class="warning">
//! <p>Safeguards are a recent addition to godot-rust and need calibrating over time. If you are unhappy with how the <i>balanced</i> level
//! performs in basic operations, consider bringing it up for discussion. We'd like to offer the <i>disengaged</i> level for power users who
//! really need it, but it shouldn't be the only choice for decent runtime performance, as it comes with heavy trade-offs.</p>
//!
//! <p>As of v0.4, the above checks are not fully implemented yet. Neither are they guarantees; categorization may change over time.</p>
//! </div>
//!
//!
//! ## Cargo features
//!
//! The following features can be enabled for this crate. All of 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-custom`**
//! * **`api-custom-json`**
//!
//!   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.
//!
//!   `api-custom` feature requires specifying `GDRUST_GODOT_BIN` environment variable with a path to your Godot4 binary.
//!
//!   The `api-custom-json` feature requires specifying `GDRUST_GODOT_API_JSON` environment variable with a path
//!   to your custom-defined `extension_api.json`.<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.<br><br>
//!
//! _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 adds synchronization to access the user instance in `Gd<T>` and disables several single-thread checks.
//!   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.
//!
//!   Please read [Export to Web](https://godot-rust.github.io/book/toolchain/export-web.html) in the book.
//!
//!   By default, Wasm threads are enabled and require the flag `"-C", "link-args=-pthread"` in the `wasm32-unknown-unknown` target.
//!   This must be kept in sync with Godot's Web export settings (threading support enabled). To disable it, use **additionally* the feature
//!   `experimental-wasm-nothreads`.
//!
//!   It is recommended to use this feature in combination with `lazy-function-tables` to reduce the size of the generated Wasm binary.<br><br>
//!
//! * **`experimental-wasm-nothreads`**
//!
//!   Requires the `experimental-wasm` feature. Disables threading support for WebAssembly exports. This needs to be kept in sync with
//!   Godot's Web export setting (threading support disabled), and must _not_ use the `"-C", "link-args=-pthread"` flag in the
//!   `wasm32-unknown-unknown` target.<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.<br><br>
//!
//! * **`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)
//!
//! _Safeguards:_
//!
//! See [Safeguard levels](#safeguard-levels).
//!
//! * **`safeguards-dev-balanced`**
//!
//!   For the `dev` Cargo profile, use the **balanced** safeguard level instead of the default strict level.<br><br>
//!
//! * **`safeguards-release-disengaged`**
//!
//!   For the `release` Cargo profile, use the **disengaged** safeguard level instead of the default balanced level.
//!
//! _Third-party 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

// Many validations are moved to godot-ffi. #[cfg]s are not emitted in this crate, so move checks for those up to godot-core.

#[cfg(all(target_family = "wasm", not(feature = "experimental-wasm")))]
compile_error!(
    "Wasm target requires opt-in via `experimental-wasm` Cargo feature;\n\
    keep in mind that this is work in progress."
);

// See also https://github.com/godotengine/godot/issues/86346.
// Could technically be moved to godot-codegen to reduce time-to-failure slightly, but would scatter validations even more.
#[cfg(all(
    feature = "double-precision",
    not(feature = "api-custom"),
    not(feature = "api-custom-json")
))]
compile_error!(
    "The feature `double-precision` currently requires `api-custom` or `api-custom-json` due to incompatibilities in the GDExtension API JSON. \
See: https://github.com/godotengine/godot/issues/86346"
);

// On non-Emscripen targets, wasm-ld will insert a call to __wasm_call_ctors (which calls all constructors) to the start all exported functions,
// if it detects that __wasm_call_ctors is never called and not exported. This could cause constructors to run multiple times.
// Emscripen should always export __wasm_call_ctors and call it at runtime.
// See https://github.com/godot-rust/gdext/pull/1476 for more info and links.
#[cfg(all(target_family = "wasm", not(target_os = "emscripten")))]
compile_error!("Wasm targets not using Emscripten are not supported.");

// ----------------------------------------------------------------------------------------------------------------------------------------------
// Modules

#[doc(hidden)]
pub use godot_core::possibly_docs as docs;
#[doc(hidden)]
pub use godot_core::sys;
#[doc(inline)]
pub use godot_core::{builtin, classes, global, obj, task, tools};

/// Entry point and global init/shutdown of the library.
pub mod init {
    pub use godot_core::init::*;
    // Re-exports
    pub use godot_macros::gdextension;
}

/// Meta-information about Godot types, their properties and conversions between them.
pub mod meta {
    // Submodules.
    // Derive macro (moved from `register`).
    pub use godot_core::meta::ClassId;
    #[doc(hidden)]
    pub use godot_core::meta::arg_into_owned;
    #[cfg(feature = "__trace")]
    #[doc(hidden)]
    pub use godot_core::meta::trace;
    // Argument conversions that stay in flat `meta`.
    pub use godot_core::meta::{AsArg, ObjectArg, ToArg, owned_into_arg, ref_to_arg};
    // Hidden internal items for proc-macros and generated code.
    #[doc(hidden)]
    pub use godot_core::meta::{CallContext, Signature, ensure_func_bounds};
    #[cfg(feature = "__trace")]
    #[doc(hidden)]
    pub use godot_core::meta::{CowArg, FfiArg};
    // Type traits.
    pub use godot_core::meta::{
        Element, GodotImmutable, GodotType, PackedElement, element_variant_type,
    };
    // Conversion traits.
    pub use godot_core::meta::{EngineFromGodot, EngineToGodot, FromGodot, GodotConvert, ToGodot};
    // Range utilities.
    pub use godot_core::meta::{SignedRange, wrapped};
    #[doc(inline)]
    pub use godot_core::meta::{conv, error, inspect, shape};
    pub use godot_macros::GodotConvert;
}

/// Runtime types for working with signals: connecting, emitting, and handling.
pub mod signal {
    pub use godot_core::obj::signal::re_export::*;
}

/// Register/export Rust symbols to Godot: classes, methods, enums...
pub mod register {
    #[cfg(feature = "__codegen-full")]
    pub use godot_core::registry::RpcConfig;
    pub use godot_macros::{GodotClass, godot_api, godot_dyn};

    /// Register Rust fields as Godot properties.
    pub mod property {
        pub use godot_core::registry::property::*;
        // Derive macros for property traits.
        pub use godot_macros::{Export, Var};
    }

    #[doc(inline)]
    pub use godot_core::registry::info;

    /// 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;