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

Top-level gameplay convenience methods

Global fluent group query helper

Global convenience helper to load resources from Godot VFS

Global query helper returning all nodes matching the regex under the active node context.

Example:

nodes(~/coin_\d+/).each(&.queue_free)

Dispatches block to execute safely on the Godot Main Thread. Executes immediately if already on the main thread; queues if on a worker thread.

Global convenience helper to preload resources from Godot VFS

Top-level math constructors

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

Unlike eager onready var = path properties which initialize strictly during _ready, this macro defines a lazy getter that resolves the node on first access, caches the pointer, and verifies #check_alive! on every subsequent access to protect against dead-pointer dereferencing.

Supported Styles:

1. Auto-inferred name and type: onready sprite_2d, Sprite2D (fetches child "Sprite2D")
2. Scene Unique Node: onready camera, Camera2D, "%MainCamera"
3. Explicit path: onready sprite, Sprite2D, "Visuals/Sprite2D"

Example:

node Enemy < CharacterBody2D do
  onready sprite, Sprite2D, "Visuals/Sprite2D"
  onready health_bar, ProgressBar, "%HealthBar"

  def hit : Void
    sprite.modulate = Godot::Color.new(1.0, 0.0, 0.0) # Resolves and caches sprite
  end
end

Internal generator synthesizing dead-pointer safe, lazy-cached node property accessors.

Convenience macro to designate a class as abstract in Godot.

Cooperatively awaits a signal, timer, or duration without blocking the engine main thread.

Rationale & Execution Model:

In Godot, asynchronous gameplay events (animations, dialogue timers, death signals) must not block the engine's main loop (_process / _physics_process). Standard Crystal sleep suspends the entire OS thread and hangs the engine.

await suspends only the calling Crystal fiber, polling Godot cooperatively across frame steps while ensuring:

1. Zero main thread stalling.
2. Immediate dead-pointer protection: if the emitting node is freed (destroy/free/queue_free) while waiting, await unblocks immediately with status.freed? == true (while await! raises Godot::DisposedObjectError and await? returns nil).
3. Optional timeout support with automated timeout cancellation.

Supported Calling Forms:

# 1. First-class bound signal:
await(enemy.died)
await(enemy.died, timeout_sec: 5.0)

# 2. Dynamic target and string signal name:
await(boss, "phase_transition")
await(boss, "phase_transition", timeout_sec: 10.0)

# 3. SceneTree timer:
await(get_tree.create_timer(1.5).timeout)

# 4. Numeric delay in seconds:
await(1.5)
await(2.seconds)

Cooperatively awaits a signal, timer, or duration, raising Godot::DisposedObjectError if the target is freed or Godot::TimeoutError if timeout expires.

Cooperatively awaits a signal, timer, or duration, returning nil if the target is freed, or nil (or false) if timeout expires.

Cooperatively yields the calling fiber until condition evaluates to truthy.

Uses Fiber.yield between evaluation cycles. Supports an optional timeout_sec parameter which raises Godot::TimeoutError if exceeded.

Example:

await_until(character.on_floor?, timeout_sec: 5.0)

Cooperatively yields the calling fiber while condition evaluates to truthy.

Uses Fiber.yield between evaluation cycles. Supports an optional timeout_sec parameter which raises Godot::TimeoutError if exceeded.

Example:

await_while(tween.is_running, timeout_sec: 3.0)

Idiomatic alias for create

Dedicated declarative cold boot test macro

Instantiates a Godot object or custom node and configures its properties and methods in a block or kwargs.

Supports:

1. Keyword properties: create Sprite2D, position: Vector2.new(10, 20), centered: true
2. Block property setters: create Sprite2D do position = Vector2.new(10, 20); centered = true end
3. Method dispatches: create Sprite2D do add_to_group("sprites"); rotate(0.5) end
4. Mixed kwargs and block: create Sprite2D, centered: true do position = Vector2.new(10, 20) end

Declarative alias for spawn_node

Defines a custom export macro macro_name that declares an exported String property with PROPERTY_HINT_ENUM (2_u32) and hint_string in the Godot Inspector.

Forwards class-level properties to the class singleton instance

Forwards class-level methods to the class singleton instance (e.g. Input, AudioServer)

Type-safe signal emitter macro.

Emits signals directly via TypedSignal#emit or emit_signal.

Examples:

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

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

node Player < CharacterBody3D node Player < CharacterBody3D do # inherits Godot::CharacterBody3D end Expressive loader macro to ensure Lapis engine bindings are loaded without duplicate require cycles or missing dependency errors

Categorizes top-level inspector sections in Godot.

May be used standalone or as a block scoping exported properties.

Example:

node Boss < CharacterBody3D do
  export_category "Combat Stats" do
    @[Export]
    property health : Int32 = 1000

    @[Export]
    property defense : Int32 = 50
  end
end

Groups exported properties under a common folding group in the Godot inspector.

May be used standalone or as a block scoping exported properties.

Example:

node Vehicle < CharacterBody3D do
  export_group "Engine", prefix: "engine_" do
    @[Export]
    property engine_power : Float32 = 250.0_f32

    @[Export]
    property engine_torque : Float32 = 400.0_f32
  end
end

Subgroups exported properties under the current inspector group.

May be used standalone or as a block scoping exported properties.

Example:

node Character < CharacterBody3D do
  export_group "Movement" do
    export_subgroup "Advanced", prefix: "adv_" do
      @[Export]
      property adv_friction : Float32 = 0.1_f32
    end
  end
end

Declares a custom RefCounted or generic Godot engine class registered with ClassDB. Defaults to inheriting RefCounted when no parent is specified. Can be called with or without a block (e.g. gdclass MyState).

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

gdclass SimpleState

Declares a reusable Godot module or mixin registered with ClassDB metadata. Can declare properties (with @[Export]), signals, lifecycle hooks, and interface methods. When included into a node, gdclass, or resource via include, its properties and signals are automatically registered with ClassDB and dispatched via the GDExtension bridge.

Examples:

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

Lazily retrieves and caches a GDExtension method bind handle from ClassDB

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

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

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

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

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

Marshals a String argument into an unmanaged Godot String pointer

Marshals a String or StringName argument into an interned StringName pointer

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

Synthesizes an ergonomic getter and setter pair

Executes a low-overhead GDExtension ptrcall

Executes a ptrcall returning a boolean

Executes a ptrcall returning a strongly-typed enum

Executes a ptrcall returning a float (Float64 / Float32)

Executes a ptrcall returning an integer (Int64)

Executes a ptrcall returning a typed object wrapper, reusing alive instance if present

Executes a ptrcall returning a typed object wrapper, or nil if Godot returned nullptr

Executes a ptrcall returning a value type with default constructor (e.g. Vector2, Vector3, Color, Transform3D)

Executes a void ptrcall with no return buffer

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

Wraps a returned native object pointer into its typed Crystal wrapper

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

Defines a Godot singleton accessor and pointer caching

Emits top-level Godot module singleton helper

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

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

The node macro extracts all group statements and registers them automatically in Godot's SceneTree when the node enters the tree.

Example:

node Player < CharacterBody3D do
  group "players", "damageable", "interactable"
end

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

Loads a PackedScene (.tscn) and instantiates it as wrapper type T with configuration

Loads a PackedScene (.tscn), instantiates it as wrapper type T, and attaches it as a child to the parent

Loads a resource dynamically from the Godot virtual filesystem with compile-time type inference.

Supported extensions:

• .tscn, .scn -> Godot::PackedScene
• .png, .svg, .webp -> Godot::Texture2D
• .wav, .ogg, .mp3 -> Godot::AudioStream
• Other / .tres -> Godot::Resource

For custom types, chain .as(Type):

config = load("res://data.tres").as(CustomConfig)

Safe, nil-returning variant of load(path).

Returns nil if the resource fails to load or does not exist on disk.

Example:

if scene = load?("res://dlc/bonus_level.tscn")
  # ...
end

Re-export at top-level for maximum ergonomics

Expression-oriented pattern matching macro designed for concise, expressive gameplay scripting.

Returns the evaluated result of the first matching branch, or nil if no branch matched.

Rationale & Architectural Design:

While Crystal's native case / when statement is powerful, game development in Godot requires specialized pattern matching capabilities that native case cannot express:

1. Variant Unboxing: Automatically extracting typed values from dynamically typed Godot::Variant.
2. Dead-Pointer Safe Node Downcasting: Verifying #alive? during downcasting so freed nodes never match.
3. Implicit Variable Binding: Allowing match i do is Int64 do "Value: #{i * 2}" end without repetitive |i| closures.
4. String & Symbol Equivalence: Matching :action against "action" seamlessly for input and state machines.
5. Structural Destructuring: Extracting elements from Tuples, Arrays with rest ranges ([first, .., last]), and Dictionaries.

Supported Syntax Patterns:

1. Implicit Variable Binding (Variable is narrowed to branch type):

value_text = match i do
  is Int64          do "Integer: #{i * 2}" end
  is String         do "Text: #{i.upcase}" end
  is Godot::Vector2 do "Vector: (#{i.x}, #{i.y})" end
  default           do "Unsupported Variant" end
end

2. Explicit Parameter Binding:

description = match hit.collider do
  is Player do |player| "Player with #{player.health} HP" end
  is Enemy  do |enemy|  "Enemy of level #{enemy.level}" end
  default   do "Non-entity obstacle" end
end

3. Guard Clauses (if: named argument):

label = match score do
  is Int64, if: score > 1000 do "High Score: #{score}" end
  is Int64                   do "Normal Score: #{score}" end
  default                    do "Invalid" end
end

4. Multi-Pattern Splats:

match state do
  is :idle, :standing do play_animation("idle") end
  is :run, :sprint    do play_animation("run") end
end

5. Tuple Destructuring:

match {state, on_floor?} do
  is :jumping, false do apply_air_control end
  is :jumping, true  do land! end
end

6. Array Rest Matching:

match inventory do
  is [first, .., last] do |f, l| "First: #{f}, Last: #{l}" end
  default do "Empty or small" end
end

7. Dictionary Matching:

match packet do
  is dict(type: "chat", body: msg) do |_, text| display_message(text) end
  default do handle_unknown_packet end
end

Dedicated declarative multiplayer simulation test macro

Ultra-short alias for node!(path, type).

Ultra-short alias for node?(path, type).

Immediately retrieves a child node from the current node's scene hierarchy.

Provides GDScript $ parity with static type casting.

Supported Patterns:

1. Type-inferred: node!(Sprite2D) -> looks up "Sprite2D" and casts to Sprite2D
2. Path with Type: node!("Visuals/Sprite2D", Sprite2D) -> resolves path and casts to Sprite2D
3. Path string: node!("Visuals/Sprite2D") -> resolves path as untyped Godot::Node

Raises Godot::NodeNotFoundError if the node is not found or fails type casting.

Example:

def _ready : Void
  sprite = node!(Sprite2D)
  camera = node!("Pivot/Camera3D", Camera3D)
end

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

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

Safely retrieves a child node from the current node's scene hierarchy, returning nil if not found.

Supported Patterns:

1. Type-inferred: node?(Sprite2D) -> looks up "Sprite2D", returns Sprite2D?
2. Path with Type: node?("Visuals/Sprite2D", Sprite2D) -> returns Sprite2D?
3. Path string: node?("Visuals/Sprite2D") -> returns Godot::Node?

Creates a compile-time verified Godot::NodePath

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

Supports:

1. Macro signature: node_ref player, Player, "Player"
2. Type declaration: node_ref player : Player = "Player"
3. Auto-inferred: node_ref sprite_2d : Sprite2D

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

Examples:

node_ref? player, PlayerController, "Player"
node_ref? hud : GameHUD = "HUD"

Expressive signal connection macro

Supports:

1. First-class signal: on button.pressed { do_something }
2. Positional type filter: on body_entered, Player { |p| p.collect }
3. Multi-argument type filters: on item_equipped, Player, Sword { |p, s| ... }
4. Any wildcard filter: on damage_received, Player, Any { |p, info| ... }
5. One-shot execution: on boss.died, Player, once: true { |p| ... }
6. Target and signal string: on enemy, "died" { |bounty| add_score(bounty) }

Zero-allocation static signal connection macro binding compile-time typed procs or blocks directly to StaticSignalTable slots.

Can be used both:

1. Declaratively at class body scope inside node or gmodule:

   node Player < CharacterBody3D do
     signal health_changed(new_health : Int32, max_health : Int32)
     signal died
   
     on_signal health_changed, ->on_health_changed(Int32, Int32)
     on_signal :died, ->on_died, once: true
   
     def on_health_changed(hp : Int32, max : Int32) : Void
     end
   
     def on_died : Void
     end
   end

2. Imperatively inside methods or scripts:

   on_signal player.health_changed, ->(hp : Int32, max : Int32) { ... }
   on_signal player.health_changed_slot, handler_proc
   on_signal player, :health_changed, handler_proc, once: true
   on_signal player.health_changed do |hp, max|
     ...
   end

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

Examples:

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

Context-aware one-shot audio playback macro:

• Inspects @type at compile-time:
  • @type <= Godot::Node2D -> emits AudioStreamPlayer2D with global_position
  • @type <= Godot::Node3D -> emits AudioStreamPlayer3D with global_position
  • Otherwise -> emits non-spatial AudioStreamPlayer
• If explicit at: coordinate is passed (Vector2 or Vector3), spatializes appropriately
• Automatically preloads or loads the AudioStream
• Sets kwargs properties (e.g. pitch_scale: 1.2, volume_db: -5.0, bus: "SFX")
• Executes inline configuration block (e.g. do pitch_scale = 1.2 end)
• Attaches to active scene root (current_scene || root) so audio survives caller deletion!
• Connects finished.once { queue_free } for automatic memory cleanup
• Returns the strongly-typed audio player

Preloads and caches a resource from the Godot virtual filesystem with compile-time type inference.

Supported extensions:

• .tscn, .scn -> Godot::PackedScene
• .png, .svg, .webp -> Godot::Texture2D
• .wav, .ogg, .mp3 -> Godot::AudioStream
• Other / .tres -> Godot::Resource

For custom types, chain .as(Type):

const CONFIG = preload("res://data.tres").as(CustomConfig)

Safe, nil-returning variant of preload(path).

Returns nil if the resource fails to load or does not exist on disk.

Example:

if icon = preload?("res://custom_icon.png")
  # ...
end

Declares a custom Godot Resource class registered with ClassDB and EditorHelp. Supports @[Export] properties, custom signals, and serialization to .tres.

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`).

resource CustomPotion do @[Export] property item_name : String = "Health Potion"

@[Export] property value : Int32 = 50 end

resource ShortItem

Declares a custom Resource strategy card.

Custom Resources inheriting from Godot::Resource act as pluggable strategy objects and data containers (e.g. inventory items, ability cards, weapon stats).

Example:

resource_card WeaponCard < Resource do
  @[Export]
  property damage : Int32 = 50
  @[Export]
  property cooldown : Float32 = 1.0_f32

  def use(target : CharacterBody2D) : Void
    # strategy implementation
  end
end

Declares a custom Godot signal with first-class typed signal accessors.

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

  def take_damage(amount : Int32)
    health_changed.emit(50, 100)
    died.emit if amount >= 100
  end
end

Contextual alias for spawn_node

Instantiates a node, configures it, and attaches it as a child to the specified parent (defaults to self if inside a Node method, or current scene / root).

Convenience macro to mark extension library unloading behavior.

Base test_case macro

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

Block-based tween DSL targeting specified node with compile-time type verification (e.g. tween(player) do animate(...) end)

Block-based tween DSL targeting self (e.g. tween do animate(...) end)

Compile-time type-safe tween macro supporting dot-navigation (e.g. tween(boss.position.y, to: 150.0))

Ultra-short alias for unique!(name, type).

Ultra-short alias for unique?(name, type).

Immediately retrieves a Scene Unique Node (Godot 4 %Node syntax).

Automatically prepends % to the identifier if not already present.

Supported Patterns:

1. Type-inferred: unique!(ProgressBar) -> looks up "%ProgressBar" as ProgressBar
2. Name with Type: unique!("HealthBar", ProgressBar) -> looks up "%HealthBar" as ProgressBar
3. Name string: unique!("HealthBar") -> looks up "%HealthBar" as Godot::Node

Raises Godot::NodeNotFoundError if the unique node does not exist.

Safely retrieves a Scene Unique Node (Godot 4 %Node syntax), returning nil if not found.

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

Examples:

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

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

Examples:

unique_node? health_bar, ProgressBar, "HealthBar"

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

Supports:

1. Macro signature: unique_node_ref camera, Camera2D, "MainCamera"
2. Type declaration: unique_node_ref camera : Camera2D = "MainCamera"
3. Auto-inferred: unique_node_ref main_hud : CanvasLayer

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

Examples:

unique_node_ref? camera, Camera2D, "MainCamera"
unique_node_ref? hud : CanvasLayer

Convenience macro to suppress compiler warnings.