module Lapis::Docs::GENERAL::GAME_HELPERS

Overview

Game Spatial Helpers and UX Controls

Comprehensive guide to swept shape casts, splines, actor cards, channels, transform stacks, and freeze mode.

Overview

Diorite includes rich gameplay debugging utilities and developer UX features. Debug collision queries with swept shape casts, inspect pathfinding curves with cubic Bézier and Catmull-Rom splines, display overhead entity stat cards, isolate system debug output with channels, and freeze frame decay for freecam inspection.

Key Topics

Code Examples

Swept Shape Casts

# Visualize a sphere cast with hit notification
DebugDraw.sphere_cast_3d(cast_start, cast_end, radius: 0.5_f32, hit: is_colliding)

# Visualize player character capsule sweep
DebugDraw.capsule_cast_3d(from_pos, to_pos, radius: 0.4_f32, height: 1.8_f32)

# Visualize moving platform box sweep
DebugDraw.box_cast_3d(box_start, box_end, size: Godot::Vector3.new(2, 0.5, 2))

Spline Path Visualization

# 3D Cubic Bézier with control hull
DebugDraw.bezier_cubic_3d(p0, p1, p2, p3, segments: 32, show_hull: true)

# Multi-waypoint Catmull-Rom patrol curve
DebugDraw.catmull_rom_3d(patrol_points, segments_per_curve: 16, loop: true)

Channels and Transform Stacks

# Scoped drawing with local transform
DebugDraw.with_transform(vehicle.global_transform) do
  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

# Filtered channel drawing
DebugDraw.channel("ai") do |d|
  d.vision_cone_3d(enemy.position, enemy.forward, angle_deg: 45.0_f32, range: 10.0_f32)
  d.actor_card_3d(enemy.position, "Guard AI", {"State" => "Patrol", "HP" => "100%"})
end

Pitfalls & Best Practices

• Transform stacks automatically pop when exiting with_transform blocks, ensuring consistent global coordinate states.
• When the queue is frozen via freeze!, commands persist without decaying their remaining duration.

Frequently Asked Questions

• Q: How do I toggle channels during gameplay?
  A: Call DebugDraw.enable_channel("ai") or DebugDraw.disable_channel("ai") from an input action or debug console command.
• Q: How do I freeze debug draws with a hotkey?
  A: Call DebugDraw.toggle_freeze! in your input event handler when the desired pause/inspect key is pressed.

Defined in:

Class Method Summary

• .example_01_swept_shape_casts : Nil

  Example: Swept Shape Casts

• .example_02_spline_paths : Nil

  Example: Spline Path Visualization

• .example_03_channels_and_transforms : Nil

  Example: Channels and Transform Stacks

• .topic_01_swept_shape_casts : Nil

  Swept Shape Casts: Visualize continuous physics sweep queries showing start position, destination shape, edge connector rays, and impact indicators.

• .topic_02_splines : Nil

  Splines (Cubic Bézier & Catmull-Rom): Render smooth 3D trajectories, patrol routes, and motion camera curves with optional control polygon hulls.

• .topic_03_actor_cards : Nil

  Actor Cards & 3D Spatial Helpers: Floating billboard cards with ground anchor poles displaying entity names and dynamic key-value stat blocks.

• .topic_04_channel_filtering : Nil

  Category / Channel Filtering: Assign draw calls to channels (e.g.

• .topic_05_transform_stacks : Nil

  Local-Space Transform Stacks: Render primitives relative to parent transforms with DebugDraw.with_transform(xform) do ...

• .topic_06_frame_freeze : Nil

  Frame Freeze Mode: Pause lifetime decay with DebugDraw.freeze! to freely maneuver the scene camera around momentary collision or visual glitches.

Class Method Detail

DebugDraw.sphere_cast_3d(cast_start, cast_end, radius: 0.5_f32, hit: is_colliding)
DebugDraw.capsule_cast_3d(from_pos, to_pos, radius: 0.4_f32, height: 1.8_f32)
DebugDraw.box_cast_3d(box_start, box_end, size: Godot::Vector3.new(2, 0.5, 2))

DebugDraw.bezier_cubic_3d(p0, p1, p2, p3, segments: 32, show_hull: true)
DebugDraw.catmull_rom_3d(patrol_points, segments_per_curve: 16, loop: true)

DebugDraw.with_transform(vehicle.global_transform) do
  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

DebugDraw.channel("ai") do |d|
  d.vision_cone_3d(enemy.position, enemy.forward, angle_deg: 45.0_f32, range: 10.0_f32)
  d.actor_card_3d(enemy.position, "Guard AI", {"State" => "Patrol", "HP" => "100%"})
end