godot_ffi/
init_level.rs

1/*
2 * Copyright (c) godot-rust; Bromeon and contributors.
3 * This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
6 */
7
8crate::atomic_enum! {
9    /// Step in the Godot initialization process.
10    ///
11    /// Godot's initialization and deinitialization processes are split into multiple stages, like a stack. At each level,
12    /// a different amount of engine functionality is available. Deinitialization happens in reverse order.
13    ///
14    /// See also:
15    // Explicit HTML links because this is re-exported in godot::init, and we can't document a `use` statement.
16    /// - [`InitStage`](enum.InitStage.html): all levels + main loop.
17    /// - [`ExtensionLibrary::on_stage_init()`](trait.ExtensionLibrary.html#method.on_stage_init)
18    /// - [`ExtensionLibrary::on_stage_deinit()`](trait.ExtensionLibrary.html#method.on_stage_deinit)
19    #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
20    pub enum InitLevel {
21        /// First level loaded by Godot. Builtin types are available, classes are not.
22        Core = 0,
23
24        /// Second level loaded by Godot. Only server classes and builtins are available.
25        Servers = 1,
26
27        /// Third level loaded by Godot. Most classes are available.
28        Scene = 2,
29
30        /// Fourth level loaded by Godot, only in the editor. All classes are available.
31        Editor = 3,
32    }
33}
34
35impl InitLevel {
36    #[doc(hidden)]
37    pub fn from_sys(level: crate::GDExtensionInitializationLevel) -> Self {
38        match level {
39            crate::GDEXTENSION_INITIALIZATION_CORE => Self::Core,
40            crate::GDEXTENSION_INITIALIZATION_SERVERS => Self::Servers,
41            crate::GDEXTENSION_INITIALIZATION_SCENE => Self::Scene,
42            crate::GDEXTENSION_INITIALIZATION_EDITOR => Self::Editor,
43            _ => {
44                eprintln!("WARNING: unknown initialization level {level}");
45                Self::Scene
46            }
47        }
48    }
49
50    #[doc(hidden)]
51    pub fn to_sys(self) -> crate::GDExtensionInitializationLevel {
52        match self {
53            Self::Core => crate::GDEXTENSION_INITIALIZATION_CORE,
54            Self::Servers => crate::GDEXTENSION_INITIALIZATION_SERVERS,
55            Self::Scene => crate::GDEXTENSION_INITIALIZATION_SCENE,
56            Self::Editor => crate::GDEXTENSION_INITIALIZATION_EDITOR,
57        }
58    }
59
60    /// Convert this initialization level to an initialization stage.
61    pub fn to_stage(self) -> InitStage {
62        match self {
63            Self::Core => InitStage::Core,
64            Self::Servers => InitStage::Servers,
65            Self::Scene => InitStage::Scene,
66            Self::Editor => InitStage::Editor,
67        }
68    }
69}
70
71// ----------------------------------------------------------------------------------------------------------------------------------------------
72
73/// Extended step in the initialization process, including both init-levels and the main loop.
74///
75/// This enum extends [`InitLevel`] with a `MainLoop` variant, representing the fully initialized state of Godot
76/// after all initialization levels have been loaded and before any deinitialization begins.
77///
78/// During initialization, stages are loaded in order: `Core` → `Servers` → `Scene` → `Editor` (if in editor) → `MainLoop`.  \
79/// During deinitialization, stages are unloaded in reverse order.
80///
81/// See also:
82/// - [`InitLevel`](enum.InitLevel.html): only levels, without `MainLoop`.
83/// - [`ExtensionLibrary::on_stage_init()`](trait.ExtensionLibrary.html#method.on_stage_init)
84/// - [`ExtensionLibrary::on_stage_deinit()`](trait.ExtensionLibrary.html#method.on_stage_deinit)
85/// - [`ExtensionLibrary::on_main_loop_frame()`](trait.ExtensionLibrary.html#method.on_main_loop_frame)
86#[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
87#[non_exhaustive]
88pub enum InitStage {
89    /// First level loaded by Godot. Builtin types are available, classes are not.
90    Core,
91
92    /// Second level loaded by Godot. Only server classes and builtins are available.
93    Servers,
94
95    /// Third level loaded by Godot. Most classes are available.
96    Scene,
97
98    /// Fourth level loaded by Godot, only in the editor. All classes are available.
99    Editor,
100
101    /// The main loop stage, representing the fully initialized state of Godot.
102    ///
103    /// This variant is only available in Godot 4.5+. In earlier versions, it will never be passed to callbacks.
104    /// It is however unconditionally available, to avoid "infecting" user code with `#[cfg]`s.
105    MainLoop,
106}
107
108impl InitStage {
109    /// Try to convert this initialization stage to an initialization level.
110    ///
111    /// Returns `None` for [`InitStage::MainLoop`], as it doesn't correspond to a Godot initialization level.
112    pub fn try_to_level(self) -> Option<InitLevel> {
113        match self {
114            Self::Core => Some(InitLevel::Core),
115            Self::Servers => Some(InitLevel::Servers),
116            Self::Scene => Some(InitLevel::Scene),
117            Self::Editor => Some(InitLevel::Editor),
118            Self::MainLoop => None,
119        }
120    }
121}
godot_ffi/init_level.rs

godot_ffi/
init_level.rs
