Merge pull request #1309 from godot-rust/bugfix/init-tests

Improve init-level tests; fix `RenderingServer` singleton error

Author: Bromeon

godot-codegen/src/special_cases/special_cases.rs

@@ -985,7 +985,7 @@ pub fn get_derived_virtual_method_presence(class_name: &TyName, godot_method_nam
     }
 }
 
-/// Initialization order for Godot (see https://github.com/godotengine/godot/blob/master/main/main.cpp)
+/// Initialization order for Godot (see https://github.com/godotengine/godot/blob/master/main/main.cpp).
 /// - Main::setup()
 ///   - register_core_types()
 ///   - register_early_core_singletons()
@@ -1002,13 +1002,25 @@ pub fn get_derived_virtual_method_presence(class_name: &TyName, godot_method_nam
 ///     - initialize_extensions(GDExtension::INITIALIZATION_LEVEL_EDITOR)
 ///   - register_server_singletons() ...another weird one.
 ///   - Autoloads, etc.
+///
+/// ## Singleton availability by initialization level
+/// - **Core level**: Basic singletons like `Engine`, `OS`, `ProjectSettings`, `Time` are available.
+/// - **Servers level**: Server singletons like `RenderingServer` are NOT yet available due to GDExtension timing issues.
+/// - **Scene level**: All singletons including `RenderingServer` are available.
+/// - **Editor level**: Editor-specific functionality is available.
+///
+/// GDExtension singletons are generally not available during *any* level initialization, with the exception of a few core singletons 
+/// (see above). This is different from how modules work, where servers are available at _Servers_ level.
+///
+/// See also:
+/// - Singletons not accessible in Scene (godot-cpp): <https://github.com/godotengine/godot-cpp/issues/1180>
+/// - `global_get_singleton` not returning singletons: <https://github.com/godotengine/godot/issues/64975>
+/// - PR to make singletons available: <https://github.com/godotengine/godot/pull/98862>
 #[rustfmt::skip]
 pub fn classify_codegen_level(class_name: &str) -> Option<ClassCodegenLevel> {
     let level = match class_name {
         // See register_core_types() in https://github.com/godotengine/godot/blob/master/core/register_core_types.cpp,
-        // which is called before Core level is initialized.
-        // Currently only promoting super basic classes to Core level since this is a brittle hardcoded list (feel free expand as 
-        // necessary based on careful evaluation of register_core_types).
+        // which is called before Core level is initialized. Only a small list is promoted to Core; carefully evaluate if more are added.
         | "Object" | "RefCounted" | "Resource" | "MainLoop" | "GDExtension"
         => ClassCodegenLevel::Core,
 
@@ -1035,6 +1047,7 @@ pub fn classify_codegen_level(class_name: &str) -> Option<ClassCodegenLevel> {
         | "RenderData" | "RenderDataExtension"
         | "RenderSceneData" | "RenderSceneDataExtension"
         => ClassCodegenLevel::Servers,
+        
         // Declared final (un-inheritable) in Rust, but those are still servers.
         | "AudioServer" | "CameraServer" | "NavigationServer2D" | "NavigationServer3D" | "RenderingServer" | "TranslationServer" | "XRServer" | "DisplayServer"
         => ClassCodegenLevel::Servers,
@@ -1045,6 +1058,7 @@ pub fn classify_codegen_level(class_name: &str) -> Option<ClassCodegenLevel> {
         | "OpenXRInteractionProfileEditor"
         | "OpenXRBindingModifierEditor" if cfg!(before_api = "4.5") 
         => ClassCodegenLevel::Editor,
+        
         // https://github.com/godotengine/godot/issues/86206
         "ResourceImporterOggVorbis" | "ResourceImporterMP3" if cfg!(before_api = "4.3") 
         => ClassCodegenLevel::Editor,

godot-core/src/init/mod.rs

@@ -244,6 +244,23 @@ fn gdext_on_level_deinit(level: InitLevel) {
 /// Note that this only changes the name. You cannot provide your own function -- use the [`on_level_init()`][ExtensionLibrary::on_level_init]
 /// hook for custom startup logic.
 ///
+/// # Availability of Godot APIs during init and deinit
+// Init order: see also special_cases.rs > classify_codegen_level().
+/// Godot loads functionality gradually during its startup routines, and unloads it during shutdown. As a result, Godot classes are only
+/// available above a certain level. Trying to access a class API when it's not available will panic (if not, please report it as a bug).
+///
+/// A few singletons (`Engine`, `Os`, `Time`, `ProjectSettings`) are available from the `Core` level onward and can be used inside
+/// this method. Most other singletons are **not available during init** at all, and will only become accessible once the first frame has
+/// run.
+///
+/// The exact time a class is available depends on the Godot initialization logic, which is quite complex and may change between versions.
+/// To get an up-to-date view, inspect the Godot source code of [main.cpp], particularly `Main::setup()`, `Main::setup2()` and
+/// `Main::cleanup()` methods. Make sure to look at the correct version of the file.
+///
+/// In case of doubt, do not rely on classes being available during init/deinit.
+///
+/// [main.cpp]: https://github.com/godotengine/godot/blob/master/main/main.cpp
+///
 /// # Safety
 /// The library cannot enforce any safety guarantees outside Rust code, which means that **you as a user** are
 /// responsible to uphold them: namely in GDScript code or other GDExtension bindings loaded by the engine.
@@ -269,6 +286,8 @@ pub unsafe trait ExtensionLibrary {
     /// Custom logic when a certain init-level of Godot is loaded.
     ///
     /// This will only be invoked for levels >= [`Self::min_level()`], in ascending order. Use `if` or `match` to hook to specific levels.
+    ///
+    /// If the overridden method panics, an error will be printed, but GDExtension loading is **not** aborted.
     #[allow(unused_variables)]
     fn on_level_init(level: InitLevel) {
         // Nothing by default.
@@ -277,6 +296,8 @@ pub unsafe trait ExtensionLibrary {
     /// Custom logic when a certain init-level of Godot is unloaded.
     ///
     /// This will only be invoked for levels >= [`Self::min_level()`], in descending order. Use `if` or `match` to hook to specific levels.
+    ///
+    /// If the overridden method panics, an error will be printed, but GDExtension unloading is **not** aborted.
     #[allow(unused_variables)]
     fn on_level_deinit(level: InitLevel) {
         // Nothing by default.

itest/rust/src/lib.rs

@@ -6,7 +6,6 @@
  */
 
 use godot::init::{gdextension, ExtensionLibrary, InitLevel};
-use godot::sys::Global;
 
 mod benchmarks;
 mod builtin_tests;
@@ -19,39 +18,13 @@ mod register_tests;
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 // Entry point
 
-static LEVELS_SEEN: Global<Vec<InitLevel>> = Global::default();
-
 #[gdextension(entry_symbol = itest_init)]
 unsafe impl ExtensionLibrary for framework::IntegrationTests {
     fn min_level() -> InitLevel {
         InitLevel::Core
     }
-    fn on_level_init(level: InitLevel) {
-        LEVELS_SEEN.lock().push(level);
-        match level {
-            InitLevel::Core => {
-                // Make sure we can access early core singletons.
-                object_tests::test_early_core_singletons();
-            }
-            InitLevel::Servers => {
-                // Make sure we can access server singletons by now.
-                object_tests::test_server_singletons();
-            }
-            InitLevel::Scene => {}
-            InitLevel::Editor => {}
-        }
-    }
-}
 
-// Ensure that we saw all the init levels expected.
-#[crate::framework::itest]
-fn observed_all_init_levels() {
-    let levels_seen = LEVELS_SEEN.lock().clone();
-    assert_eq!(levels_seen[0], InitLevel::Core);
-    assert_eq!(levels_seen[1], InitLevel::Servers);
-    assert_eq!(levels_seen[2], InitLevel::Scene);
-    // NOTE: some tests don't see editor mode
-    if let Some(level_3) = levels_seen.get(3) {
-        assert_eq!(*level_3, InitLevel::Editor);
+    fn on_level_init(level: InitLevel) {
+        object_tests::on_level_init(level);
     }
 }

itest/rust/src/object_tests/init_level_test.rs

@@ -7,12 +7,15 @@
 
 use std::sync::atomic::{AtomicBool, Ordering};
 
+use godot::init::InitLevel;
 use godot::obj::NewAlloc;
 use godot::register::{godot_api, GodotClass};
+use godot::sys::Global;
 
-use crate::framework::itest;
+use crate::framework::{expect_panic, itest, runs_release, suppress_godot_print};
 
 static OBJECT_CALL_HAS_RUN: AtomicBool = AtomicBool::new(false);
+static LEVELS_SEEN: Global<Vec<InitLevel>> = Global::default();
 
 #[derive(GodotClass)]
 #[class(base = Object, init)]
@@ -34,8 +37,49 @@ impl SomeObject {
     }
 }
 
+// Ensure that the above function has actually run and succeeded.
+#[itest]
+fn init_level_all_initialized() {
+    assert!(
+        OBJECT_CALL_HAS_RUN.load(Ordering::Relaxed),
+        "Object call function did not run during Core init level"
+    );
+}
+
+// Ensure that we saw all the init levels expected.
+#[itest]
+fn init_level_observed_all() {
+    let levels_seen = LEVELS_SEEN.lock().clone();
+
+    assert_eq!(levels_seen[0], InitLevel::Core);
+    assert_eq!(levels_seen[1], InitLevel::Servers);
+    assert_eq!(levels_seen[2], InitLevel::Scene);
+
+    // In Debug/Editor builds, Editor level is loaded; otherwise not.
+    let level_3 = levels_seen.get(3);
+    if runs_release() {
+        assert_eq!(level_3, None);
+    } else {
+        assert_eq!(level_3, Some(&InitLevel::Editor));
+    }
+}
+
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+// Level-specific callbacks
+
+pub fn on_level_init(level: InitLevel) {
+    LEVELS_SEEN.lock().push(level);
+
+    match level {
+        InitLevel::Core => on_init_core(),
+        InitLevel::Servers => on_init_servers(),
+        InitLevel::Scene => on_init_scene(),
+        InitLevel::Editor => on_init_editor(),
+    }
+}
+
 // Runs during core init level to ensure we can access core singletons.
-pub fn test_early_core_singletons() {
+fn on_init_core() {
     // Ensure we can create and use an Object-derived class during Core init level.
     SomeObject::test();
 
@@ -59,14 +103,20 @@ pub fn test_early_core_singletons() {
     assert!(time.get_ticks_usec() <= time.get_ticks_usec());
 }
 
-// Runs during scene init level to ensure we can access general singletons in the Scene init call for the extension as a whole.
-pub fn test_server_singletons() {
-    let mut rendering = godot::classes::RenderingServer::singleton();
-    assert!(rendering.get_test_cube() != godot::builtin::Rid::Invalid);
+fn on_init_servers() {
+    // Nothing yet.
 }
 
-// Ensure that the above function actually ran.
-#[itest]
-fn class_run_during_servers_init() {
-    assert!(OBJECT_CALL_HAS_RUN.load(Ordering::Acquire));
+fn on_init_scene() {
+    // Known limitation that singletons only become available later:
+    // https://github.com/godotengine/godot-cpp/issues/1180#issuecomment-3074351805
+    expect_panic("Singletons not loaded during Scene init level", || {
+        suppress_godot_print(|| {
+            let _ = godot::classes::RenderingServer::singleton();
+        });
+    });
+}
+
+pub fn on_init_editor() {
+    // Nothing yet.
 }