module

Godot

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

Constants

VERSION = "0.1.0"

Class methods

audio_server
Source
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. Returns the emitted arguments as an Array(Variant). If the target object is freed while awaiting, raises Godot::DisposedObjectError.

Source
await(target : Godot::Object, signal_name : String, timeout_sec : Number) : Array(Variant)

Cooperatively awaits a signal on a target object with numeric timeout.

Source
await(signal : Godot::BoundSignal, timeout_sec : Number)

Cooperatively awaits a bound signal with timeout.

Source
await(seconds : Number) : Void

Cooperatively pauses execution for the given duration in seconds. Safe for use in cooperative fibers without blocking the Godot main loop.

Source
await(span : ::Time::Span) : Void

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

Source
await(signal : Godot::BoundSignal, timeout_sec : Float64 | Nil = nil)

Cooperatively awaits a bound signal. Usage: args = Godot.await(enemy.died) args = Godot.await(enemy.died, timeout_sec: 3.0)

Source
await(timer : SceneTreeTimer) : Void

Cooperatively awaits a SceneTreeTimer until its countdown expires

Source
clear_signal_subscriptions(target_id : UInt64) : Void

Cleans up all signal subscriptions associated with a target instance ID

Source
create(class_name : String) : Node | Nil

Constructs a new native Godot engine object of the given class name (e.g. "Node2D", "MeshInstance3D", "BoxMesh")

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

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

Source
delay(seconds : Number) : Void

Cooperatively pauses execution for the given duration in seconds. Alias to Godot.await(seconds).

Source
delay(span : ::Time::Span) : Void

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

Source
display_server
Source
editor_hint?

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

Source
engine
Source
input

Singleton accessors

Source
instantiate_scene(path : String, type : T.class) : T forall T
Source
load(path : String, type_hint : String = "", cache_mode : Int64 = 0_i64) : Resource

Resource and Scene loading helpers

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

Loads a resource and casts to the given Crystal resource class (e.g. PackedScene)

Source
load_scene(path : String) : PackedScene
Source
next_frame

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

Source
notify_signal(target_id : UInt64, signal_name : String, args : Array(Variant)) : Void

Notifies active subscribers that a signal has fired on an object

Source
performance
Source
physics_frame

Cooperatively yields until the next physics process frame has completed.

Source
physics_frame_count

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

Source
preload(path : String) : Resource

Preloads/loads a resource from the given path

Source
print(*args)

Godot Engine Logging & Diagnostics System

Source
print_error(msg : String, func : String = "", file : String = __FILE__, line : Int32 = __LINE__)
Source
print_warning(msg : String, func : String = "", file : String = __FILE__, line : Int32 = __LINE__)
Source
printerr(*args)
Source
process_frame_count

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

Source
project_settings
Source
resource_loader
Source
resource_saver
Source
signal_subs
Source
signal_subs_mutex
Source
spawn

Spawns a cooperative gameplay fiber with managed exception logging.

Source
subscribe_signal(target_id : UInt64, signal_name : String, flags : ConnectFlags = ConnectFlags::None, callback : Proc(Array(Variant), Void) | Nil = nil) : SignalSubscription

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

Source
to_godot_res_path(path : String) : String

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

Source
unsubscribe_signal(sub : SignalSubscription) : Void

Unsubscribes a signal subscription

Source

Nested types