A. Dual-Paradigm Architecture

LibGodot for Crystal is designed around a dual-paradigm architecture that provides both rapid, hot-reloading in-editor game development and lean, standalone native executable production shipping:

1. Mode A: GDExtension In-Editor / Runner Paradigm (game.dll + crystal_bridge.dll)
2. Mode B: Standalone LibGodot Host Paradigm (game.exe + libgodot.dll)

---

Mode A: GDExtension In-Editor Workflow

Used when creating games inside the Godot Editor 4.8+ (make editor) or running via the Godot engine binary (make run).

In this mode:

• Godot is the parent host process (godot.exe).
• Godot discovers addons/crystal_integration/crystal.gdextension at startup.
• The manifest directs Godot to load bin/crystal_bridge.dll (a lightweight native C++ bridge).
• During library initialization (crystal_library_init):
  1. Godot passes its C-API function table pointer (GDExtensionInterfaceGetProcAddress).
  2. The bridge initializes the Boehm Garbage Collector (GC_init()) for Crystal.
  3. In development mode, the bridge creates a timestamped shadow copy of game.dll (game_loaded_<PID>_<timestamp>.dll) to prevent Windows OS file lock collisions.
  4. The bridge dynamically loads the shadow DLL via LoadLibraryA (or dlopen on Linux).
  5. The bridge resolves crystal_godot_init inside game.dll and hands over the BridgeAPI function table.
  6. Crystal registers custom nodes, signals, exported properties, and doc comments into Godot's ClassDB and EditorHelp subsystems.
• Pressing Play (F5) or Play Scene (F6) in the Godot editor invokes the EditorPlugin._build() hook in addons/crystal_integration/crystal_integration.gd, automatically recompiling game.dll and reloading without restarting Godot.

---

Mode B: Standalone LibGodot Host Paradigm

Used for standalone shipping builds (make game_exe), embedded deployments, or CI test runners.

In this mode:

• Crystal compiles as a standalone Windows PE executable (bin/game.exe).
• Crystal owns the main() entry point, boots its runtime, and configures GC natively.
• Godot is compiled as a shared library (bin/libgodot.dll).
• Crystal loads libgodot.dll in-memory using LibGodot::DynamicLoader.
• Crystal invokes libgodot_create_godot_instance(argc, argv, init_callback), passing its own command-line arguments and an initialization callback.
• Godot boots in-memory and invokes Crystal's Scene-level initialization callback, registering all nodes and scene hooks directly.
• Crystal steps the main loop, controls window initialization, and manages shutdown.

---

Comparison Table

Feature	Mode A (GDExtension Bridge)	Mode B (Standalone LibGodot)
Host Process	Godot Engine (godot.exe)	Crystal Executable (game.exe)
Shared Libraries	crystal_bridge.dll, game.dll	libgodot.dll
Godot Editor	Full support (Inspector, Node tree, F1 Help)	Headless or embedded window
Hot Reloading	Live shadow reload on F5 / F6	Recompilation of executable required
GC Bootstrapping	Initialized by C++ bridge (GC_init)	Initialized natively by Crystal CRT
Target Use-Case	Development, editing, prototyping	Standalone production distribution