Adding ClassCodegenLevel::Core

- mostly just mimic'd the setup for server classes
added special_case::is_class_level_core
- trying to dry up all the special case stuff into special_cases module
- added unit testing for init levels. Make sure utilizing the early_core_singletons works.
- documented Godot startup sequence in special_cases.rs and tried to reference where each class list was (roughly) coming from
- promoted some base types to Core but hestiant to promote the whole list since it's very brittle and later levels are always safe.

Author: ogapo

godot-codegen/src/generator/mod.rs

@@ -47,6 +47,7 @@ pub fn generate_sys_module_file(sys_gen_path: &Path, submit_fn: &mut SubmitFn) {
     let code = quote! {
         pub mod table_builtins;
         pub mod table_builtins_lifecycle;
+        pub mod table_core_classes;
         pub mod table_servers_classes;
         pub mod table_scene_classes;
         pub mod table_editor_classes;

godot-codegen/src/models/domain.rs

@@ -805,14 +805,15 @@ impl ToTokens for ModName {
 /// At which stage a class function pointer is loaded.
 #[derive(Copy, Clone, Eq, PartialEq, Hash)]
 pub enum ClassCodegenLevel {
+    Core,
     Servers,
     Scene,
     Editor,
 }
 
 impl ClassCodegenLevel {
-    pub fn with_tables() -> [Self; 3] {
-        [Self::Servers, Self::Scene, Self::Editor]
+    pub fn with_tables() -> [Self; 4] {
+        [Self::Core, Self::Servers, Self::Scene, Self::Editor]
     }
 
     pub fn table_global_getter(self) -> Ident {
@@ -829,6 +830,7 @@ impl ClassCodegenLevel {
 
     pub fn lower(self) -> &'static str {
         match self {
+            Self::Core => "core",
             Self::Servers => "servers",
             Self::Scene => "scene",
             Self::Editor => "editor",
@@ -837,6 +839,7 @@ impl ClassCodegenLevel {
 
     fn upper(self) -> &'static str {
         match self {
+            Self::Core => "Core",
             Self::Servers => "Servers",
             Self::Scene => "Scene",
             Self::Editor => "Editor",
@@ -845,6 +848,7 @@ impl ClassCodegenLevel {
 
     pub fn to_init_level(self) -> TokenStream {
         match self {
+            Self::Core => quote! { crate::init::InitLevel::Core },
             Self::Servers => quote! { crate::init::InitLevel::Servers },
             Self::Scene => quote! { crate::init::InitLevel::Scene },
             Self::Editor => quote! { crate::init::InitLevel::Editor },

godot-codegen/src/special_cases/codegen_special_cases.rs

@@ -140,6 +140,7 @@ const SELECTED_CLASSES: &[&str] = &[
     "ClassDB",
     "Engine",
     "OS",
+    "ProjectSettings",
     //
     // Editor plugins
     "EditorPlugin",

godot-codegen/src/special_cases/special_cases.rs

@@ -30,7 +30,7 @@
 use proc_macro2::Ident;
 
 use crate::conv::to_enum_type_uncached;
-use crate::models::domain::{Enum, RustTy, TyName, VirtualMethodPresence};
+use crate::models::domain::{ClassCodegenLevel, Enum, RustTy, TyName, VirtualMethodPresence};
 use crate::models::json::{JsonBuiltinMethod, JsonClassMethod, JsonSignal, JsonUtilityFunction};
 use crate::special_cases::codegen_special_cases;
 use crate::util::option_as_slice;
@@ -985,34 +985,85 @@ 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)
+/// - Main::setup()
+///   - register_core_types()
+///   - register_early_core_singletons()
+///   - initialize_extensions(GDExtension::INITIALIZATION_LEVEL_CORE)
+/// - Main::setup2()
+///   - register_server_types()
+///   - initialize_extensions(GDExtension::INITIALIZATION_LEVEL_SERVERS)
+///   - register_core_singletons() ...possibly a bug. Should this be before LEVEL_SERVERS?
+///   - register_scene_types()
+///   - register_scene_singletons()
+///   - initialize_extensions(GDExtension::INITIALIZATION_LEVEL_SCENE)
+///   - IF EDITOR
+///     - register_editor_types()
+///     - initialize_extensions(GDExtension::INITIALIZATION_LEVEL_EDITOR)
+///   - register_server_singletons() ...another weird one.
+///   - Autoloads, etc.
 #[rustfmt::skip]
-pub fn is_class_level_server(class_name: &str) -> bool {
-    // Unclear on if some of these classes should be registered earlier than `Scene`:
-    // - `RenderData` + `RenderDataExtension`
-    // - `RenderSceneData` + `RenderSceneDataExtension`
-
-    match class_name {
-        // TODO: These should actually be at level `Core`
-        | "Object" | "OpenXRExtensionWrapperExtension" 
-
-        // Declared final (un-inheritable) in Rust, but those are still servers.
-        | "AudioServer" | "CameraServer" | "NavigationServer2D" | "NavigationServer3D" | "RenderingServer" | "TranslationServer" | "XRServer" 
-
-        // PhysicsServer2D
+pub fn classify_codegen_level(class_name: &str, godot_classification: &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).
+        | "Object" | "RefCounted" | "Resource" | "MainLoop" | "GDExtension"
+        => ClassCodegenLevel::Core,
+
+        // See register_early_core_singletons() in https://github.com/godotengine/godot/blob/master/core/register_core_types.cpp,
+        // which is called before Core level is initialized.
+        | "ProjectSettings" | "Engine" | "OS" | "Time"
+        => ClassCodegenLevel::Core,
+
+        // Anything that comes from another extension could be available in Core but since there would be load order dependencies,
+        // instead don't allow calls until Server level.
+        | "OpenXRExtensionWrapperExtension" 
+        => ClassCodegenLevel::Servers,
+
+        // See register_server_types() in https://github.com/godotengine/godot/blob/master/servers/register_server_types.cpp
         | "PhysicsDirectBodyState2D" | "PhysicsDirectBodyState2DExtension" 
         | "PhysicsDirectSpaceState2D" | "PhysicsDirectSpaceState2DExtension" 
         | "PhysicsServer2D" | "PhysicsServer2DExtension" 
         | "PhysicsServer2DManager" 
-
-        // PhysicsServer3D
         | "PhysicsDirectBodyState3D" | "PhysicsDirectBodyState3DExtension" 
         | "PhysicsDirectSpaceState3D" | "PhysicsDirectSpaceState3DExtension" 
         | "PhysicsServer3D" | "PhysicsServer3DExtension" 
         | "PhysicsServer3DManager" 
         | "PhysicsServer3DRenderingServerHandler"
+        | "RenderData" | "RenderDataExtension"
+        | "RenderSceneData" | "RenderSceneDataExtension"
+        => ClassCodegenLevel::Servers,
+        // Declared final (un-inheritable) in Rust, but those are still servers.
+        // NOTE: while these _types_ are available at Server level, the singletons themselves are actually not available until _even after_ Editor level.
+        | "AudioServer" | "CameraServer" | "NavigationServer2D" | "NavigationServer3D" | "RenderingServer" | "TranslationServer" | "XRServer" | "DisplayServer"
+        => ClassCodegenLevel::Servers,
+
+        // Work around wrong classification in https://github.com/godotengine/godot/issues/86206.
+        // https://github.com/godotengine/godot/issues/103867
+        "OpenXRInteractionProfileEditorBase"
+        | "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,
 
-        => true, _ => false
-    }
+        _ => {
+            // NOTE: Right now, Godot reports everything that's not "editor" as "core" in `extension_api.json`. 
+            // If it wasn't picked up by the whitelist, and Godot reports it as "core" we will treat it as a scene class.
+            match godot_classification {
+                "editor" => ClassCodegenLevel::Editor,
+                "core" => ClassCodegenLevel::Scene,
+                _ => {
+                    // we don't know this classification
+                    return None;
+                }
+            }
+        }
+    };
+    Some(level)
 }
 
 /// Whether a generated enum is `pub(crate)`; useful for manual re-exports.

godot-codegen/src/util.rs

@@ -51,33 +51,24 @@ pub fn make_sname_ptr(identifier: &str) -> TokenStream {
 }
 
 pub fn get_api_level(class: &JsonClass) -> ClassCodegenLevel {
-    // Work around wrong classification in https://github.com/godotengine/godot/issues/86206.
-    fn override_editor(class_name: &str) -> bool {
-        match class_name {
-            // https://github.com/godotengine/godot/issues/103867
-            "OpenXRInteractionProfileEditorBase"
-            | "OpenXRInteractionProfileEditor"
-            | "OpenXRBindingModifierEditor" => cfg!(before_api = "4.5"),
-
-            // https://github.com/godotengine/godot/issues/86206
-            "ResourceImporterOggVorbis" | "ResourceImporterMP3" => cfg!(before_api = "4.3"),
-
-            _ => false,
-        }
+    // NOTE: We have to use a whitelist of known classes because Godot doesn't separate these out
+    // beyond "editor" and "core" and some classes are also  mis-classified in the JSON depending on the Godot version.
+    if let Some(forced_classification) =
+        special_cases::classify_codegen_level(&class.name, &class.api_type)
+    {
+        return forced_classification;
     }
 
-    if special_cases::is_class_level_server(&class.name) {
-        ClassCodegenLevel::Servers
-    } else if class.api_type == "editor" || override_editor(&class.name) {
-        ClassCodegenLevel::Editor
-    } else if class.api_type == "core" {
-        ClassCodegenLevel::Scene
-    } else {
-        panic!(
-            "class {} has unknown API type {}",
-            class.name, class.api_type
-        )
+    // Fall back to just trusting the categorization. Presently, Godot only reports "core" and "editor".
+    for level in ClassCodegenLevel::with_tables() {
+        if level.lower() == class.api_type {
+            return level;
+        }
     }
+    panic!(
+        "class {} has unknown API type {}",
+        class.name, class.api_type
+    );
 }
 
 pub fn ident(s: &str) -> Ident {

godot-ffi/src/binding/mod.rs

@@ -6,9 +6,9 @@
  */
 
 use crate::{
-    BuiltinLifecycleTable, BuiltinMethodTable, ClassEditorMethodTable, ClassSceneMethodTable,
-    ClassServersMethodTable, GDExtensionClassLibraryPtr, GDExtensionInterface,
-    GdextRuntimeMetadata, ManualInitCell, UtilityFunctionTable,
+    BuiltinLifecycleTable, BuiltinMethodTable, ClassCoreMethodTable, ClassEditorMethodTable,
+    ClassSceneMethodTable, ClassServersMethodTable, GDExtensionClassLibraryPtr,
+    GDExtensionInterface, GdextRuntimeMetadata, ManualInitCell, UtilityFunctionTable,
 };
 
 #[cfg(feature = "experimental-threads")]
@@ -34,6 +34,7 @@ pub(crate) struct GodotBinding {
     interface: GDExtensionInterface,
     library: ClassLibraryPtr,
     global_method_table: BuiltinLifecycleTable,
+    class_core_method_table: ManualInitCell<ClassCoreMethodTable>,
     class_server_method_table: ManualInitCell<ClassServersMethodTable>,
     class_scene_method_table: ManualInitCell<ClassSceneMethodTable>,
     class_editor_method_table: ManualInitCell<ClassEditorMethodTable>,
@@ -56,6 +57,7 @@ impl GodotBinding {
             interface,
             library: ClassLibraryPtr(library),
             global_method_table,
+            class_core_method_table: ManualInitCell::new(),
             class_server_method_table: ManualInitCell::new(),
             class_scene_method_table: ManualInitCell::new(),
             class_editor_method_table: ManualInitCell::new(),
@@ -148,6 +150,20 @@ pub unsafe fn class_servers_api() -> &'static ClassServersMethodTable {
     )
 }
 
+/// # Safety
+///
+/// - The Godot binding must have been initialized before calling this function.
+/// - The class core method table must have been initialized before calling this function.
+///
+/// If "experimental-threads" is not enabled, then this must be called from the same thread that the bindings were initialized from.
+#[inline(always)]
+pub unsafe fn class_core_api() -> &'static ClassCoreMethodTable {
+    get_table(
+        &get_binding().class_core_method_table,
+        "cannot fetch classes; init level 'Core' not yet loaded",
+    )
+}
+
 /// # Safety
 ///
 /// - The Godot binding must have been initialized before calling this function.
@@ -251,6 +267,20 @@ pub(crate) unsafe fn get_binding() -> &'static GodotBinding {
     BindingStorage::get_binding_unchecked()
 }
 
+/// # Safety
+///
+/// - The Godot binding must have been initialized before calling this function.
+/// - Must only be called once.
+///
+/// If "experimental-threads" is not enabled, then this must be called from the same thread that the bindings were initialized from.
+pub(crate) unsafe fn initialize_class_core_method_table(table: ClassCoreMethodTable) {
+    initialize_table(
+        &get_binding().class_core_method_table,
+        table,
+        "classes (Core level)",
+    )
+}
+
 /// # Safety
 ///
 /// - The Godot binding must have been initialized before calling this function.

godot-ffi/src/lib.rs

@@ -81,6 +81,7 @@ pub use gen::interface::*;
 // Method tables
 pub use gen::table_builtins::*;
 pub use gen::table_builtins_lifecycle::*;
+pub use gen::table_core_classes::*;
 pub use gen::table_editor_classes::*;
 pub use gen::table_scene_classes::*;
 pub use gen::table_servers_classes::*;
@@ -101,8 +102,9 @@ mod binding;
 
 pub use binding::*;
 use binding::{
-    initialize_binding, initialize_builtin_method_table, initialize_class_editor_method_table,
-    initialize_class_scene_method_table, initialize_class_server_method_table, runtime_metadata,
+    initialize_binding, initialize_builtin_method_table, initialize_class_core_method_table,
+    initialize_class_editor_method_table, initialize_class_scene_method_table,
+    initialize_class_server_method_table, runtime_metadata,
 };
 
 #[cfg(not(wasm_nothreads))]
@@ -313,9 +315,18 @@ pub unsafe fn load_class_method_table(api_level: InitLevel) {
     let (class_count, method_count);
     match api_level {
         InitLevel::Core => {
-            // Currently we don't need to do anything in `Core`, this may change in the future.
-            class_count = 0;
-            method_count = 0;
+            // SAFETY: The interface has been initialized and this function hasn't been called before.
+            unsafe {
+                #[cfg(feature = "codegen-lazy-fptrs")]
+                initialize_class_core_method_table(ClassCoreMethodTable::load());
+                #[cfg(not(feature = "codegen-lazy-fptrs"))]
+                initialize_class_core_method_table(ClassCoreMethodTable::load(
+                    interface,
+                    &mut string_names,
+                ));
+            }
+            class_count = ClassCoreMethodTable::CLASS_COUNT;
+            method_count = ClassCoreMethodTable::METHOD_COUNT;
         }
         InitLevel::Servers => {
             // SAFETY: The interface has been initialized and this function hasn't been called before.
@@ -386,7 +397,7 @@ pub unsafe fn godot_has_feature(
     // Issue a raw C call to OS.has_feature(tag_string).
 
     // SAFETY: Called from main thread, interface has been initialized, and the scene api has been initialized.
-    let method_bind = unsafe { class_scene_api() }.os__has_feature();
+    let method_bind = unsafe { class_core_api() }.os__has_feature();
 
     // SAFETY: Called from main thread, and interface has been initialized.
     let interface = unsafe { get_interface() };

itest/rust/src/lib.rs

@@ -5,6 +5,8 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+use std::sync::Mutex;
+
 use godot::init::{gdextension, ExtensionLibrary, InitLevel};
 
 mod benchmarks;
@@ -18,10 +20,36 @@ mod register_tests;
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 // Entry point
 
+static LEVELS_SEEN: Mutex<Vec<InitLevel>> = Mutex::new(Vec::new());
+
 #[gdextension(entry_symbol = itest_init)]
 unsafe impl ExtensionLibrary for framework::IntegrationTests {
+    fn min_level() -> InitLevel {
+        InitLevel::Core
+    }
     fn on_level_init(level: InitLevel) {
-        // Testing that we can initialize and use `Object`-derived classes during `Servers` init level. See `object_tests::init_level_test`.
-        object_tests::initialize_init_level_test(level);
+        LEVELS_SEEN.lock().unwrap().push(level);
+        match level {
+            InitLevel::Core => {
+                // make sure we can access early core singletons
+                object_tests::test_early_core_singletons();
+            }
+            InitLevel::Servers => {}
+            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().unwrap().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);
     }
 }