Diorite 💎

High-Performance 2D & 3D Debug Drawing Plugin & Frame DSL for Godot Engine 4.8+

CI Docs Crystal Godot License: MIT

Diorite is a debug drawing plugin and immediate-mode DSL for Godot 4.8+ powered by the Lapis Crystal toolchain. Inspired by tools like Godot's DebugDraw3D and Raylib's immediate drawing functions, Diorite provides both a node-based scene workflow and a zero-allocation frame-based DSL for real-time visualization.

📖 Full API & Architecture Documentation: https://sol-vin.github.io/diorite/

All debug primitives render with highest visual priority:

⚡ Performance Benchmarks

Diorite was engineered from the ground up for extreme throughput and zero-allocation runtime performance. Benchmarks measured on Crystal 1.21.0:

| Category | Benchmark Routine | Throughput | Latency | Allocation | |---|---|---|---|---| | Vector Transforms | MathHelpers.find_perpendicular | 15.02 M ops/sec | 66.56 ns | 0.0 B/op | | Vector Transforms | MathHelpers.orthonormal_plane | 7.15 M ops/sec | 139.85 ns | 0.0 B/op | | Vector Transforms | MathHelpers.rotate_around_axis | 8.76 M ops/sec | 114.21 ns | 0.0 B/op | | 3D Primitives | 3D Line | 7.90 M ops/sec | 126.63 ns | 0.0 B/op | | 3D Primitives | 3D Arrow | 669.85 k ops/sec | 1.49 µs | 96.0 B/op | | 3D Primitives | 3D Box (12 edges) | 769.05 k ops/sec | 1.30 µs | 0.0 B/op | | 3D Primitives | 3D Camera Frustum | 628.66 k ops/sec | 1.59 µs | 0.0 B/op | | 3D Primitives | 3D Sphere (16 rings) | 146.31 k ops/sec | 6.83 µs | 0.0 B/op | | 3D Primitives | 3D Grid (10x10 subs) | 288.30 k ops/sec | 3.47 µs | 0.0 B/op | | 3D Primitives | 3D Trajectory Arc (20 steps) | 138.04 k ops/sec | 7.24 µs | 0.0 B/op | | 3D Sweeps | SphereCast (12 rings + rays) | 110.45 k ops/sec | 9.05 µs | 0.0 B/op | | 3D Sweeps | BoxCast (2 boxes + 8 edges) | 452.10 k ops/sec | 2.21 µs | 0.0 B/op | | 3D Splines | Cubic Bézier (32 segs) | 195.40 k ops/sec | 5.12 µs | 0.0 B/op | | 3D Splines | Catmull-Rom Spline (20 pts) | 68.20 k ops/sec | 14.66 µs | 0.0 B/op | | 2D Primitives | 2D Line | 9.26 M ops/sec | 108.04 ns | 0.0 B/op | | 2D Primitives | 2D Arrow | 2.76 M ops/sec | 361.94 ns | 0.0 B/op | | 2D Primitives | 2D Rect | 2.81 M ops/sec | 356.13 ns | 0.0 B/op | | 2D Primitives | 2D Circle (24 segs) | 210.34 k ops/sec | 4.75 µs | 0.0 B/op | | Data Charts | 2D Pie Chart (3 slices) | 215.80 k ops/sec | 4.63 µs | 0.0 B/op | | Data Charts | 3D Donut Chart (3 slices) | 142.60 k ops/sec | 7.01 µs | 0.0 B/op | | Data Charts | 2D Bar Chart (3 bars) | 340.20 k ops/sec | 2.94 µs | 0.0 B/op | | Data Charts | 2D Radial Gauge | 188.40 k ops/sec | 5.31 µs | 0.0 B/op | | Queue Operations | Batch Enqueue 10,000 Commands | 2.01 M cmds/sec | 4.95 ms / 10k | Fast Push | | Queue Operations | Step & Decay 10,000 Commands | 20.04 M cmds/sec | 0.49 ms / 10k | Fast Reject | | Queue Operations | Clear Queue | 250.0 M ops/sec | 4.0 µs / 10k | Instant | | Telemetry Ingestion | TelemetryGraph#add_sample | 24.20 M ops/sec | 41.33 ns | 0.0 B/op | | Telemetry Render | TelemetryGraph#build_geometry | 63.84 k fps | 15.66 µs | 0.0 B/op | | Heavy Simulation | 700 Mixed Shapes per Frame | 4,590 frames/sec | 0.21 ms / frame | 108 kB / frame |

In a 60 FPS frame budget (16.6 milliseconds), drawing 700 mixed 2D and 3D shapes takes only 0.21 ms (~1.3% of the frame budget).

✨ Features & Visualization Suite

Diorite ships with 35+ debug visualization items and developer UX helpers:

1. Standard 3D Items

2. Game-Dev Spatial Helpers & Swept Shape Casts

3. Data Visualization & Charting

4. 2D Canvas Helpers

🎮 Developer UX & Workflow Features

Category / Channel Filtering

Organize debug output into logical layers and selectively toggle them:

# Draw within an AI channel
DebugDraw.channel("ai") do |d|
  d.vision_cone_3d(enemy.position, enemy.forward, angle_deg: 45.0, range: 10.0)
  d.actor_card_3d(enemy.position, "Enemy Scout", {"HP" => "100%", "State" => "Alert"})
end

# Toggle channels via console command or hotkey
DebugDraw.disable_channel("ai") # Suppresses all AI drawing
DebugDraw.enable_channel("ai")  # Restores AI drawing

Local-Space Transform Stacks

Draw directly relative to moving nodes or local coordinate systems without manual math:

DebugDraw.with_transform(vehicle.global_transform) do
  # These points and boxes automatically rotate and translate with the vehicle
  DebugDraw.box_3d(Godot::Vector3.new(0, 0, 0), Godot::Vector3.new(2, 1, 4))
  DebugDraw.arrow_3d(Godot::Vector3.new(0, 1, 0), Godot::Vector3.new(0, 1, 3))
end

Frame Freeze Mode

Pause lifetime decay with DebugDraw.freeze! to orbit the camera freely and inspect collision glitches:

# Freeze active debug shapes so they don't disappear while inspecting
DebugDraw.freeze!

# Orbit camera freely...

# Resume normal decay
DebugDraw.unfreeze!

🚀 Usage Example

require "lapis"
require "diorite"

# 1. Immediate-mode drawing in _process
def _process(delta : Float64) : Void
  # Swept sphere cast
  DebugDraw.sphere_cast_3d(start_pos, target_pos, radius: 0.5_f32, hit: is_hit)

  # Data visualization: 2D Bar Chart
  bars = [
    Diorite::BarData.new("RigidBodies", 42.0_f32, Color.new(0.2, 0.8, 0.3)),
    Diorite::BarData.new("Particles", 120.0_f32, Color.new(0.8, 0.3, 0.2))
  ]
  DebugDraw.bar_chart_2d(Rect2.new(20, 200, 160, 80), bars: bars, title: "Engine Stats")

  # Multi-series telemetry graph
  DebugDraw.telemetry_series_2d("Engine", "Frame", frame_ms, Color.new(0.2, 0.9, 0.3))
  DebugDraw.telemetry_series_2d("Engine", "Physics", physics_ms, Color.new(0.2, 0.5, 1.0))
  DebugDraw.telemetry_threshold_2d("Engine", 16.66_f32, Color.new(1.0, 0.2, 0.2, 0.8), "60 FPS")
end

🛠️ Project Structure

diorite/
├── .github/workflows/
│   ├── ci.yml               # Multi-platform CI (Specs, Benchmarks, Godot Headless Smoke Test)
│   └── docs.yml             # Automatic Lapis documentation generation & GitHub Pages deployment
├── addons/
│   ├── crystal_integration/ # Lapis Crystal GDExtension integration
│   └── diorite/             # Diorite Godot addon manifest & plugin
│       ├── plugin.cfg
│       ├── diorite.gd
│       └── diorite.gdextension
├── bench/
│   └── benchmark_suite.cr   # Comprehensive benchmark suite (IPS & Benchmark.bm)
├── docs_src/                # Source documentation in YAML for lapis docs compiler
├── docs/                    # Compiled static documentation site
├── scenes/
│   └── main.tscn            # Showcase test scene demonstrating Diorite items
├── spec/                    # Pure Crystal unit test suite (53 specs across 7 suites)
│   ├── charts_spec.cr
│   ├── spatial_helpers_spec.cr
│   ├── channels_and_transforms_spec.cr
│   ├── geometry_builder_spec.cr
│   ├── math_helpers_spec.cr
│   ├── dsl_spec.cr
│   ├── dsl_queue_spec.cr
│   ├── telemetry_graph_spec.cr
│   └── spec_helper.cr
├── src/
│   ├── demo/                # Showcase demo controller
│   │   └── demo_controller.cr
│   ├── diorite/
│   │   ├── core/            # Geometry builder, chart builder, math, command queues, DSL
│   │   ├── nodes/           # Node-based 3D and 2D debug shapes & manager
│   │   └── diorite.cr       # Addon entry point
│   └── main.cr              # Project root game entry point
├── project.godot            # Godot 4.8 engine project configuration
├── shard.yml                # Crystal dependency manifest
└── godot-version.yml        # Target Godot version specification (4.8-dev6)

🧪 Testing & Benchmarking

Running Unit Specs (53 specs)

Diorite contains comprehensive unit specs covering all 35+ geometric builders, charts, channels, transform stacks, vertex counts, color assignments, telemetry ring buffers, and command queue duration decay:

crystal spec

Running Benchmark Suite

crystal run --release bench/benchmark_suite.cr

📄 License

Licensed under the MIT License. See LICENSE for details.