debug
debug Module
The debug module provides a comprehensive suite of 3D debug visualizations and 2D screen text overlays. Lines, rays, arrows, boxes, spheres, capsules, cylinders, grids, planes, and text can be drawn with custom colors and optional durations in seconds.
Overview
Methods (46)
Detailed Reference
debug.beginTextGroup(groupTitle, [groupPriority = 0], [groupColor], [showTitle = true], [titleSize = -1], [textSize = -1])| Parameter | Type | Default | Description |
|---|---|---|---|
groupTitle | string | Title of group. | |
groupPriority | number | `0` | Priority. |
groupColor | color|string|number | optional | Header color. |
showTitle | boolean | `true` | Show header. |
titleSize | number | `-1` | Header font size. |
textSize | number | `-1` | Item font size. |
Groups subsequent setText calls under a collapsible group title.
debug.clear2D()Clears 2D texts.
debug.clear3D()Clears 3D drawings.
debug.clearAll()Clears all active debug lines, shapes, and texts.
debug.clearTexts()Clears active 2D debug texts.
debug.drawAabb(aabb, [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
aabb | aabb | Axis-aligned bounding box. | |
color | color|string|number | optional | Color. |
duration | number | `0` | Duration. |
Renders an AABB object in world space.
debug.drawAabbAb(a, b, [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
a | vector3 | Min corner. | |
b | vector3 | Max corner. | |
color | color|string|number | optional | Color. |
duration | number | `0` | Duration. |
Renders an AABB directly between points a and b.
debug.drawArrow(a, b, [color], [arrowSize = 0.5], [isAbsoluteSize = false], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
a | vector3 | Start position. | |
b | vector3 | End position (arrowhead). | |
color | color|string|number | optional | Color. |
arrowSize | number | `0.5` | Head size. |
isAbsoluteSize | boolean | `false` | Constant size. |
duration | number | `0` | Duration in seconds. |
Draws a directed arrow between two 3D positions.
debug.drawArrowhead(position, [rotation], [scale], [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
position | vector3 | Position. | |
rotation | quaternion|vector3 | optional | Orientation. |
scale | vector3 | {0, 0, 0} | Scale. |
color | color|string|number | optional | Color. |
duration | number | `0` | Duration. |
Draws an isolated arrowhead marker.
debug.drawArrowPath(path, [color], [arrowSize = 0.75], [isAbsoluteSize = true], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
path | table | Array of 3D points. | |
color | color|string|number | optional | Color. |
arrowSize | number | `0.75` | Arrow size. |
isAbsoluteSize | boolean | `true` | Absolute size. |
duration | number | `0` | Duration. |
Renders directed arrows connecting points in path.
debug.drawArrowRay(origin, direction, length, [color], [arrowSize = 0.5], [isAbsoluteSize = false], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
origin | vector3 | Origin. | |
direction | vector3 | Direction vector. | |
length | number | Length. | |
color | color|string|number | optional | Color. |
arrowSize | number | `0.5` | Head size. |
isAbsoluteSize | boolean | `false` | Constant size. |
duration | number | `0` | Duration in seconds. |
Draws an arrow ray in direction for length.
debug.drawBox(position, [rotation], [size], [color], [isCentered = false], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
position | vector3 | Position. | |
rotation | quaternion|vector3 | optional | Rotation. |
size | vector3 | `(1, 1, 1)` | Dimensions. |
color | color|string|number | optional | Color. |
isCentered | boolean | `false` | Whether position is center or origin corner. |
duration | number | `0` | Duration. |
Renders a box with position, rotation, and dimensions.
debug.drawBoxAb(a, b, [up], [color], [isAbDiagonal = true], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
a | vector3 | Point A. | |
b | vector3 | Point B. | |
up | vector3 | `(0, 1, 0)` | Up vector. |
color | color|string|number | optional | Color. |
isAbDiagonal | boolean | `true` | Diagonal bounds. |
duration | number | `0` | Duration. |
Draws a bounding box between corners a and b.
debug.drawCapsule(position, [rotation], [radius = 0.5], [height = 2.0], [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
position | vector3 | Center. | |
rotation | quaternion|vector3 | optional | Rotation. |
radius | number | `0.5` | Capsule radius. |
height | number | `2.0` | Capsule total height. |
color | color|string|number | optional | Color. |
duration | number | `0` | Duration. |
Draws a capsule representing character colliders or physics shapes.
debug.drawCapsuleAb(a, b, [radius = 0.5], [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
a | vector3 | Start point. | |
b | vector3 | End point. | |
radius | number | `0.5` | Capsule radius. |
color | color|string|number | optional | Color. |
duration | number | `0` | Duration. |
Draws a capsule spanning between endpoints a and b.
debug.drawCircle(position, [radius = 1.0], [color], [normal], [segments = 32], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
position | vector3 | Center. | |
radius | number | `1.0` | Radius. |
color | color|string|number | optional | Color. |
normal | vector3 | `(0, 1, 0)` | Normal orientation. |
segments | number | `32` | Number of segments. |
duration | number | `0` | Duration. |
Draws a circular disc wireframe oriented along normal.
debug.drawCross(position, [size = 0.5], [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
position | vector3 | Center. | |
size | number | `0.5` | Extent. |
color | color|string|number | optional | Color. |
duration | number | `0` | Duration. |
Draws an intersecting 3-axis cross.
debug.drawCylinder(position, [rotation], [scale], [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
position | vector3 | Center. | |
rotation | quaternion|vector3 | optional | Rotation. |
scale | vector3 | {0, 0, 0} | Scale. |
color | color|string|number | optional | Color. |
duration | number | `0` | Duration. |
Renders a cylinder volume.
debug.drawCylinderAb(a, b, [radius = 0.5], [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
a | vector3 | Base center. | |
b | vector3 | Top center. | |
radius | number | `0.5` | Radius. |
color | color|string|number | optional | Color. |
duration | number | `0` | Duration. |
Renders a cylinder between points a and b.
debug.drawEntity(entityVal, [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
entityVal | entity|number | Entity object or ID. | |
color | color|string|number | optional | Color. |
duration | number | `0` | Duration. |
Renders the entity world AABB and transform axes.
debug.drawGizmo(position, [rotation], [scale], [color], [isCentered = false], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
position | vector3 | Position. | |
rotation | quaternion|vector3 | optional | Rotation. |
scale | vector3 | {0, 0, 0} | Scale. |
color | color|string|number | optional | Color. |
isCentered | boolean | `false` | Center. |
duration | number | `0` | Duration. |
Renders axes gizmo with orientation and scale.
debug.drawGrid(origin, [xSize], [ySize], [subdivX = 1], [subdivY = 1], [color], [isCentered = true], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
origin | vector3 | Grid center or origin. | |
xSize | vector3 | `(10, 0, 0)` | X axis vector. |
ySize | vector3 | `(0, 0, 10)` | Y axis vector. |
subdivX | number | `1` | Subdivisions on X. |
subdivY | number | `1` | Subdivisions on Y. |
color | color|string|number | optional | Grid color. |
isCentered | boolean | `true` | Centered. |
duration | number | `0` | Duration. |
Renders a grid with configurable subdivisions.
debug.drawLine(a, b, [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
a | vector3 | Start point. | |
b | vector3 | End point. | |
color | color|string|number | optional | Line color. |
duration | number | `0` | Time in seconds (0 = single frame). |
Renders a line between points a and b.
debug.drawLine(pos, pos + vector3.new(0, 5, 0), color.new(0, 1, 0), 2.0)debug.drawLineHit(start, end, hit, [isHit = true], [hitSize = 0.25], [hitColor], [afterHitColor], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
start | vector3 | Ray start. | |
end | vector3 | Ray target end. | |
hit | vector3 | Impact point. | |
isHit | boolean | `true` | Hit success flag. |
hitSize | number | `0.25` | Size of hit marker. |
hitColor | color|string|number | optional | Ray color before impact. |
afterHitColor | color|string|number | optional | Line color after impact. |
duration | number | `0` | Duration. |
Visualizes a raycast with hit point marker.
debug.drawLineHitOffset(start, end, [isHit = true], [unitOffset = 0.5], [hitSize = 0.25], [hitColor], [afterHitColor], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
start | vector3 | Ray start. | |
end | vector3 | Ray end. | |
isHit | boolean | `true` | Hit flag. |
unitOffset | number | `0.5` | Normalized hit offset (0.0 to 1.0). |
hitSize | number | `0.25` | Size. |
hitColor | color|string|number | optional | Color. |
afterHitColor | color|string|number | optional | After hit color. |
duration | number | `0` | Duration. |
Draws a raycast using normalized unit offset.
debug.drawLinePath(path, [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
path | table | Array of connected 3D points. | |
color | color|string|number | optional | Color. |
duration | number | `0` | Duration in seconds. |
Draws connected lines between consecutive points in path.
debug.drawLines(lines, [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
lines | table | Array of alternating start and end points. | |
color | color|string|number | optional | Line color. |
duration | number | `0` | Duration. |
Renders multiple line segments from point pairs.
debug.drawNode(nodeVal, [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
nodeVal | node | Node wrapper. | |
color | color|string|number | optional | Color. |
duration | number | `0` | Duration. |
Renders the node AABB and transform.
debug.drawPlane(planeNormalOrPosition, [dOrDistance = 0], [color], [anchorPoint], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
planeNormalOrPosition | vector3 | Plane normal. | |
dOrDistance | number | `0` | Distance from origin. |
color | color|string|number | optional | Color. |
anchorPoint | vector3 | {0, 0, 0} | Visual anchor. |
duration | number | `0` | Duration. |
Renders a plane defined by normal and distance.
debug.drawPoint(position, [size = 0.25], [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
position | vector3 | Point position. | |
size | number | `0.25` | Size. |
color | color|string|number | optional | Color. |
duration | number | `0` | Duration. |
Renders a marker at position.
debug.drawPointPath(path, [size = 0.25], [pointsColor], [linesColor], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
path | table | Array of positions. | |
size | number | `0.25` | Point size. |
pointsColor | color|string|number | optional | Marker color. |
linesColor | color|string|number | optional | Connecting line color. |
duration | number | `0` | Duration. |
Visualizes waypoints or navigation paths.
debug.drawPoints(points, [size = 0.25], [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
points | table | Array of vector3 positions. | |
size | number | `0.25` | Size. |
color | color|string|number | optional | Color. |
duration | number | `0` | Duration. |
Renders markers at every position in points.
debug.drawPosition(position, [rotation], [scale], [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
position | vector3 | Position. | |
rotation | quaternion|vector3 | optional | Rotation. |
scale | vector3 | {0, 0, 0} | Scale. |
color | color|string|number | optional | Color. |
duration | number | `0` | Duration. |
Renders XYZ axes representing position and rotation.
debug.drawRay(origin, direction, length, [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
origin | vector3 | Ray origin. | |
direction | vector3 | Ray direction vector. | |
length | number | Ray length. | |
color | color|string|number | optional | Ray color. |
duration | number | `0` | Duration in seconds. |
Draws a ray starting at origin extending in direction for length units.
debug.drawSphere(position, [radius = 0.5], [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
position | vector3 | Center position. | |
radius | number | `0.5` | Radius in world units. |
color | color|string|number | optional | Sphere color. |
duration | number | `0` | Duration. |
Visualizes a spherical radius or trigger zone in 3D.
debug.drawSphereXf(position, [rotation], [scale], [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
position | vector3 | Center. | |
rotation | quaternion|vector3 | optional | Rotation. |
scale | vector3 | {0, 0, 0} | Scale (ellipsoid). |
color | color|string|number | optional | Color. |
duration | number | `0` | Duration. |
Draws an oriented and non-uniformly scaled sphere.
debug.drawSquare(position, [size = 0.2], [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
position | vector3 | Center. | |
size | number | `0.2` | Side length. |
color | color|string|number | optional | Color. |
duration | number | `0` | Duration. |
Renders a flat billboard square.
debug.drawText(position, text, [size = 32], [color], [duration = 0])| Parameter | Type | Default | Description |
|---|---|---|---|
position | vector3 | 3D world position. | |
text | string | Label text. | |
size | number | `32` | Font size. |
color | color|string|number | optional | Text color. |
duration | number | `0` | Duration in seconds. |
Renders a text label in 3D world coordinates.
debug.drawText(pos, "Enemy Spawn Point", 24, color.new(1, 1, 0), 5.0)debug.endTextGroup()Closes the current debug text group.
debug.is2DEnabled()booleanTrue if 2D debug is enabled.
Returns true if 2D text is enabled.
debug.is3DEnabled()booleanTrue if 3D debug is enabled.
Returns true if 3D debug is enabled.
debug.isDebugEnabled()booleanTrue if enabled.
Returns true if debug draw is active.
debug.set2DEnabled(state)| Parameter | Type | Default | Description |
|---|---|---|---|
state | boolean | Enable/disable flag. |
Enables or disables 2D debug text.
debug.set3DEnabled(state)| Parameter | Type | Default | Description |
|---|---|---|---|
state | boolean | Enable/disable flag. |
Enables or disables 3D debug rendering.
debug.setDebugEnabled(state)| Parameter | Type | Default | Description |
|---|---|---|---|
state | boolean | Enable/disable flag. |
Enables or disables debug rendering globally.
debug.setText(key, [value = ""], [priority = 0], [color], [duration = -1])| Parameter | Type | Default | Description |
|---|---|---|---|
key | string | Unique debug key title. | |
value | string | `""` | Text value. |
priority | number | `0` | Order priority. |
color | color|string|number | optional | Text color. |
duration | number | `-1` | Display duration in seconds (-1 = until next frame). |
Draws text on the 2D HUD debug overlay.
debug.setText("Player Speed", tostring(speed), 10)