draw

The `draw` library provides all the functions necessary to draw 2D shapes, and text directly onto the screen.

IMPORTANT: All drawfunctions must be called from within a function registered to the onPaint callback.

All color parameters are integers ranging from 0 to 255.

This script will draw a Polyline tracing the local player's Head.

local TARGET_BONE_NAME  = "Head"
local OUTLINE_COLOR     = Color3.new(0, 1, 1)
local OUTLINE_THICKNESS = 2.0
local OUTLINE_ALPHA     = 255 

local function on_paint()
    local local_player = entity.get_local_player()
    if not local_player then return end

    local head = local_player:get_bone_instance(TARGET_BONE_NAME)
    if not head then return end

    local world_points = draw.get_part_corners(head)
    if not world_points then return end

    local screen_points = {}
    for i, world_pos in ipairs(world_points) do
        local screen_x, screen_y, is_on_screen = utility.world_to_screen(world_pos)
        if is_on_screen then
            table.insert(screen_points, { screen_x, screen_y })
        end
    end

    if #screen_points < 3 then return end

    local hull_points = draw.compute_convex_hull(screen_points)
    if not hull_points or #hull_points < 2 then return end
    
    draw.polyline(hull_points, OUTLINE_COLOR, true, OUTLINE_THICKNESS, OUTLINE_ALPHA)
end

cheat.register("onPaint", on_paint)

draw.Line(x1, y1, x2, y2, color, [thickness], [alpha])

Draws a line between two points.

Parameters:

  • x1, y1: number - Start coordinates.

  • x2, y2: number - End coordinates.

  • color - Color3 object.

  • alpha: number - (optional, default = 255) - the alpa transparency of the color.

  • thickness: number - The thickness of the line in pixels.

draw.Rect(x, y, w, h, color, [thickness], [rounding], [alpha])

Draws the outline of a rectangle.

  • Parameters:

    • x, y: number - Top-left corner coordinates.

    • w, h: number - Width and height.

    • color: Color3 - The color of the outline.

    • alpha: number (optional, default=255) - The alpha transparency of the color.

    • thickness: number (optional, default=1.0) - The thickness of the outline.

    • rounding: number (optional, default=0.0) - The radius of the corner rounding.

draw.RectFilled(x, y, w, h, color, [rounding], [alpha])

Draws a filled rectangle.

  • Parameters:

    • x, y: number - Top-left corner coordinates.

    • w, h: number - Width and height.

    • color: Color3 - The fill color.

    • alpha: number (optional, default=255) - The alpha transparency of the color.

    • rounding: number (optional, default=0.0) - The radius of the corner rounding.

draw.Circle(x, y, radius, color, [thickness], [segments], [alpha])

Draws the outline of a circle.

  • Parameters:

    • x, y: number - Center coordinates.

    • radius: number - The radius of the circle.

    • color: Color3 - The color of the outline.

    • alpha: number (optional, default=255) - The alpha transparency of the color.

    • thickness: number (optional, default=1.0) - The thickness of the outline.

    • segments: integer (optional, default=12) - The number of segments to use. More segments result in a smoother circle.

draw.CircleFilled(x, y, radius, color, [segments], [alpha])

Draws a filled circle.

  • Parameters:

    • x, y: number - Center coordinates.

    • radius: number - The radius of the circle.

    • color: Color3 - The fill color.

    • alpha: number (optional, default=255) - The alpha transparency of the color.

    • segments: integer (optional, default=12) - The number of segments to use. More segments result in a smoother circle.

draw.Triangle(x1, y1, x2, y2, x3, y3, color, [thickness], [alpha])

Draws the outline of a triangle defined by three points.

  • Parameters:

    • x1, y1: number - Coordinates of the first point.

    • x2, y2: number - Coordinates of the second point.

    • x3, y3: number - Coordinates of the third point.

    • color: Color3 - The color of the outline.

    • alpha: number (optional, default=255) - The alpha transparency of the color.

    • thickness: number (optional, default=1.0) - The thickness of the outline.

draw.TriangleFilled(x1, y1, x2, y2, x3, y3, color, [alpha])

Draws a filled triangle defined by three points.

  • Parameters:

    • x1, y1: number - Coordinates of the first point.

    • x2, y2: number - Coordinates of the second point.

    • x3, y3: number - Coordinates of the third point.

    • color: Color3 - The fill color.

    • alpha: number (optional, default=255) - The alpha transparency of the color.

draw.Gradient(x, y, w, h, startColor, endColor, isHorizontal, [startAlpha], [endAlpha])

Draws a rectangle with a two-color gradient.

  • Parameters:

    • x, y, w, h: number - The position and size.

    • startColor, endColor: Color3 - The gradient colors.

    • isHorizontal: boolean - true for left-to-right, false for top-to-bottom.

    • startAlpha: number (optional, default=255) - Alpha for startColor.

    • endAlpha: number (optional, default=255) - Alpha for endColor.

draw.Image(textureId, x, y, w, h, r, g, b, a)

Draws a filled triangle defined by three points.

  • Parameters:

    • textureId: integer - The ID from utility.loadImage.

    • x, y, w, h: number - The position and size.

    • r, g, b, a: integer - The tint color (0-255).

draw.Text(text, x, y, color, [alpha])

Draws text on the screen using the current default font.

  • Parameters:

    • text: string - The text to draw.

    • x, y: number - Top-left coordinates for the text.

    • color: Color3 - The color of the text.

    • alpha: number (optional, default=255) - The alpha transparency of the color.

draw.TextOutlined(text, x, y, color, [alpha])

Draws text with a standard black outline for high contrast and better readability.

  • Parameters:

    • text: string - The text to draw.

    • x, y: number - Top-left coordinates for the text.

    • color: Color3 - The color of the text.

    • alpha: number (optional, default=255) - The alpha transparency.

local white = Color3.new(255, 255, 255)
draw.TextOutlined("PlayerName [100m]", 150, 200, white)

draw.GetTextSize(text)

Calculates the width and height of a string, without actually drawing it. This is useful for positioning elements.

  • Parameters:

    • text: string - The text to measure.

  • Returns:

    • width: number

    • height: number

  • Example:

local my_text = "Hello, World!"
local text_width, text_height = draw.get_text_size(my_text)
print("Text is " .. text_width .. " pixels wide and " .. text_height .. " pixels high.")

draw.ComputeConvexHull(points)

Takes a set of 2D points and returns the smallest possible convex polygon that encloses all of them. This is extremely useful for drawing an outline around multiple, potentially overlapping shapes to create a single, clean silhouette.

  • Parameters:

    • points: table - An array-like table of points to process (e.g., { {x1, y1}, {x2, y2}, ... }).

  • Returns:

    • hull_points: table - A new table of points representing the vertices of the convex hull, ready to be used with draw.Polyline or draw.ConvexPolyFilled.

local all_points = { {100, 100}, {200, 100}, {250, 150}, {250, 250}, {150, 250}, {100, 200} }
local silhouette = draw.compute_convex_hull(all_points)

draw.convex_poly_filled(silhouette, Color3.new(1, 0, 0), 128)

local white_color = Color3.new(1, 1, 1)
draw.Polyline(silhouette, white_color, true, 2.0) -- no alpha passed, defaults to 255

draw.Polyline(points, color, closed, thickness, [alpha])

Draws a series of connected lines through a set of points.

  • Parameters:

    • points: table - An array of points, e.g., { {x1, y1}, {x2, y2}, ... }.

    • color: Color3 - The color of the lines.

    • closed: boolean - If true, connects the last point to the first.

    • thickness: number - The thickness of the lines in pixels.

    • alpha: number (optional, default=255) - The alpha transparency.

local star_points = {
    {100, 20}, {110, 60}, {150, 60}, {120, 85},
    {130, 125}, {100, 100}, {70, 125}, {80, 85},
    {50, 60}, {90, 60}
}
-- draw an open red star shape (alpha will default to 255)
draw.Polyline(star_points, Color3.new(1, 0, 0), false, 2.0)


for i, p in ipairs(star_points) do p[1] = p[1] + 150 end
draw.Polyline(star_points, Color3.new(0, 0, 1), true, 2.0, 128)

draw.ConvexPolyFilled(points, color, [alpha])

Draws a filled, convex polygon. A convex polygon has no "inward-pointing" corners.

  • Parameters:

    • points: table - An ordered array of vertices.

    • color: Color3 - The fill color.

    • alpha: number (optional, default=255) - The alpha transparency.

local hexagon_points = {
    {200, 200}, {250, 200}, {275, 243},
    {250, 286}, {200, 286}, {175, 243}
}
local green = Color3.new(0, 255, 0)
draw.ConvexPolyFilled(hexagon_points, green, 128)

draw.GetPartCorners(part)

Calculates the 8 world-space corners of a part's bounding box, accounting for its position, size, and rotation. This is the recommended way to get points for drawing an outline around a part.

  • Parameters:

    • part: Instance - The Part object to process.

  • Returns:

    • corners_table: table - A table containing 8 Vector3 objects representing each corner, or nil if the part is invalid.

local head = entity.GetLocalPlayer():GetBoneInstance("Head")
if head then
    local corners_3d = draw.GetPartCorners(head)
    if corners_3d then
        -- Now you can loop through 'corners_3d' and use utility.worldToScreen on each one
        -- to get the 2D points needed for drawing.
    end
end
PreviousModelNextutility

Last updated