module Lapis::Docs::C_GAMEPLAY_AND_DECLARATIVE_DSL::A_NODE_DSL

Overview

Declarative Node DSL & Lifecycle

Comprehensive guide to authoring gameplay entities using Lapis's declarative Node DSL, ClassDB registration, and engine lifecycle virtual methods.

Executive Summary & Key Topics

Topic Method / Anchor Description
Core DSL Features .topic_00_dsl_features Declarative class registration, export properties, typed signals, and in-editor tool execution.
Node Declaration Syntax .topic_01_node_declaration Declaring custom nodes inheriting from 2D, 3D, UI, or Server nodes.
Engine Lifecycle Virtual Methods .topic_02_lifecycle_methods Virtual methods invoked by the Godot scene tree during execution.
In-Editor Tool Scripts (@[Tool]) .topic_03_tool_scripts Executing Crystal code live inside the Godot Editor viewport and scene dock.
Ergonomic Node Declarations & Groups .topic_04_node_helpers Convenient macros for groups, cached node references, and unique scene access.

Related Guides & Source References

Defined in:

libgodot/docs/c_gameplay_and_declarative_dsl/a_node_dsl.cr

Class Method Summary

Class Method Detail

def self.topic_00_dsl_features : Nil #

Core DSL Features: Declarative class registration, export properties, typed signals, and in-editor tool execution.

Key Topics & Information

  • Declarative syntax: node ClassName < ParentNode do ... end
  • Automatic ClassDB engine registration
  • Virtual method overrides: _ready, _process, _physics_process, _enter_tree, _exit_tree
  • In-editor live execution via @[Tool] annotation

def self.topic_01_node_declaration : Nil #

Node Declaration Syntax: Declaring custom nodes inheriting from 2D, 3D, UI, or Server nodes.

Declare a custom Godot node using the node macro:

require "libgodot"

node Enemy < CharacterBody2D do
  @[Export]
  property max_health : Int32 = 100

  def _ready : Void
    Godot.print("Enemy #{name} ready!")
  end
end

Supported Parent Classes:

You can inherit from any registered Godot engine node:


def self.topic_02_lifecycle_methods : Nil #

Engine Lifecycle Virtual Methods: Virtual methods invoked by the Godot scene tree during execution.

Godot dispatches lifecycle callbacks to custom nodes:

Virtual Method Invocation Timing Typical Use Case
_enter_tree : Void When node enters active scene tree Subscribing to signals, global lookups
_ready : Void When node and all children enter tree Initialization, setting initial positions
_process(delta : Float64) : Void Every visual render frame Smooth visuals, UI updates, animations
_physics_process(delta : Float64) : Void Fixed-rate physics step (60 Hz) Movement, raycasts, collision calculations
_exit_tree : Void When node leaves active scene tree Cleanup, unregistering listeners

def self.topic_03_tool_scripts : Nil #

In-Editor Tool Scripts (@[Tool]): Executing Crystal code live inside the Godot Editor viewport and scene dock.

Annotate a class with @[Tool] to have it execute inside the Godot Editor:

@[Tool]
node LevelGenerator < Node2D do
  @[ExportToolButton("Generate Maze")]
  property generate_button : ToolButton do
    generate_level!
  end

  def generate_level! : Void
    Godot.print("Procedural generation running in Godot Editor!")
  end
end

When selected in the editor, clicking the inspector tool button executes the Crystal code live in the viewport!


def self.topic_04_node_helpers : Nil #

Ergonomic Node Declarations & Groups: Convenient macros for groups, cached node references, and unique scene access.

Lapis provides built-in macros for declarative scene setup directly inside the node block:

node Player < CharacterBody2D do
  # Declarative group membership
  group "players", "damageable"

  # Cached node references (typed and nilable variants)
  onready sprite : Sprite2D
  onready? particle_fx : CPUParticles2D

  # Scene Unique Node access (%UniqueNodeName)
  unique_node health_bar : ProgressBar
  unique_node? quest_tracker : Control
end