module Lapis::Docs::GENERAL::OVERVIEW

Overview

Diorite Overview & Getting Started

Diorite is a high-performance 2D and 3D debug drawing plugin and frame DSL for Godot Engine 4.8+ powered by the Lapis Crystal toolchain.

Overview

Diorite provides two primary workflows for debug drawing in Godot:

1. Node-based System: Scene tree nodes (DebugBox3D, DebugSphere3D, DebugShape2D, etc.) designed for in-editor placement, gizmo manipulation, and persistent hierarchy visualization.
2. Immediate-Mode Frame DSL: A procedural API (DebugDraw.*) that can be invoked anywhere in game logic (_process, _physics_process, collision signals, or AI behaviors) with single-frame or timed duration.

Key Topics

Code Examples

Basic 3D Line and Sphere

DebugDraw.line_3d(Godot::Vector3.new(0, 0, 0), Godot::Vector3.new(0, 5, 0), Godot::Color.new(0, 1, 0))
DebugDraw.sphere_3d(center: player.position, radius: 1.5_f32, color: Godot::Color.new(1, 0, 0), duration: 2.5_f32)

Block Frame DSL

DebugDraw.frame do |d|
  d.line_3d(actor.position, actor.position + actor.velocity)
  d.circle_2d(Godot::Vector2.new(100, 100), 30.0_f32)
end

Pitfalls & Best Practices

• Do not use raw .new on native Godot engine objects without pointers; use Godot.create(T) or Diorite helper nodes.
• For commands called frequently inside tight loops, prefer batched DSL paths (line_path_3d, points_3d) to minimize per-command dispatch overhead.

Frequently Asked Questions

• Q: How do I make debug shapes persist for more than one frame?
  A: Pass duration in seconds (e.g. duration: 3.0) to any DebugDraw method.
• Q: Can I configure shapes in the Godot Inspector?
  A: Yes, add any of the Diorite node types (e.g. DebugBox3D, DebugShape2D) to your scene tree.

Defined in:

Class Method Summary

• .example_01_basic_3d_line_and_sphere : Nil

  Example: Basic 3D Line and Sphere

• .example_02_block_frame_dsl : Nil

  Example: Block Frame DSL

• .topic_01_visual_priority : Nil

  Visual Priority: All debug items render on top of other game effects (3D render priority 127 with depth test disabled; 2D canvas layer 128 at z-index 4096).

• .topic_02_dual_workflow : Nil

  Dual Workflow: Choose between scene tree nodes or immediate-mode procedural calls in _process or physics steps.

Class Method Detail

DebugDraw.line_3d(Godot::Vector3.new(0, 0, 0), Godot::Vector3.new(0, 5, 0), Godot::Color.new(0, 1, 0))
DebugDraw.sphere_3d(center: player.position, radius: 1.5_f32, color: Godot::Color.new(1, 0, 0), duration: 2.5_f32)

DebugDraw.frame do |d|
  d.line_3d(actor.position, actor.position + actor.velocity)
  d.circle_2d(Godot::Vector2.new(100, 100), 30.0_f32)
end