module Docs::L_MACRO_DSL_REFERENCE

Overview

Macro DSL Reference & In-Editor Reflection Manual

LibGodot provides a expressive, compile-time checked Domain Specific Language (DSL) for declaring Godot engine classes, resources, refcounted objects, inspector exports, signals, RPC endpoints, and editor tools.

All macros expand into native Godot ClassDB registrations during library initialization without runtime reflection overhead.

1. Class Declaration Macros

Macro	Default Superclass	Zero-Block Syntax	Description
`node Name < Parent do ... end`	`Godot::Node`	`node Name` or `node Name < Parent`	Declares a scene graph Node class exposed to Godot's ClassDB.
`resource Name < Parent do ... end`	`Resource`	`resource Name` or `resource Name < Parent`	Declares a serializable Godot Resource class (.tres / .res).
`gdclass Name < Parent do ... end`	`RefCounted`	`gdclass Name` or `gdclass Name < Parent`	Declares a reference-counted engine class managed by ObjectDB.

Syntax Examples

require "libgodot"

# 1. Node with explicit parent and block
node PlayerController < CharacterBody3D do
  @[Export]
  property speed : Float32 = 7.5_f32

  def _physics_process(delta : Float64) : Void
    # Movement code
  end
end

# 2. Zero-block node inheriting default Godot::Node
node WorldManager

# 3. Zero-block node with explicit parent
node CustomCamera < Camera3D

# 4. Resource inheriting default Resource
resource InventoryItem do
  @[Export]
  property item_name : String = "Health Potion"

  @[Export]
  property power : Int32 = 50
end

# 5. Zero-block resource defaulting to Resource
resource QuestData

# 6. RefCounted class using gdclass
gdclass StateMachine do
  property state : String = "idle"
end

# 7. RefCounted class using gdclass (zero-block)
gdclass DataPacket

2. Property Export Annotations

Export annotations configure how Crystal properties are presented in the Godot Inspector, serialized to disk (.tscn / .tres), and exposed to GDScript.

Annotation	Arguments	Inspector Widget
`@[Export]`	None	Standard typed editor (number, string, color, vector)
`@[ExportRange]`	`min..max, step: n, or_greater: bool, or_less: bool`	Numeric slider bar with bounds and step increments
`@[ExportEnum]`	`EnumType`	Dropdown selection list of named enum values
`@[ExportFile]`	`filter: ".png,.jpg"`	File system picker dialog with extension filter
`@[ExportDir]`	None	Directory path picker dialog
`@[ExportMultiline]`	None	Multi-line expandable text area
`@[ExportPlaceholder]`	`text: "Placeholder..."`	Text field with gray placeholder text when empty
`@[ExportColorNoAlpha]`	None	Color picker with alpha/opacity channel locked at 1.0
`@[ExportExpEasing]`	`attenuation: bool, positive_only: bool`	Interactive exponential easing curve visualization widget
`@[ExportNodePath]`	`type: "Camera3D"`	NodePath picker constrained to matching node types in scene
`@[ExportFlags]`	`FlagEnumType`	Multi-select checkbox list for bitfield flags
`@[ExportFlags2DRender]`	None	Godot 2D render layer visibility bitmask checkboxes
`@[ExportFlags2DPhysics]`	None	Godot 2D physics collision layer bitmask checkboxes
`@[ExportFlags3DPhysics]`	None	Godot 3D physics collision layer bitmask checkboxes
`@[ExportGroup]`	`name: "Combat", prefix: "combat_"`	Collapsible category grouping header in Inspector
`@[ExportSubgroup]`	`name: "Defenses", prefix: "combat_def_"`	Nested subcategory header within an inspector group
`@[ExportStorage]`	None	Serialized with scene/resource but hidden from the Inspector
`@[ExportToolButton]`	`text: "Execute Action", icon: "res://icon.png"`	Clickable push button rendered directly in the Inspector

Export Example

enum CharacterClass
  Warrior = 1
  Mage    = 2
  Rogue   = 4
end

node Hero < CharacterBody2D do
  @[ExportGroup("Attributes", prefix: "attr_")]
  @[ExportRange(1..100, step: 1)]
  property attr_level : Int32 = 1

  @[ExportEnum(CharacterClass)]
  property attr_hero_class : CharacterClass = CharacterClass::Warrior

  @[ExportGroup("Media", prefix: "media_")]
  @[ExportFile("*.png,*.tres")]
  property media_avatar : String = "res://avatar.png"

  @[ExportColorNoAlpha]
  property theme_color : Godot::Color = Godot::Color.new(0.2, 0.6, 1.0, 1.0)

  @[ExportToolButton("Recalculate Stats")]
  def recalculate_stats : Void
    Godot.print("Recalculating stats for level #{attr_level}...")
  end
end

3. Signal Declaration & Ergonomic Listeners

Signals connect nodes loosely across Crystal, GDScript, and C++.

Declaration	Generated Emission Method	Generated Listener
`signal died`	`emit_died`	`on_died { ... }`, `on_died_once { ... }`
`signal damage_taken(amount : Int32, source : String)`	`emit_damage_taken(amount, source)`	`on_damage_taken { \|amt, src\| ... }`

First-Class Signal Awaiting

# Await bound signal directly:
await(hero.died, timeout_sec: 10.0)
hero.died.await(timeout_sec: 10.0)

# Await by string name:
await(hero, "damage_taken", timeout_sec: 5.0)
hero.await_signal("damage_taken", timeout_sec: 5.0)

4. Behavioral & Execution Directives

Directive	Scope	Description
`@[Tool]` or `tool`	Class level	Enables execution inside the Godot Editor in real time (for gizmos, previews, tool buttons).
`@[RPC]`	Method level	Configures multiplayer network replication (call_local, mode, channel).
`onready name : Type = path`	Property level	Lazy node lookup evaluated during `_ready`.

Defined in:

libgodot/docs.cr

Class Method Summary

.features : Array(String)

Class Method Detail

def self.features : Array(String) #

[View source]

lapis