The Three Golden Fiber Invariants: Essential rules for writing asynchronous fiber code in LibGodot.

Key Topics & Information

• Rule 1: Godot owns the OS main loop; fibers must cooperatively yield via Fiber.yield
• Rule 2: NEVER call top-level sleep in a fiber; Godot does not pump LibEvent
• Rule 3: Use await(timer) or frame delta accumulators for time delays

Yielding Execution in _process: Pumping spawned fibers cooperatively from the engine main thread.

Because Godot controls the OS event loop, spawned fibers (spawn do ... end) will starve unless the main thread cooperatively yields:

node GameManager < Node do
  def _ready : Void
    # Spawn a background gameplay fiber
    spawn do
      Godot.print("Dialog sequence started!")
      await(get_tree.create_timer(2.0))
      Godot.print("2 seconds elapsed non-blockingly!")
    end
  end

  def _process(delta : Float64) : Void
    # Cooperatively yield time slice to pending fibers:
    Fiber.yield
  end
end

The Sleep Deadlock Hazard: Why sleep hangs in fibers and how to await timers safely.

The Hazard:

In standard Crystal console programs, sleep 2.seconds registers a timer with Crystal's LibEvent / IOCP event loop. In LibGodot, Godot drives the main loop — not LibEvent! Calling top-level sleep suspends the fiber permanently, hanging that fiber indefinitely.

The Safe Pattern:

Always use Godot's timer mechanism with await:

# SAFE: Suspends fiber until Godot's timer fires
await(get_tree.create_timer(1.5))