module Godot

Overview

LibGodot for Crystal

High-performance Crystal bindings and 2-way host language integration for Godot Engine 4.8+.

Overview

LibGodot enables Crystal to act as the primary host language for Godot games, combining Crystal's LLVM-compiled speed and Ruby-like elegance with Godot's powerful scene tree, rendering, and editor tooling.

Key Features

• Native LibGodot Host (Option C): Crystal owns the executable (game.exe), initializing its runtime and Boehm GC cleanly before booting Godot in-memory via libgodot.dll.
• Clean Macro Syntax:
  • node MyNode do ... end (defaults to inheriting Godot::Node)
  • node Player < CharacterBody3D do ... end (inherits specified Godot node type)
  • signal health_changed(new_health : Int32)
  • @[Export] with full Godot Inspector hints (ranges, sliders, enums, bitflags, resource pickers, files, colors, arrays).
• Compile Button Hook: The Godot Editor's Play (F5) and Build buttons invoke crystal build via an EditorPlugin._build() hook.

Basic Example

require "libgodot"

node Player < CharacterBody3D do
  @[Export(range: 50.0_f32..800.0_f32, step: 10.0_f32)]
  property speed : Float32 = 300.0_f32

  @[Export(range: 100.0_f32..1000.0_f32, step: 25.0_f32)]
  property jump_velocity : Float32 = 450.0_f32

  signal health_changed(new_health : Int32, max_health : Int32)
  signal died

  def _ready
    puts "Player ready!"
  end

  def _physics_process(delta : Float64) : Void
    vel = velocity
    unless is_on_floor
      vel.y -= 980.0_f32 * delta.to_f32
    end
    if Input.is_action_just_pressed("jump") && is_on_floor
      vel.y = @jump_velocity
    end
    self.velocity = vel
    move_and_slide
  end
end

Extended Modules

• Godot::ClassMethods

Direct including types

• Lapis

Defined in:

editor/crystal_panel.cr
editor/debugger/crystal_debugger_plugin.cr
editor/debugger/debugger_session_tab.cr
editor/debugger/session_controller.cr
lapis.cr
lapis/color.cr
lapis/core/frame_arena.cr
lapis/core/static_signal_table.cr
lapis/cs_extras/signal_operators.cr
lapis/dsl/frame_arena_dsl.cr
lapis/extras/operators.cr
lapis/extras/wildcards.cr
lapis/gd_extras/editor_extras.cr
libgodot/autoload.cr
libgodot/bridge.cr
libgodot/channel.cr
libgodot/classes/audio_stream.cr
libgodot/classes/camera3d.cr
libgodot/classes/canvas_item.cr
libgodot/classes/character_body2d.cr
libgodot/classes/character_body3d.cr
libgodot/classes/collision_object2d.cr
libgodot/classes/collision_object3d.cr
libgodot/classes/collision_shape3d.cr
libgodot/classes/control.cr
libgodot/classes/input.cr
libgodot/classes/input_event.cr
libgodot/classes/main_loop.cr
libgodot/classes/node.cr
libgodot/classes/node2d.cr
libgodot/classes/node3d.cr
libgodot/classes/node_path.cr
libgodot/classes/object.cr
libgodot/classes/packed_scene.cr
libgodot/classes/physics_body2d.cr
libgodot/classes/physics_body3d.cr
libgodot/classes/progress_bar.cr
libgodot/classes/range.cr
libgodot/classes/ray_cast3d.cr
libgodot/classes/ref_counted.cr
libgodot/classes/resource.cr
libgodot/classes/scene_tree.cr
libgodot/classes/slider.cr
libgodot/classes/spin_box.cr
libgodot/classes/texture.cr
libgodot/collections.cr
libgodot/debugger/agent.cr
libgodot/debugger/context_classifier.cr
libgodot/debugger/decompiler.cr
libgodot/debugger/radare_driver.cr:14
libgodot/debugger/radare_driver.cr:712
libgodot/diagnostics.cr
libgodot/diagnostics/dispatch_profiler.cr
libgodot/diagnostics/leak_tracker.cr
libgodot/diagnostics/signal_spy.cr
libgodot/diagnostics/tombstone_tracker.cr
libgodot/doc_macro.cr
libgodot/docs.cr
libgodot/editor.cr
libgodot/editor_script_creation.cr
libgodot/errors.cr
libgodot/extensions.cr
libgodot/extensions/audio_server.cr
libgodot/extensions/config_file.cr
libgodot/extensions/image.cr
libgodot/extensions/input.cr
libgodot/extensions/multiplayer.cr
libgodot/extensions/node.cr
libgodot/extensions/packed_scene.cr
libgodot/extensions/physics.cr
libgodot/extensions/primitives.cr
libgodot/extensions/query.cr
libgodot/extensions/resource.cr
libgodot/extensions/scene_tree.cr
libgodot/extensions/spatial.cr
libgodot/extensions/timer.cr
libgodot/extensions/tween.cr
libgodot/extensions/viewport.cr
libgodot/generated/classes/classes_part1.cr
libgodot/generated/classes/classes_part2.cr
libgodot/generated/classes/classes_part3.cr
libgodot/generated/classes/classes_part4.cr
libgodot/generated/classes/classes_part5.cr
libgodot/generated/classes/classes_part6.cr
libgodot/generated/global_enums.cr
libgodot/generated/singletons.cr
libgodot/instance.cr
libgodot/logging.cr
libgodot/logging/channel.cr
libgodot/logging/filter.cr:1
libgodot/logging/filter.cr:125
libgodot/logging/logger.cr
libgodot/logging/macros.cr
libgodot/logging/record.cr
libgodot/logging/sink.cr
libgodot/macros.cr
libgodot/node_context.cr
libgodot/object.cr
libgodot/script.cr
libgodot/script/highlighter.cr
libgodot/script/language.cr
libgodot/script/lsp.cr
libgodot/script/resource_format.cr
libgodot/script/script.cr
libgodot/signals/bound_signal.cr
libgodot/signals/subscription.cr
libgodot/signals/typed_signal.cr
libgodot/system_io.cr
libgodot/testing.cr
libgodot/thread_safety.cr
libgodot/timer.cr:5
libgodot/timer.cr:222
libgodot/types/aabb.cr
libgodot/types/basis.cr
libgodot/types/color.cr
libgodot/types/plane.cr
libgodot/types/quaternion.cr
libgodot/types/rect2.cr
libgodot/types/rid.cr
libgodot/types/transform2d.cr
libgodot/types/transform3d.cr
libgodot/types/vector2.cr
libgodot/types/vector3.cr
libgodot/types/vector4.cr
libgodot/variant.cr

Constant Summary

CUSTOM_EXPORT_MACROS = {} of StringLiteral => ASTNode

EMPTY_VARIANT_ARGS = [] of Variant

Pre-allocated empty Variant array for zero-allocation parameterless signal dispatch.

MIN_CRYSTAL_VERSION = "1.20.0"

TARGET_CRYSTAL_VERSION = "1.21.0"

TARGET_GODOT_VERSION = "4.8-beta2"

VERSION = "0.2.3"

Class Method Summary

• .accessibility_server : AccessibilityServer
• .after(delay : ::Time::Span | Number, node : Godot::Node | Nil = nil, &block : TimerHandle -> Void) : TimerHandle

  Schedules a one-shot delay that fires after .delay.

• .audio_server : AudioServer
• .autoload(type : T.class) : T forall T

  Retrieves an autoload singleton instance by class type

• .autoload(name : String) : Godot::Node | Nil

  Retrieves an autoload singleton instance by name

• .await(target : Godot::Object, signal_name : String, timeout_sec : Float64 | Nil = nil) : AwaitStatus(Array(Variant))

  Cooperatively awaits until the named signal is emitted on the target object.

• .await(target : Godot::Object, signal_name : String, timeout_sec : Number) : AwaitStatus(Array(Variant))
• .await(signal : Godot::TypedSignal(*T), timeout_sec : Float64 | Nil = nil) forall T

  Cooperatively awaits a typed signal.

• .await(seconds : Number, timeout_sec : Float64 | Nil = nil) : AwaitStatus(Nil)

  Cooperatively pauses execution for the given duration in seconds.

• .await(signal : Godot::TypedSignal(*T), timeout_sec : Number) forall T
• .await(seconds : Number, timeout_sec : Number) : AwaitStatus(Nil)
• .await(span : ::Time::Span, timeout_sec : Float64 | Nil = nil) : AwaitStatus(Nil)

  Cooperatively pauses execution for the given Time::Span duration.

• .await(span : ::Time::Span, timeout_sec : Number) : AwaitStatus(Nil)
• .await(signal : Godot::BoundSignal, timeout_sec : Float64 | Nil = nil)

  Cooperatively awaits a bound signal.

• .await(signal : Godot::BoundSignal, timeout_sec : Number)
• .await(timer : SceneTreeTimer, timeout_sec : Float64 | Nil = nil) : AwaitStatus(Nil)

  =========================================================================== SceneTreeTimer Cooperative Await =========================================================================== Cooperatively awaits a SceneTreeTimer until its countdown expires.

• .await(timer : SceneTreeTimer, timeout_sec : Number) : AwaitStatus(Nil)
• .await!(target : Godot::Object, signal_name : String, timeout_sec : Float64 | Nil = nil) : Array(Variant)

  Cooperatively awaits until the named signal is emitted on the target object.

• .await!(target : Godot::Object, signal_name : String, timeout_sec : Number) : Array(Variant)
• .await!(signal : Godot::TypedSignal(*T), timeout_sec : Float64 | Nil = nil) forall T
• .await!(seconds : Number, timeout_sec : Float64 | Nil = nil) : Void

  Cooperatively pauses execution for the given duration in seconds.

• .await!(signal : Godot::TypedSignal(*T), timeout_sec : Number) forall T
• .await!(seconds : Number, timeout_sec : Number) : Void
• .await!(span : ::Time::Span, timeout_sec : Float64 | Nil = nil) : Void
• .await!(span : ::Time::Span, timeout_sec : Number) : Void
• .await!(signal : Godot::BoundSignal, timeout_sec : Float64 | Nil = nil)
• .await!(signal : Godot::BoundSignal, timeout_sec : Number)
• .await!(timer : SceneTreeTimer, timeout_sec : Float64 | Nil = nil) : Void

  Cooperatively awaits a SceneTreeTimer, raising DisposedObjectError if freed or TimeoutError if timeout_sec expires.

• .await!(timer : SceneTreeTimer, timeout_sec : Number) : Void
• .await?(target : Godot::Object, signal_name : String, timeout_sec : Float64 | Nil = nil) : Array(Variant) | Nil

  Cooperatively awaits until the named signal is emitted on the target object.

• .await?(target : Godot::Object, signal_name : String, timeout_sec : Number) : Array(Variant) | Nil
• .await?(signal : Godot::TypedSignal(*T), timeout_sec : Float64 | Nil = nil) forall T
• .await?(seconds : Number, timeout_sec : Float64 | Nil = nil) : Bool

  Cooperatively pauses execution for the given duration in seconds.

• .await?(signal : Godot::TypedSignal(*T), timeout_sec : Number) forall T
• .await?(seconds : Number, timeout_sec : Number) : Bool
• .await?(span : ::Time::Span, timeout_sec : Float64 | Nil = nil) : Bool
• .await?(span : ::Time::Span, timeout_sec : Number) : Bool
• .await?(signal : Godot::BoundSignal, timeout_sec : Float64 | Nil = nil)
• .await?(signal : Godot::BoundSignal, timeout_sec : Number)
• .await?(timer : SceneTreeTimer, timeout_sec : Float64 | Nil = nil) : Bool | Nil

  Cooperatively awaits a SceneTreeTimer, returning true on completion, false on timeout, or nil if freed.

• .await?(timer : SceneTreeTimer, timeout_sec : Number) : Bool | Nil
• .awaiting_fiber_count : Int32
• .awaiting_fiber_count=(awaiting_fiber_count : Int32)
• .breakpoint(can_continue : Bool = true) : Void

  Pauses execution in Godot's engine debugger or attached radare2 session

• .camera_server : CameraServer
• .channel(name : String) : LogChannel

  Access or register a user-defined log channel

• .class_db : ClassDB
• .clear_signal_subscriptions(target_id : UInt64, yield_awaiters : Bool = true) : Void

  Cleans up all signal subscriptions associated with a target instance ID (as emitter or receiver).

• .configure_channel(name : String, status : String = "active", min_level : LogLevel | Nil = nil, &block : LogChannel -> ) : LogChannel

  Configure a user-defined log channel with status, level, and filters

• .create(class_name : String) : Node | Nil

  Constructs a new native Godot engine object of the given class name (e.g.

• .create(type : T.class) : T forall T

  Constructs a new native Godot engine object and wraps it in the given Crystal class

• .create(type : T.class, &block : T -> ) : T forall T

  Constructs a new native Godot engine object, wraps it in T, and configures it in a block

• .debug(*args)

  Alias for .print_verbose

• .delay(seconds : Number, timeout_sec : Float64 | Nil = nil) : AwaitStatus(Nil)

  Cooperatively pauses execution for the given duration in seconds.

• .delay(seconds : Number, timeout_sec : Number) : AwaitStatus(Nil)
• .delay(span : ::Time::Span, timeout_sec : Float64 | Nil = nil) : AwaitStatus(Nil)

  Cooperatively pauses execution for the given Time::Span duration.

• .delay(span : ::Time::Span, timeout_sec : Number) : AwaitStatus(Nil)
• .delay!(seconds : Number, timeout_sec : Float64 | Nil = nil) : Void
• .delay!(seconds : Number, timeout_sec : Number) : Void
• .delay!(span : ::Time::Span, timeout_sec : Float64 | Nil = nil) : Void
• .delay!(span : ::Time::Span, timeout_sec : Number) : Void
• .delay?(seconds : Number, timeout_sec : Float64 | Nil = nil) : Bool
• .delay?(seconds : Number, timeout_sec : Number) : Bool
• .delay?(span : ::Time::Span, timeout_sec : Float64 | Nil = nil) : Bool
• .delay?(span : ::Time::Span, timeout_sec : Number) : Bool
• .dispatch_profiler
• .display_server : DisplayServer
• .dump_dispatch_profile(io : IO = STDOUT, top_n : Int32 = 20) : Void
• .dump_leaks(io : IO = STDERR) : Int32
• .editor_hint? : Bool

  Returns true if the code is currently executing inside the Godot Editor

• .editor_interface : EditorInterface
• .editor_text_input_focused? : Bool

  Returns true if running inside the Godot Editor and a text input control (LineEdit, TextEdit, or CodeEdit, such as an active EditorSpinSlider numeric input or Inspector string field) currently holds GUI keyboard focus.

• .emit(signal : Godot::TypedSignal(*T), *args : *T) : Void forall T

  Emits a typed signal with compile-time type safety.

• .emit(signal : Godot::BoundSignal, *args) : Void

  Emits a bound signal dynamically on its target object.

• .engine : Engine
• .engine_debugger : EngineDebugger
• .every(interval : ::Time::Span | Number, node : Godot::Node | Nil = nil, &block : TimerHandle -> Void) : TimerHandle

  Schedules a recurring timer that fires every interval.

• .gd_extension_manager : GDExtensionManager
• .gd_script_language_protocol : GDScriptLanguageProtocol
• .geometry2_d : Geometry2D
• .geometry3_d : Geometry3D
• .get_tree : SceneTree

  Returns the global SceneTree, or raises if not yet booted

• .get_tree? : SceneTree | Nil

  Returns the SceneTree if engine is currently running, or nil in headless/standalone specs

• .has_signal_subscribers?(target_id : UInt64, signal_name : String) : Bool

  Returns true if (target_id, signal_name) has any active SignalSubscription listeners.

• .has_untyped_signal_subscribers?(target_id : UInt64, signal_name : String) : Bool

  Returns true if (target_id, signal_name) has any active untyped BoundSignal / .await listeners.

• .in_typed_emit=(in_typed_emit : Bool)

  Re-entrancy guard when TypedSignal#emit dispatches through C++ Bridge.emit_signal.

• .in_typed_emit? : Bool

  Re-entrancy guard when TypedSignal#emit dispatches through C++ Bridge.emit_signal.

• .input : Input
• .input_map : InputMap
• .instantiate_scene(path : String, type : T.class) : T forall T
• .instantiate_scene(path : String) : Godot::Node
• .instantiate_scene?(path : String, type : T.class) : T | Nil forall T
• .instantiate_scene?(path : String) : Godot::Node | Nil
• .ip : IP
• .java_class_wrapper : JavaClassWrapper
• .java_script_bridge : JavaScriptBridge
• .leak_tracker
• .load(path : String, type_hint : String = "", cache_mode : Int64 = 0_i64) : Resource

  =========================================================================== Resource & Scene Loading Helpers ===========================================================================

• .load(path : String, type : T.class, type_hint : String = "", cache_mode : Int64 = 0_i64) : T forall T
• .load(path : String, *, as type : T.class, type_hint : String = "", cache_mode : Int64 = 0_i64) : T forall T

  Named argument variant for as: (e.g.

• .load?(path : String, type_hint : String = "", cache_mode : Int64 = 0_i64) : Resource | Nil

  Safe nil-returning resource loader (get_or_null parity)

• .load?(path : String, type : T.class, type_hint : String = "", cache_mode : Int64 = 0_i64) : T | Nil forall T

  Safe nil-returning typed resource loader

• .load_as(type : T.class, path : String, type_hint : String = "", cache_mode : Int64 = 0_i64) : T forall T
• .load_scene(path : String) : PackedScene
• .load_scene?(path : String) : PackedScene | Nil
• .log_history : Array(LogRecord)

  Returns the circular in-memory buffer of recent log records

• .logger : DiagnosticLogger

  Master diagnostic logger instance accessor

• .marshalls : Marshalls
• .native_menu : NativeMenu
• .navigation_mesh_generator : NavigationMeshGenerator
• .navigation_server2_d : NavigationServer2D
• .navigation_server2_d_manager : NavigationServer2DManager
• .navigation_server3_d : NavigationServer3D
• .navigation_server3_d_manager : NavigationServer3DManager
• .next_frame(timeout_sec : Float64 | Nil = 5.0) : Void

  Cooperatively yields until the next process (render/idle) frame has completed.

• .notify_object_queued_for_deletion(target_id : UInt64, yield_awaiters : Bool = true) : Void

  Marks all non-teardown signal subscriptions on a node queued for deletion (queue_free) as freed and yields on the Main Thread so awaiting fibers unblock immediately without waiting for frame end.

• .notify_signal(target_id : UInt64, signal_name : String, args : Array(Variant) = EMPTY_VARIANT_ARGS) : Void

  Notifies active subscribers that a signal has fired on an object.

• .notify_untyped_signal(target_id : UInt64, signal_name : String, args : Array(Variant) = EMPTY_VARIANT_ARGS) : Void

  Notifies only untyped BoundSignal / .await subscribers when a TypedSignal has already dispatched all typed fast-path subscribers through StaticSignalTable.

• .on_main_thread(&block : -> Void) : Void

  Global convenience delegator

• .os : OS
• .performance : Performance
• .physics_frame(timeout_sec : Float64 | Nil = 5.0) : Void

  Cooperatively yields until the next physics process frame has completed.

• .physics_frame_count : Int64

  Returns the total number of physics process steps executed since the engine started.

• .physics_server2_d : PhysicsServer2D
• .physics_server2_d_manager : PhysicsServer2DManager
• .physics_server3_d : PhysicsServer3D
• .physics_server3_d_manager : PhysicsServer3DManager
• .preload(path : String, as type : T.class) : T forall T
• .preload(path : String) : Resource

  Preloads/loads a resource from the given path (convenience alias to Godot.load)

• .preload?(path : String, as type : T.class) : T | Nil forall T
• .preload?(path : String) : Resource | Nil
• .print(*args)

  Prints a formatted message to the Godot console and records it to log sinks

• .print_error(msg : String, func : String = "", file : String = __FILE__, line : Int32 = __LINE__)

  Prints a rich structured error with function, file, and line details

• .print_verbose(*args)

  Prints a verbose diagnostic message that only appears when verbose logging is active

• .print_warning(msg : String, func : String = "", file : String = __FILE__, line : Int32 = __LINE__)

  Prints a rich structured warning with function, file, and line details

• .printerr(*args)

  Prints an error message to the Godot console and standard error

• .process_frame_count : Int64

  Returns the total number of frames rendered since the engine started.

• .project_settings : ProjectSettings
• .pump_awaiting_fibers_once_per_frame! : Void

  Cooperatively yields once per engine process frame if any fibers are actively awaiting signals.

• .register_filter(name : String, &block : LogFilterProc) : Void

  Register a globally named log filter

• .rendering_server : RenderingServer
• .resource_loader : ResourceLoader
• .resource_saver : ResourceSaver
• .resource_uid : ResourceUID
• .signal_spy

  Master diagnostics helpers for Lapis

• .signal_subs
• .signal_subs_mutex
• .spawn(&block : -> Void) : Fiber

  Spawns a cooperative gameplay fiber with managed exception logging.

• .subscribe_signal(target_id : UInt64, signal_name : String, flags : ConnectFlags = ConnectFlags::None, callback : Proc(Array(Variant), Void) | Nil = nil, receiver : Godot::Object | Nil = nil) : SignalSubscription

  Subscribes an awaiter or callback to a signal on a target object instance ID

• .text_server_manager : TextServerManager
• .texture_streaming : TextureStreaming
• .theme_db : ThemeDB
• .time : Time
• .to_godot_res_path(path : String) : String

  Converts any filesystem or relative path to a normalized Godot res:// path

• .tombstone_tracker
• .translation_server : TranslationServer
• .unsubscribe_signal(sub : SignalSubscription) : Void

  Unsubscribes a signal subscription

• .verbose? : Bool

  Returns true if the engine was launched with verbose logging enabled (--verbose)

• .wake_freed_awaiters! : Void

  Yields on the Main Thread until all recently freed awaiting subscriptions have woken up and exited .await.

• .worker_thread_pool : WorkerThreadPool
• .xr_server : XRServer

Macro Summary

• define_log_filter(name, tag = nil, name_tag = nil, color = nil, ansi = nil, level = nil)

  Alias for log_filter

• define_log_filters(&block)

  Block DSL for registering multiple log filters cleanly

• define_packed_array(name, elem_type, default_val)
• log(level, *args, **kwargs)

  Master log macro with AST elision, automatic tagging, and status handling

• log_channel(channel, level, message, **kwargs)

  Logs directly to a specific channel

• log_debug(category, message = nil, **kwargs)
• log_error(category, message = nil, **kwargs)
• log_filter(name, tag = nil, name_tag = nil, color = nil, ansi = nil, level = nil)

  Registers a single log filter definition anywhere in the codebase

• log_info(category, message = nil, **kwargs)
• log_internal(category, message = nil, **kwargs)
• log_public(level, category, message, **kwargs)

  Logs a message explicitly tagged as "public" with "public" status for public channels and distribution

• log_public_error(category, message = nil, **kwargs)
• log_public_info(category, message = nil, **kwargs)
• log_public_warn(category, message = nil, **kwargs)
• log_secret(level, category, message, **kwargs)

  Logs an internal/confidential message tagged as secret.

• log_trace(category, message = nil, **kwargs)
• log_warn(category, message = nil, **kwargs)

Class Method Detail

Macro Detail