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

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:24
lapis.cr:459
lapis.cr:502
lapis.cr:583
libgodot/bridge.cr
libgodot/channel.cr
libgodot/collections.cr
libgodot/debugger/agent.cr
libgodot/debugger/lldb_driver.cr
libgodot/doc_macro.cr
libgodot/editor.cr
libgodot/editor_script_creation.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/macros.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/system_io.cr
libgodot/types.cr
libgodot/variant.cr

Constant Summary

VERSION = "0.1.0"

Class Method Summary

• .audio_server : AudioServer
• .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)

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

• .await(signal : Godot::BoundSignal, timeout_sec : Number)

  Cooperatively awaits a bound signal with timeout.

• .await(seconds : Number) : Void

  Cooperatively pauses execution for the given duration in seconds.

• .await(span : ::Time::Span) : Void

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

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

  Cooperatively awaits a bound signal.

• .await(timer : SceneTreeTimer) : Void

  Cooperatively awaits a SceneTreeTimer until its countdown expires

• .clear_signal_subscriptions(target_id : UInt64) : Void

  Cleans up all signal subscriptions associated with a target instance ID

• .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

• .delay(seconds : Number) : Void

  Cooperatively pauses execution for the given duration in seconds.

• .delay(span : ::Time::Span) : Void

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

• .display_server : DisplayServer
• .editor_hint? : Bool

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

• .engine : Engine
• .input : Input

  Singleton accessors

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

  Resource and Scene loading helpers

• .load(path : String, as type : T.class, type_hint : String = "", cache_mode : Int64 = 0_i64) : T forall T
• .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.

• .load_scene(path : String) : PackedScene
• .next_frame : Void

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

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

  Notifies active subscribers that a signal has fired on an object

• .os : OS
• .performance : Performance
• .physics_frame : 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.

• .preload(path : String) : Resource

  Preloads/loads a resource from the given path

• .print(*args)

  Godot Engine Logging & Diagnostics System

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

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

• .project_settings : ProjectSettings
• .resource_loader : ResourceLoader
• .resource_saver : ResourceSaver
• .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) : SignalSubscription

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

• .to_godot_res_path(path : String) : String

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

• .unsubscribe_signal(sub : SignalSubscription) : Void

  Unsubscribes a signal subscription

Class Method Detail