Top Level Namespace

Included Modules

• Lapis::Test

Extended Modules

• Lapis::Test

Defined in:

Method Summary

• crystal_godot_init(api : Pointer(Godot::LibBridge::BridgeAPI)) : Void

  C ABI Entry point called by crystal_bridge when game library is loaded

• load(path : String, type_hint : String = "", cache_mode : Int64 = 0_i64) : Godot::Resource

  Global convenience helper to load resources from Godot VFS

• preload(path : String) : Godot::Resource

  Global convenience helper to preload resources from Godot VFS

• vec2(x : Number, y : Number) : Godot::Vector2

  Top-level math constructors

• vec3(x : Number, y : Number, z : Number) : Godot::Vector3
• vec4(x : Number, y : Number, z : Number, w : Number) : Godot::Vector4

Macro Summary

• abstract_class

  Convenience macro to designate a class as abstract in Godot.

• await(target, signal_name = nil, timeout_sec = nil)

  Top-level await macro for intuitive GDScript-like calling syntax Usage: await(enemy.died) await(enemy.died, timeout_sec: 2.0) await(enemy, "died") await(enemy, "died", timeout_sec: 2.0) await(timer.timeout) await(timer) await(1.5) await(2.seconds)

• await_until(condition, timeout_sec, &block)

  Cooperatively yields the current fiber until the condition evaluates to truthy.

• await_while(condition, timeout_sec, &block)

  Cooperatively yields the current fiber while the condition evaluates to truthy.

• cold_boot_test(category, name, &block)

  Dedicated declarative cold boot test macro

• define_log_filter(name, **opts)
• define_log_filters(&block)
• delegate_property_to_instance(*prop_names)

  Forwards class-level properties to the class singleton instance

• delegate_to_instance(*method_names)

  Forwards class-level methods to the class singleton instance (e.g.

• emit(signal_expr, *args)

  Type-safe signal emitter macro.

• ensure_lapis

  The primary node macro: Usage: node MyNode node MyNode do # defaults to Godot::Node end

• export_category(name, &block)

  Categories group top-level inspector sections in Godot.

• export_group(name, prefix = "", &block)

  Groups exported properties in the Godot inspector.

• export_subgroup(name, prefix = "", &block)

  Subgroups exported properties under the current inspector group.

• gdclass(decl, &block)

  Declares a custom RefCounted or generic Godot engine class registered with ClassDB.

• gmodule(decl, &block)

  Declares a reusable Godot module or mixin registered with ClassDB metadata.

• godot_bind(var_name, class_name, method_name, hash)

  Lazily retrieves and caches a GDExtension method bind handle from ClassDB

• godot_call_str(method_name, *args)

  Dynamically calls an instance method and returns the result as a Crystal String

• godot_collider_query(cls_name, indexed = false)

  Synthesizes null-safe #get_collider? query on raycasts and shapecasts

• godot_marshal_enum(name, idx)

  Marshals an enum or integer argument into a typed 64-bit pointer for ptrcall

• godot_marshal_nodepath(name, idx)

  Marshals a NodePath or String argument into an unmanaged Godot NodePath pointer

• godot_marshal_obj(name, idx)

  Marshals a Godot Object wrapper into an unmanaged pointer-to-pointer for ptrcall

• godot_marshal_str(name, idx)

  Marshals a String argument into an unmanaged Godot String pointer

• godot_marshal_string_name(name, idx)

  Marshals a String or StringName argument into an interned StringName pointer

• godot_marshal_val(name, idx)

  Marshals a primitive scalar (Float, Int, Bool, Vector2/3, Color) for ptrcall

• godot_module(decl)
• godot_prop(prop_name, getter_name, setter_name = nil)

  Synthesizes an ergonomic getter and setter pair

• godot_ptrcall(mb, target_ptr, args_slice, ret_ptr)

  Executes a low-overhead GDExtension ptrcall

• godot_ptrcall_bool(mb, target_ptr, args_slice)

  Executes a ptrcall returning a boolean

• godot_ptrcall_enum(mb, target_ptr, args_slice, enum_type)

  Executes a ptrcall returning a strongly-typed enum

• godot_ptrcall_float(mb, target_ptr, args_slice)

  Executes a ptrcall returning a float (Float64 / Float32)

• godot_ptrcall_float32(mb, target_ptr, args_slice)
• godot_ptrcall_float64(mb, target_ptr, args_slice)
• godot_ptrcall_int(mb, target_ptr, args_slice)

  Executes a ptrcall returning an integer (Int64)

• godot_ptrcall_obj(mb, target_ptr, args_slice, class_type)

  Executes a ptrcall returning a typed object wrapper

• godot_ptrcall_val(mb, target_ptr, args_slice, type_name)

  Executes a ptrcall returning a value type with default constructor (e.g.

• godot_ptrcall_void(mb, target_ptr, args_slice)

  Executes a void ptrcall with no return buffer

• godot_return_enum(enum_type, ret_var)

  Instantiates a strongly-typed enum from a 64-bit ptrcall return buffer

• godot_return_obj(class_type, ret_ptr)

  Wraps a returned native object pointer into its typed Crystal wrapper

• godot_signal(name, *types)

  Synthesizes a first-class typed signal accessor and direct emission helper

• godot_singleton(cls_name, godot_name, parent_type = Godot::Object)

  Defines a Godot singleton accessor and pointer caching

• godot_singleton_accessor(method_name, cls_name)

  Emits top-level Godot module singleton helper

• godot_static_call_str(method_name, *args)

  Dynamically calls a static engine method and returns the result as a Crystal String

• group(*group_names)

  Declaratively assigns the node to one or more scene tree groups upon _ready.

• icon(path)

  Convenience macro to set a custom icon path in the editor.

• log_filter(name, **opts)

  Re-export at top-level for maximum ergonomics

• multiplayer_test(name, clients = 2, &block)

  Dedicated declarative multiplayer simulation test macro

• n!(path, type = nil)

  Ultra-short aliases for node! and node?

• n?(path, type = nil)
• node(decl, &block)
• node!(path, type = nil)

  Compact node retrieval macro (GDScript $ analog).

• node2d(decl, &block)

  Expressive convenience macro for 2D scene nodes defaulting to Godot::Node2D

• node3d(decl, &block)

  Expressive convenience macro for 3D spatial nodes defaulting to Godot::Node3D

• node?(path, type = nil)

  Safe compact node retrieval macro (returns nil if not found).

• node_path!(path)

  Creates a compile-time verified Godot::NodePath

• node_ref(decl)

  Declares a node_ref property initialized from the scene tree during _ready.

• node_ref(name_or_decl, type = nil, path = nil)

  Declares a dead-pointer safe, lazy-cached node property matching Godot's @onready pattern.

• onready(decl)

  Declares an @onready node property initialized from the scene tree during _ready.

• onready(name, type, path = nil)

  Declares a lazy-cached node property matching Godot's @onready pattern.

• onready?(name, type, path = nil)

  Declares a safe, lazy-cached node property that returns nil if missing or type mismatch.

• resource(decl, &block)

  Declares a custom Godot Resource class registered with ClassDB and EditorHelp.

• signal(name_or_decl, *extra_types)

  Declares a custom Godot signal and generates a type-safe emit_<signal_name> helper method.

• static_unload

  Convenience macro to mark extension library unloading behavior.

• test_case(category, name, cold_boot = false, &block)

  Base test_case macro

• test_suite(category, &block)

  Declarative suite macro allowing grouped tests, parameterized tests, and suite/case lifecycle hooks

• u!(name, type = nil)

  Ultra-short aliases for unique! and unique?

• u?(name, type = nil)
• unique!(name, type = nil)

  Compact Scene Unique Node retrieval macro (GDScript % analog).

• unique?(name, type = nil)

  Safe compact Scene Unique Node retrieval macro (returns nil if not found).

• unique_node(name, type, unique_name = nil)

  Declares a lazy-cached Scene Unique Node property (Godot 4 %Node syntax).

• unique_node?(name, type, unique_name = nil)

  Declares a safe, lazy-cached Scene Unique Node property that returns nil if missing.

• unique_node_ref(decl)

  Declares a unique_node_ref property initialized from the scene tree during _ready.

• unique_node_ref(name_or_decl, type = nil, unique_name = nil)

  Declares a dead-pointer safe, lazy-cached Scene Unique Node property (Godot 4 %Node syntax).

• warning_ignore(name)

  Convenience macro to suppress compiler warnings.

• warning_ignore_restore(name)
• warning_ignore_start(name)

Method Detail

Macro Detail

emit(player.health_changed, 50, 100) # Expands to player.emit_health_changed(50, 100)
emit(player.renamed)                  # Expands to player.emit_renamed
emit(health_changed, 50, 100)         # Inside Player: expands to emit_health_changed(50, 100)
emit(sig, 50, 100)                    # Signal variable: expands to sig.emit(50, 100)

export_category "Combat" do
  @[Export]
  property health : Int32 = 100
end

export_group "Movement", prefix: "move_" do
  @[Export]
  property move_speed : Float32 = 5.0_f32
end

export_subgroup "Advanced", prefix: "adv_" do
  @[Export]
  property adv_friction : Float32 = 0.1_f32
end

gdclass StateMachine < RefCounted do
  @[Export]
  property current_state : String = "idle"
end

gdclass SimpleState

gmodule Damageable do
  signal health_changed(current : Int32, max : Int32)
  signal died

  @[Export(range: 0..100)]
  property health : Int32 = 100

  @[Export]
  property max_health : Int32 = 100

  def take_damage(amount : Int32) : Void
    self.health = Math.max(0, self.health - amount)
    emit(health_changed, self.health, self.max_health)
    emit(died) if self.health == 0
  end
end

node Player < CharacterBody2D do
  include Damageable
end

node Player < CharacterBody3D do
  group "players", "flammable"
end

onready? player, PlayerController, "Player"
onready? hud, GameHUD, "HUD"

resource ItemData < Resource do
  @[Export]
  property item_name : String = "Health Potion"

Declares a custom Resource subclass registered with ClassDB.
Defaults to inheriting `Resource` when no parent is specified.
Can be called with or without a block (e.g. `resource MyItem`).

class Player < Godot::CharacterBody3D
  signal health_changed(new_health : Int32, max_health : Int32)
  signal died

  def take_damage(amount : Int32)
    emit_health_changed(50, 100)
    emit_died if amount >= 100
  end
end

unique_node health_bar, ProgressBar      # fetches "%HealthBar"
unique_node main_hud, CanvasLayer, "HUD" # fetches "%HUD"

unique_node? health_bar, ProgressBar, "HealthBar"