module
Lapis::Docs::I_ARCHITECTURE_AND_EXTENSIONS::B_CPP_BRIDGE_LOADER
Overview
Native C++ Loader Bridge Architecture
Technical analysis of src/bridge/crystal_bridge.cpp, resolving Godot GDExtension interface
tables and bridging them across flat C-ABI boundaries into Crystal.
Executive Summary & Key Topics
| Topic | Method / Anchor | Description |
|---|---|---|
| Bridge Responsibilities | .topic_00_bridge_responsibilities |
GC initialization, C-ABI flattening, ClassDB dispatch, and crash isolation. |
| The BridgeAPI Function Pointer Table | .topic_01_function_pointer_table |
How Crystal receives direct Godot engine entry points. |
Related Guides & Source References
- Bridge Source:
src/bridge/crystal_bridge.cpp - Module Loader:
src/bridge/module_loader.hpp - GDExtension API:
src/bridge/gdextension_api.hpp
Defined in:
libgodot/docs/i_architecture_and_extensions/b_cpp_bridge_loader.crClass Method Summary
-
.topic_00_bridge_responsibilities : Nil
Bridge Responsibilities: GC initialization, C-ABI flattening, ClassDB dispatch, and crash isolation.
-
.topic_01_function_pointer_table : Nil
The BridgeAPI Function Pointer Table: How Crystal receives direct Godot engine entry points.
Class Method Detail
Bridge Responsibilities: GC initialization, C-ABI flattening, ClassDB dispatch, and crash isolation.
Key Topics & Information
- Boehm GC initialization (GC_init) before any Crystal code runs
- Flattens Godot's C++ virtual dispatches into direct C function pointers
- Tracks loaded modules and handles shadow DLL lifecycle
- Guards entry points against concurrent re-initialization
The BridgeAPI Function Pointer Table: How Crystal receives direct Godot engine entry points.
During initialization, crystal_bridge.cpp populates a flat BridgeAPI structure containing direct function pointers to Godot engine entry points:
gd_classdb_register_extension_classgd_classdb_register_extension_class_methodgd_classdb_register_extension_class_propertygd_classdb_register_extension_class_signalgd_variant_get_ptr_utility_function
When crystal_godot_init(&g_bridge_api) is called, Crystal stores these function pointers in Godot::Bridge, bypassing all C++ ABI name mangling and calling engine routines at raw C speed!