Skip to content

Conversation

@Bromeon
Copy link
Member

@Bromeon Bromeon commented Oct 22, 2025

Iterates on the API design for main-loop callbacks, introduced in #1313.
Quick comparison:

(0): Status quo (master)

Separate methods for each callback. Direct C mapping.

trait ExtensionLibrary {
    fn on_main_loop_startup() {}
    fn on_main_loop_frame() {}
    fn on_main_loop_shutdown() {}
}

(1): Group main-loop together

See first commit 74f9a01.

enum MainLoopEvent {
    Init,
    Frame,
    Deinit,
}

trait ExtensionLibrary {
    fn on_main_loop_event(event: MainLoopEvent) {}
}

Smaller API in ExtensionLibrary and fully independent of existing InitLevel, at the cost of enum + case differentiation even for Frame.

(2): Group init level/stage together

See second commit a1d9adc.

// Like InitLevel with added MainLoop
enum InitStage {
    Core,
    Servers,
    Scene,
    Editor,
    MainLoop,
}

trait ExtensionLibrary {
    fn on_stage_init(stage: InitStage) {}
    fn on_stage_deinit(stage: InitStage) {}
    fn on_main_loop_frame() {}
}

Consistently treats all initialization stages (main loop has strict ordering > init levels). However, both InitLevel + InitStage will need to coexist, as the latter cannot be used for e.g. a class' init level.

@Bromeon Bromeon added quality-of-life No new functionality, but improves ergonomics/internals c: ffi Low-level components and interaction with GDExtension API labels Oct 22, 2025
@GodotRust
Copy link

API docs are being generated and will be shortly available at: https://godot-rust.github.io/docs/gdext/pr-1380

@Bromeon Bromeon force-pushed the qol/main-loop-api branch 3 times, most recently from bd6e127 to eb85854 Compare October 22, 2025 20:41
@Bromeon Bromeon changed the title ExtensionLibrary: merge 3 on_main_loop_*() methods -> on_main_loop_event() ExtensionLibrary::on_main_loop_*: merge into new on_stage_init/deinit API Oct 23, 2025
Copy link
Contributor

@TitanNano TitanNano left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer Solution 2. It feels most consistent with what we already have and does not introduce two extra functions.

@Bromeon Bromeon force-pushed the qol/main-loop-api branch 3 times, most recently from d841973 to 2c7085e Compare October 23, 2025 17:36
@Bromeon Bromeon marked this pull request as ready for review October 23, 2025 17:36
@Bromeon Bromeon force-pushed the qol/main-loop-api branch 3 times, most recently from f2848f5 to dced4e3 Compare October 23, 2025 19:41
…frame

Add InitStage as a superset of InitLevel, with added MainLoop variant.
Integrates into the layered approach of on_level_[de]init, but with a new
pair of methods due to backwards compatibility.
We previously used a type alias because `use` statements don't allow RustDoc in this case.
However, this caused many broken links and shows up in a "Type Aliases" section, rather than
in "Enums" next to `InitStage`.

The new setup requires HTML links because the godot-ffi crate doesn't know the symbols, but
it ultimately works, and we can also avoid duplicating docs.
@Bromeon Bromeon enabled auto-merge October 23, 2025 19:55
@Bromeon Bromeon added this pull request to the merge queue Oct 23, 2025
@github-merge-queue github-merge-queue bot removed this pull request from the merge queue due to failed status checks Oct 23, 2025
@Bromeon Bromeon added this pull request to the merge queue Oct 23, 2025
@Bromeon Bromeon removed this pull request from the merge queue due to a manual request Oct 23, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

c: ffi Low-level components and interaction with GDExtension API quality-of-life No new functionality, but improves ergonomics/internals

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants