paweljarosz / debug-draw

A set of convenience functions for drawing debug lines, shapes, and text with Defold.

Debug-Draw

A set of convenience functions to draw lines, shapes, and text with the "draw_line" and "draw_debug_text" render messages. This is not intended to be used for final game graphics. Most of the functions only draw on a 2D plane at z=0, though the ray function can draw 3D lines.

Dependency Link:

https://github.com/rgrams/debug-draw/archive/master.zip

Don't know what to do with this link? Read the manual: https://www.defold.com/manuals/libraries/

To use the module in your scripts, you must require it, like so:

local debugdraw = require "debug-draw.debug-draw"

Settings:

debugdraw.COLORS

table

A table of colors that you can use for drawing lines and shapes. You can modify this at runtime if you want.

The list of built-in colors:

• white
• black
• red
• cyan
• yellow
• orange
• green
• blue
• pink
• magenta

debugdraw.default_color

vector4 | string

The default color that will be used if you don't specify one. The default value is yellow. You can set it to a new vector4 or a string name from the COLORS list.

debugdraw.default_circle_segments

number

The default number of segments for drawing circles used if you don't specify it. The default value is 16.

Functions:

NOTE: Unless you mess with your render script, all coordinates are in world space.

debugdraw.ray(v1, v2, [color])

Draw a line from v1 to v2. The line can be 3D.

PARAMETERS

• v1 number - Line start point.
• v2 number - Line end point.
• color nil | string | vector4 - Line color. Can be a vector4 or a string name from the COLORS list.
  • Optional - debugdraw.default_color (yellow) by default.

debugdraw.line(x1, y1, x2, y2, [color])

Draw a 2D line from (x1, y1) to (x2, y2).

PARAMETERS

• x1, y1 number - Line start point X and Y.
• x2, y2 number - Line end point X and Y.
• color nil | string | vector4 - Line color. Can be a vector4 or a string name from the COLORS list.
  • Optional - debugdraw.default_color (yellow) by default.

debugdraw.rect(lt, rt, top, bot, [color])

Draw a rectangle from it's left, right, top, and bottom coordinates.

PARAMETERS

• lt, rt, top, bot number - Left, right, top, and bottom coordinates of the rectangle.
• color nil | string | vector4 - Line color. Can be a vector4 or a string name from the COLORS list.
  • Optional - debugdraw.default_color (yellow) by default.

debugdraw.box(cx, cy, w, h, [color], [rot])

Draw a rectangle from a center point, width, and height, with optional rotation.

PARAMETERS

• cx, cy number - X and Y of the center of the box.
• w, h number - Width and height of the box.
• color nil | string | vector4 - Line color. Can be a vector4 or a string name from the COLORS list.
  • Optional - debugdraw.default_color (yellow) by default.
• rot nil | number - Rotation angle (in radians) of the box.
  • Optional - 0 by default.

debugdraw.cross(cx, cy, radiusX, radiusY, [color], [rot])

Draw a cross or X from a center point and two radii, with optional rotation.

PARAMETERS

• cx, cy number - X and Y of the center of the cross.
• radiusX number - The radius (half of the length) of the horizontal (before rotation) line of the cross.
• radiusY number - The radius (half of the length) of the vertical (before rotation) line of the cross.
• color nil | string | vector4 - Line color. Can be a vector4 or a string name from the COLORS list.
  • Optional - debugdraw.default_color (yellow) by default.
• rot nil | number - Rotation angle (in radians) of the cross.
  • Optional - 0 by default.

debugdraw.circle(cx, cy, radius, [color], [segments], [baseAngle])

Draw a circle from a center point and a radius, with optional segment count and base angle. If you reduce the number of segments, you can use this to draw equilateral triangles, squares, pentagons, hexagons, heptagons, etc., or even single lines. If you do, you may want to supply a baseAngle to orient your shape the way you want.

PARAMETERS

• cx, cy number - X and Y of the center of the circle.
• radius number - The radius of the circle.
• color nil | string | vector4 - Line color. Can be a vector4 or a string name from the COLORS list.
  • Optional - debugdraw.default_color (yellow) by default.
• segments nil | number - The number of line segments to draw the circle/shape with. If you use a non-integer number you'll get a space at the end of your circle instead of a closing line. Setting this to 2 will draw one line across the center of the would-be circle, rotated at baseAngle. Setting it to less than 2 will draw a line across only part of the circle, and setting it to 1 or less will draw nothing.
  • Optional - debugdraw.default_circle_segments (16) by default.
• baseAngle nil | number - The angle in radians of the first vertex of the circle. Measured counter-clockwise from the positive X-axis. This only really matters if you're using a very low number of segments.
  • Optional - 0 by default.

debugdraw.text(text, x, y, [color])

Draws some text. Unlike the other functions, this one's X and Y are in screen space (starting from (0,0) at the bottom left of the screen).

PARAMETERS

• text string - The text to draw.
• x, y number - X and Y of the top left corner of the text's bounding box, in screen space.
• color nil | string | vector4 - Line color. Can be a vector4 or a string name from the COLORS list.
  • Optional - debugdraw.default_color (yellow) by default.