Debug2D

Inherits: Node < Object

Debug drawing in 2D.

Description

A singleton which allows to draw various primitives in order to aid visual debugging in 2D. Unlike other nodes, this allows to draw outside of CanvasItem._draw or CanvasItem.NOTIFICATION_DRAW, so Debug2D can be used from everywhere in code, for example:

func _ready():
    Debug2D.draw_line(Vector2(0, 0), Vector2(100, 100))

When drawing each frame, you should call clear prior to drawing, otherwise draw commands will accumulate infinitely, decreasing performance:

func _process(delta):
    Debug2D.clear()
    Debug2D.draw_line(Vector2(0, 0), Vector2(100, 100))

It’s also possible to keep a history of draw commands by calling capture:

func _ready():
    var points = [Vector2(0, 0), Vector2(100, 0), Vector2(100, 100), Vector2(0, 100)]
    for point in points:
        Debug2D.draw_circle(8, point)
        Debug2D.capture()

You can then access the captured snapshots using get_capture, which will return a special DebugCapture object, refer to DebugCapture documentation for more information on how to playback snapshots.

Default draw parameters such as color or line width can be configured via ProjectSettings (see debug/draw section), or using one of the draw_set_* methods. Arguments passed directly to methods will override parameters set by draw_set_* methods, and draw_set_* methods will override parameters defined in ProjectSettings.

List of common parameters:

color: Specifies draw color.

filled: If true, then all geometrical primitives such as polygon, circle, rectangle etc. will be drawn with a solid color, otherwise only the outline is drawn.

line_width: Specifies line with for methods such as draw_line, or line width of unfilled primitives.

Note: the drawing works in debug builds only.

Methods

void capture ( )
void clear ( )
void draw ( String method, Array args=null )
void draw_arrow ( Vector2 from, Vector2 to, Color color=Color( 0, 0.6, 0.7, 1 ), float width=1.0, Vector2 tip_size=Vector2( 8, 8 ), float tip_offset=0.0 )
void draw_circle ( float radius, Vector2 position=Vector2( 0, 0 ), Color color=Color( 0, 0.6, 0.7, 1 ), bool filled=true, float width=1.0 )
void draw_line ( Vector2 from, Vector2 to, Color color=Color( 0, 0.6, 0.7, 1 ), float width=1.0 )
void draw_polygon ( PoolVector2Array polygon, Color color=Color( 0, 0.6, 0.7, 1 ), bool filled=true, float width=1.0 )
void draw_polyline ( PoolVector2Array polyline, Color color=Color( 0, 0.6, 0.7, 1 ), float width=1.0 )
void draw_rectangle ( Vector2 extents, Vector2 position=Vector2( 0, 0 ), Color color=Color( 0, 0.6, 0.7, 1 ), bool filled=true, float width=1.0 )
void draw_region ( Rect2 region, Color color=Color( 0, 0.6, 0.7, 1 ), bool filled=true, float width=1.0 )
void draw_reset ( String option=”” )
void draw_set_color ( Color color )
void draw_set_filled ( bool filled )
void draw_set_line_width ( float width )
void draw_set_transform ( Vector2 position, float rotation=0, Vector2 scale=Vector2( 1, 1 ) )
void draw_set_transform_matrix ( Transform2D matrix )
void draw_text ( String text, Vector2 position=Vector2( 0, 0 ), Color color=Color( 1, 1, 1, 1 ) )
Object get_base ( ) const
DebugCapture get_capture ( ) const
GridRect get_grid ( ) const
void update ( )

Property Descriptions

Setter set_canvas_item(value)
Getter get_canvas_item()

The current active canvas item used for drawing. To restore the default, assign the base canvas:

Debug2D.canvas_item = Debug2D.get_base()
Setter set_enabled(value)
Getter is_enabled()

If false, then all debug drawing is disabled.

Method Descriptions

  • void capture ( )

Captures a new snapshot of all draw commands that were called to this moment. Can be called multiple times.

  • void clear ( )

Clears the canvas, all the draw calls from the queue of draw commands are removed.

Calls a custom draw method. It’s possible to call both built-in CanvasItem methods (starting with draw_*), or methods defined via script.

Draws an arrow. The tip_size configures the size of the arrow’s tip, where X coordinate corresponds to the width, and Y corresponds to the height. The tip_offset allows to shift the tip towards the beginning along arrow’s length, and is specified as a fraction of the arrow’s length in the range of [0..1].

The following snippet shows how to draw a cyclic directed graph with vertices drawn as circles, where the arrow tip is perfectly aligned to circle’s boundary:

for i in points.size():
    var from = points[i]
    var to = points[(i + 1) % points.size()]

    var radius = 8.0
    var length = (to - from).length()
    var offset = radius / length

    Debug2D.draw_arrow(from, to, Color.white, 1, Vector2(8, 8), offset)
    Debug2D.draw_circle(radius, from, Color.white)
  • void draw_circle ( float radius, Vector2 position=Vector2( 0, 0 ), Color color=Color( 0, 0.6, 0.7, 1 ), bool filled=true, float width=1.0 )

Draws a circle. Unlike in CanvasItem.draw_circle, the total number of vertices is configured according to predefined arc tolerance to improve accuracy when drawing circles with large radius.

Draws a line.

Draws a polygon.

Draws a polyline.

  • void draw_rectangle ( Vector2 extents, Vector2 position=Vector2( 0, 0 ), Color color=Color( 0, 0.6, 0.7, 1 ), bool filled=true, float width=1.0 )

Draws a rectangle. The total width and height is twice the half extents. See also draw_region.

  • void draw_region ( Rect2 region, Color color=Color( 0, 0.6, 0.7, 1 ), bool filled=true, float width=1.0 )

Draws a region Rect2. For example, you can draw a bounding rectangle of points:

Debug2D.draw_region(GoostGeometry2D.bounding_rect(points))

See also draw_rectangle.

  • void draw_reset ( String option=”” )

Resets all drawing options set with draw_set_color, draw_set_filled, and draw_set_line_width.

  • void draw_set_color ( Color color )

Overrides the color parameter for all future draw calls.

  • void draw_set_filled ( bool filled )

Overrides the filled parameter for all future draw calls.

  • void draw_set_line_width ( float width )

Overrides the width parameter for all future draw calls.

  • void draw_set_transform ( Vector2 position, float rotation=0, Vector2 scale=Vector2( 1, 1 ) )

Sets a custom transform for drawing via components. Anything drawn afterwards will be transformed by this. Equivalent to CanvasItem.draw_set_transform.

  • void draw_set_transform_matrix ( Transform2D matrix )

Sets a custom transform for drawing via matrix. Anything drawn afterwards will be transformed by this. Equivalent to CanvasItem.draw_set_transform_matrix.

  • void draw_text ( String text, Vector2 position=Vector2( 0, 0 ), Color color=Color( 1, 1, 1, 1 ) )

Draws text at specified position using the default Font. Unlike other draw methods, the default color will not be affected by draw_set_color.

Returns the default base CanvasItem used for drawing.

Returns DebugCapture object to manage history of draw commands.

Returns the default GridRect used to draw an infinite grid at run-time.

The grid drawing is disabled by default, so if you want to use it, you have to go into project settings and enable it manually. You can change the grid properties both by configuring project settings at debug/draw/2d/grid and via code:

func _ready():
    var grid: GridRect = Debug2D.get_grid()
    grid.show()

If you use Camera2D or change Viewport.canvas_transform, the grid’s position and scale are going to be updated automatically to simulate an infinite grid. Note that GridRect doesn’t currently support rotated grid lines.

  • void update ( )

Update all draw calls to request redraw. Similar to CanvasItem.update.