Comparative Architectural Matrix: Host binary, loading mechanics, GC init, and primary use cases.

Key Topics & Information

• Mode A: Host is godot.exe, dynamic DLL loading via GDExtension bridge
• Mode B: Host is game.exe, statically or dynamically linked LibGodot host
• Mode A features instant F5 hot reloading via shadow copies
• Mode B provides minimal memory footprint and zero GDExtension loader overhead

Mode A: GDExtension Dynamic Loading: How Godot loads crystal_bridge.dll and bootstraps Crystal's runtime.

In Mode A (Development & Editor):

1. Godot boots and parses addons/crystal_integration/crystal.gdextension.
2. Godot calls crystal_library_init in crystal_bridge.dll.
3. The bridge initializes Boehm GC (GC_init()) and CRT hooks.
4. The bridge loads bin/game.dll (via shadow copy on Windows).
5. The bridge passes function pointers to crystal_godot_init.
6. Custom Crystal nodes register with Godot's ClassDB.

Mode B: Standalone LibGodot Host: Crystal executable hosting the Godot engine directly.

In Mode B (Production Shipping & Headless Runners):

1. The OS executes bin/game.exe (a native Crystal binary).
2. The Crystal CRT initializes Boehm GC natively.
3. The Crystal executable dynamically links bin/libgodot.dll.
4. Crystal invokes libgodot_create_godot_instance and drives the engine main loop.
5. Provides a self-contained, high-performance runtime for dedicated servers and production exports.