Learning Milestones: What you will build and understand by the end of this guide.

Key Topics & Information

• Create a new Lapis game project with lapis new game
• Understand the project directory layout
• Write a 2D platformer character in pure Crystal with exported properties
• Run and inspect your game in the Godot Editor
• Package a playable standalone release executable with lapis package game

Step 1: Create Your Project: Scaffolding a fresh game project with a single command.

Open your terminal and run:

lapis new game my_first_game
cd my_first_game

What Just Happened?

Lapis scaffolded a complete, runnable Godot project pre-configured for Crystal:

• project.godot: Root Godot engine configuration with the Crystal integration plugin enabled.
• src/main.cr: The entry point for your game code.
• scenes/main.tscn: Default starting scene.
• shard.yml: Crystal package dependencies.
• Makefile: Convenient shortcuts for building, running, and testing.

Step 2: Write Your First Character Node: Creating a Player node with speed, gravity, jump velocity, and keyboard controls.

Open src/main.cr in your favorite editor (VS Code, Cursor, or Zed). Replace its content with the following declarative node definition:

require "libgodot"

# Player character with 2D physics movement, jumping, and exported speed
node Player < CharacterBody2D do
  # Movement speed in pixels per second (editable in Godot Inspector!)
  @[Export(range: 50.0_f32..1000.0_f32, step: 10.0_f32)]
  property speed : Float32 = 300.0_f32

  # Jump velocity in pixels per second (negative is upward in 2D)
  @[Export(range: -1000.0_f32..-100.0_f32)]
  property jump_velocity : Float32 = -400.0_f32

  # Gravity acceleration
  property gravity : Float32 = 980.0_f32

  # Emitted whenever player performs a jump
  signal jumped(power : Float32)

  def _ready : Void
    Godot.print("Player initialized: #{name}")
  end

  def _physics_process(delta : Float64) : Void
    cur_vel = velocity

    # 1. Apply gravity when airborne
    unless on_floor?
      cur_vel.y += gravity * delta.to_f32
    end

    # 2. Handle Jump input
    if Input.action_just_pressed?("ui_accept") && on_floor?
      cur_vel.y = jump_velocity
      emit(jumped, jump_velocity.abs)
    end

    # 3. Handle Horizontal Movement (Left / Right arrow keys)
    direction = Input.axis("ui_left", "ui_right")
    if direction != 0.0_f32
      cur_vel.x = direction * speed
    else
      cur_vel.x = 0.0_f32
    end

    self.velocity = cur_vel
    move_and_slide
  end
end

Step 3: Compile & Open in Godot Editor: Building your game library and testing it live in the Godot Editor.

In your project directory, compile your game:

lapis build game

Now launch the Godot Editor:

lapis editor

Inside the Editor:

1. Notice that Player appears in Godot's Create New Node dialog (Ctrl+A), complete with custom documentation and icons!
2. Select your Player node in the Scene tree: check the Inspector panel on the right.
3. Notice the speed slider (50 to 1000) and jump_velocity slider! You can adjust these values in real-time without recompiling.
4. Press F5 to play your scene. Press the arrow keys to walk and the Spacebar to jump!

Step 4: Hot Reloading Code: Iterating on code without ever restarting the Godot Editor.

Leave the Godot Editor open!

1. In src/main.cr, change speed : Float32 = 300.0_f32 to 600.0_f32.
2. Switch to your terminal and run lapis build game (or simply press F5 in Godot).
3. The editor detects the change, reloads the Crystal library instantly, and updates your player speed!

Step 5: Package Your Playable Game: Exporting a standalone, self-contained executable for players.

When you are ready to distribute your game:

lapis package game --release

Lapis will:

1. Compile your Crystal code with --release -O3 optimizations.
2. Strip all developer and editor symbols.
3. Package your scenes and assets into a standalone executable.
4. Place the playable game bundle into dist/.