debug-visualization-workflow

name	debug-visualization-workflow
description	Operational workflow for building and validating debug overlays and gizmos that expose simulation state without mutating gameplay logic.
tier	operational
godot_version	4.6+
doc_anchors	["godot-docs/tutorials/scripting/debug/overview_of_debugging_tools.rst","godot-docs/tutorials/2d/custom_drawing_in_2d.rst","godot-docs/tutorials/plugins/editor/3d_gizmos.rst","godot-docs/classes/class_canvasitem.rst"]
tags	["debugging","visualization","gizmos"]
depends_on	["godot-skills/godot-secondary/domain-rendering-visuals/SKILL.md","godot-skills/godot-operational/qa-validation-loop/SKILL.md"]

Debug Visualization Workflow

Use When

• Debugging LOS, pathing, hit detection, or state-transition behavior.
• Teams need reproducible visual diagnostics for regression reports.
• Instrumentation is needed without contaminating production gameplay logic.

Outcomes

• Debug overlays/gizmos expose key state and decisions clearly.
• Visualization paths can be toggled and scoped safely.
• Diagnostic visuals remain non-authoritative and side-effect free.

Required Rules

• Keep debug drawing behind explicit runtime/editor toggles.
• Render diagnostics from read-only state snapshots.
• Avoid coupling debug visuals to gameplay mutation code paths.
• Include labels/legends for values needed in bug reproduction.

Workflow

1. Select target signals/states to visualize (for example path, ray hit, LOS block).
2. Implement overlay/gizmo rendering with clear toggle controls.
3. Feed visuals from deterministic state snapshots, not live mutation hooks.
4. Capture screenshot/video plus numeric trace for issue reports.
5. Validate that disabling diagnostics fully removes overhead and side effects.

Validation

• Visual overlays match logged values for the same frame/tick.
• Enabling diagnostics does not change authoritative outcomes.
• Disabling diagnostics removes drawing and leaves behavior unchanged.

Failure Modes

• Debug layers mutate gameplay state indirectly.
• Visual output lacks labels and cannot support reproducible triage.
• Diagnostic toggles leak into release behavior unintentionally.

Local Doc Anchors

• godot-docs/tutorials/scripting/debug/overview_of_debugging_tools.rst
• godot-docs/tutorials/2d/custom_drawing_in_2d.rst
• godot-docs/tutorials/plugins/editor/3d_gizmos.rst
• godot-docs/classes/class_canvasitem.rst