Draw

The utils.draw module covers all native draw functions, and a selection of custom functions.

Draw functions should typically be run on each frame; however, continuously updating this way can be client intensive. For better performance and stability, consider implementing NUI-based alternatives when possible.

Functions

text()

Draws text on the screen with customisable parameters.

local function text(params)
    local coords = params.coords or vector3(0.5, 0.5, 0.0)
    local content = params.content or ""
    local scale = params.scale or 1.0
    local colour = params.colour or {255, 255, 255, 255}
    local font = params.font or 0
    local alignment = params.alignment or 'left'
    local drop_shadow = params.drop_shadow or {0, 0, 0, 0, 255}
    local text_edge = params.text_edge or {2, 0, 0, 0, 150}
    local mode = params.mode or '2d'
    if alignment == 'center' then
        SetTextCentre(true)
    elseif alignment == 'right' then
        SetTextRightJustify(true)
        SetTextWrap(0.0, coords.x)
    end
    SetTextFont(font)
    SetTextProportional(1)
    SetTextColour(table.unpack(colour))
    SetTextDropShadow(table.unpack(drop_shadow))
    SetTextEdge(table.unpack(text_edge))
    SetTextDropShadow()
    SetTextOutline()
    SetTextEntry("STRING")
    AddTextComponentString(content)
    if mode == '2d' then
        SetTextScale(scale, scale)
        DrawText(coords.x, coords.y)
    elseif mode == '3d' then
        local cam_coords = GetGameplayCamCoords()
        local dist = #(cam_coords - coords)
        local fov = (1 / GetGameplayCamFov()) * 100
        local scale_multiplier = scale * fov * (1 / dist) * 2
        SetTextScale(0.0 * scale_multiplier, 0.55 * scale_multiplier)
        SetDrawOrigin(coords.x, coords.y, coords.z, 0)
        DrawText(0.0, 0.0)
        ClearDrawOrigin()
    end
end

exports('draw_text', text)
utils.draw.text = text

Example

--- Draws text on screen with custom params.
utils.draw.text({
    coords = vector3(0.5, 0.5, 0.0),
    content = "Hello, world!",
    scale = 0.35,
    colour = {255, 255, 0, 255},
    font = 1,
    alignment = 'center',
    drop_shadow = {1, 0, 0, 0, 255},
    text_edge = {1, 255, 255, 255, 255},
    mode = '2d'
})

line()

Draws a line between too points in the world.

Function

local function line(params)
    local start_pos = params.start_pos
    local end_pos = params.end_pos
    local colour = params.colour or {255, 255, 255, 255}
    if not start_pos or not end_pos then
        return utils.debug.warn('Invalid vector3 coordinates provided to utils.draw.line function.')
    end
    DrawLine(start_pos.x, start_pos.y, start_pos.z, end_pos.x, end_pos.y, end_pos.z, table.unpack(colour))
end

exports('draw_line', line)
utils.draw.line = line

Example

--- Draws a line.
utils.draw.line({
    start_pos = vector3(250.0, -1350.0, 30.0),
    end_pos = vector3(260.0, -1360.0, 30.0),
    colour = {255, 0, 0, 255}
})

line_2d()

Draws a 2D line on the screen.

Function

local function line_2d(params)
    local start_pos = params.start_pos
    local end_pos = params.end_pos
    local width = params.width
    local colour = params.colour or {255, 255, 255, 255}
    if not start_pos or not start_pos.x or not start_pos.y or not end_pos or not end_pos.x or not end_pos.y then
        return utils.debug.warn("Invalid 2D coordinates provided to utils.draw.line_2d function.")
    end
    DrawLine_2d(start_pos.x, start_pos.y, end_pos.x, end_pos.y, width, table.unpack(colour))
end

exports('draw_line_2d', line_2d)
utils.draw.line_2d = line_2d

Example

utils.draw.line_2d({
    start_pos = {x = 0.5, y = 0.5},
    end_pos = {x = 0.7, y = 0.7},
    width = 2,
    colour = {0, 255, 0, 255}
})

marker()

Draws a 3D marker in the world.

Function

local function marker(params)
    local coords = params.coords or vector3(0.0, 0.0, 0.0)
    local dir = params.dir or vector3(0.0, 0.0, 1.0)
    local rot = params.rot or vector3(0.0, 0.0, 0.0)
    local scale = params.scale or vector3(1.0, 1.0, 1.0)
    local colour = params.colour or {255, 0, 0, 255}
    DrawMarker(params.type, coords.x, coords.y, coords.z, dir.x, dir.y, dir.z, rot.x, rot.y, rot.z, scale.x, scale.y, scale.z, colour[1], colour[2], colour[3], colour[4], params.bob, params.face_cam, params.p19, params.rotate, params.texture_dict, params.texture_name, params.draw_on_ents)
end

exports('draw_marker', marker)
utils.draw.marker = marker

Example

utils.draw.marker({
    type = 1,
    coords = vector3(100.0, 200.0, 300.0),
    dir = vector3(0.0, 0.0, -1.0),
    rot = vector3(0.0, 0.0, 0.0),
    scale = vector3(2.0, 2.0, 2.0),
    colour = {255, 255, 0, 200},
    bob = true,
    face_cam = false,
    p19 = 2,
    rotate = true,
    texture_dict = nil,
    texture_name = nil,
    draw_on_ents = false
})

movie()

Plays and draws a BINK movie on screen.

Function

local function movie(params)
    local bink = params.bink
    local coords = params.coords or {x = 0.5, y = 0.5}
    local scale = params.scale or {x = 1.0, y = 1.0}
    local rotation = params.rotation or 0.0
    local colour = params.colour or {255, 255, 255, 255}
    CreateThread(function()
        SetBinkMovieTime(bink, 0.0) -- Seeks to 0%, just in case of errors.
        while (GetBinkMovieTime(bink) < 100.0) do
            PlayBinkMovie(bink)
            DrawBinkMovie(bink, coords.x, coords.y, scale.x, scale.y, rotation, table.unpack(colour))
            Wait(0)
        end
    end)
end

exports('draw_movie', movie)
utils.draw.movie = movie

Example

--- Draw a movie from specified handle.
utils.draw.movie({
    bink = bink_handle,
    coords = {x = 0.5, y = 0.5},
    scale = {x = 1.0, y = 1.0},
    rotation = 45.0,
    colour = {255, 200, 200, 255}
})

box()

Draws a 3D box between two points.

Function

local function box(params)
    local start_coords = params.start_coords
    local end_coords = params.end_coords
    local colour = params.colour or {255, 255, 255, 255}
    if not start_coords or not end_coords then
        return utils.debug.warn("Invalid vector3 coordinates provided to utils.draw.box function.")
    end
    DrawBox(start_coords.x, start_coords.y, start_coords.z, end_coords.x, end_coords.y, end_coords.z, table.unpack(colour))
end

exports('draw_box', box)
utils.draw.box = box

Example

--- Draw a 3D box.
utils.draw.box({
    start_coords = vector3(100.0, 100.0, 20.0),
    end_coords = vector3(105.0, 105.0, 25.0),
    colour = {255, 100, 100, 200}
})

draw_rotated_box()

Draws a rotated 3D box using draw lines, between corners after rotation.

Function

local function draw_rotated_box(corners, colour)
    if not (type(corners) == 'table' and #corners > 0) then
        return utils.debug.warn("Invalid corners table provided to utils.draw.draw_rotated_box function.")
    end
    if not (type(colour) == 'table' and #colour == 4) then
        return utils.debug.warn("Invalid colour table provided to utils.draw.draw_rotated_box function.")
    end
    for i=1, #corners do
        local next_index = i % #corners + 1
        DrawLine(corners[i].x, corners[i].y, corners[i].z, corners[next_index].x, corners[next_index].y, corners[next_index].z, colour[1], colour[2], colour[3], colour[4])
    end
end

exports('draw_rotated_box', draw_rotated_box)
utils.draw.draw_rotated_box = draw_rotated_box

Example

--- Draws a rotated box at specified points.
utils.draw.draw_rotated_box({
    vector3(100.0, 100.0, 20.0),
    vector3(105.0, 100.0, 20.0),
    vector3(105.0, 105.0, 25.0),
    vector3(100.0, 105.0, 25.0)
}, {255, 200, 200, 255})

draw_3d_cuboid()

Draws a 3D cuboid around a point based on given dimensions and heading.

Function

local function draw_3d_cuboid(center, dimensions, heading, colour)
    if not center or not dimensions or not colour then
        return utils.debug.warn("Invalid parameters provided to utils.draw.draw_3d_cuboid function.")
    end
    local bottom_center = vector3(center.x, center.y, center.z - dimensions.height / 2)
    local bottom_corners = utils.geometry.rotate_box(bottom_center, dimensions.width, dimensions.length, heading)
    local top_corners = {}
    for i, corner in ipairs(bottom_corners) do
        top_corners[i] = vector3(corner.x, corner.y, corner.z + dimensions.height)
    end
    draw_rotated_box(bottom_corners, colour)
    draw_rotated_box(top_corners, colour)
    for i=1, #bottom_corners do
        DrawLine(bottom_corners[i].x, bottom_corners[i].y, bottom_corners[i].z, top_corners[i].x, top_corners[i].y, top_corners[i].z, colour[1], colour[2], colour[3], colour[4])
    end
end

exports('draw_3d_cuboid', draw_3d_cuboid)
utils.draw.draw_3d_cuboid = draw_3d_cuboid

Example

--- Draw a 3d cuboid.
utils.draw.draw_3d_cuboid(
    vector3(150.0, 150.0, 30.0),
    {width = 10.0, length = 5.0, height = 3.0},
    45,
    {255, 100, 100, 255}
)

draw_interactive_sprite()

Draws an interactive sprite on screen.

Function

local function interactive_sprite(params)
    local texture_dict = params.texture_dict
    local texture_name = params.texture_name
    local coords = params.coords or vector3(0.5, 0.5, 0.0)
    local size = params.size or {width = 1.0, height = 1.0}
    local rotation = params.rotation or 0.0
    local colour = params.colour or {255, 255, 255, 255}
    if not texture_dict or not texture_name then
        return utils.debug.warn("Invalid texture dictionary or name provided to utils.draw.interactive_sprite function.")
    end
    utils.requests.texture(texture_dict, true)
    DrawInteractiveSprite(texture_dict, texture_name, coords.x, coords.y, size.width, size.height, rotation, table.unpack(colour))
end

exports('draw_interactive_sprite', interactive_sprite)
utils.draw.interactive_sprite = interactive_sprite

Example

--- Draws an interactive sprite.
utils.draw.interactive_sprite({
    texture_dict = 'commonmenu',
    texture_name = 'shop_box_tick',
    coords = vector3(0.8, 0.8, 0.0),
    size = {width = 0.05, height = 0.09},
    rotation = 0,
    colour = {255, 255, 255, 200}
})

draw_light()

Draws a light with a specified range and optional shadow.

Function

local function light(params)
    local coords = params.coords or vector3(0.0, 0.0, 0.0)
    local colour = params.colour or {255, 255, 255}
    local range = params.range or 10.0
    local intensity = params.intensity or 1.0    
    if params.shadow then
        local shadow = params.shadow or 2.5
        DrawLightWithRangeAndShadow(coords.x, coords.y, coords.z, colour[1], colour[2], colour[3], range, intensity, shadow)
    else
        DrawLightWithRange(coords.x, coords.y, coords.z, colour[1], colour[2], colour[3], range, intensity)
    end
end

exports('draw_light', light)
utils.draw.light = light

Example

--- Draws a light.
utils.draw.light({
    coords = vector3(100.0, 200.0, 30.0),
    colour = {255, 200, 150},
    range = 20.0,
    intensity = 2.0,
    shadow = 1.0
})

poly()

Draws a polygon in the world.

Function

local function poly(params)
    local vertex1 = params.vertex1 or vector3(0.0, 0.0, 0.0)
    local vertex2 = params.vertex2 or vector3(0.0, 0.0, 0.0)
    local vertex3 = params.vertex3 or vector3(0.0, 0.0, 0.0)
    local colour = params.colour or {255, 0, 0, 255}
    DrawPoly(vertex1.x, vertex1.y, vertex1.z, vertex2.x, vertex2.y, vertex2.z, vertex3.x, vertex3.y, vertex3.z, colour[1], colour[2], colour[3], colour[4])
end

exports('draw_poly', poly)
utils.draw.poly = poly

Example

--- Draws a polygon.
utils.draw.poly({
    vertex1 = vector3(100.0, 200.0, 300.0),
    vertex2 = vector3(150.0, 250.0, 300.0),
    vertex3 = vector3(200.0, 200.0, 300.0),
    colour = {255, 100, 100, 200}
})

rect()

Draws a rectangle on screen.

Function

local function rect(params)
    local coords = params.coords or vector2(0.0, 0.0)
    local width = params.width or 0.1
    local height = params.height or 0.05
    local colour = params.colour or {255, 255, 255, 255}
    DrawRect(coords.x, coords.y, width, height, table.unpack(colour))
end

exports('draw_rect', rect)
utils.draw.rect = rect

Example

--- Draw rectangle on screen.
utils.draw.rect({
    coords = vector2(0.5, 0.5),
    width = 0.2,
    height = 0.1,
    colour = {255, 0, 0, 200}
})

draw_scaleform_movie()

Draws a scaleform movie with specified parameters.

Function

local function scaleform_movie(params)
    local mode = params.mode or "fullscreen"
    local scaleform = params.scaleform
    local colour = params.colour or {255, 255, 255, 255}
    if mode == "3d" or mode == "3d_solid" then
        local coords = params.coords or vector3(0.0, 0.0, 0.0)
        local rotation = params.rotation or vector3(0.0, 0.0, 0.0)
        local scale = params.scale or vector3(1.0, 1.0, 1.0)
        local sharpness = params.sharpness or 15.0
        if mode == "3d" then
            DrawScaleformMovie_3d(scaleform, coords.x, coords.y, coords.z, rotation.x, rotation.y, rotation.z, 2.0, sharpness, 2.0, scale.x, scale.y, scale.z, 2)
        else
            DrawScaleformMovie_3dSolid(scaleform, coords.x, coords.y, coords.z, rotation.x, rotation.y, rotation.z, 2.0, sharpness, 2.0, scale.x, scale.y, scale.z, 2)
        end
    elseif mode == "fullscreen" then
        local width = params.width or 1.0
        local height = params.height or 1.0
        DrawScaleformMovie(scaleform, 0.5, 0.5, width, height, colour[1], colour[2], colour[3], colour[4], 0)
    elseif mode == "fullscreen_masked" then
        local scale_form_mask = params.scale_form_mask
        DrawScaleformMovieFullscreenMasked(scaleform, scale_form_mask, colour[1], colour[2], colour[3], colour[4])
    end
end

exports('draw_scaleform_movie', scaleform_movie)
utils.draw.scaleform_movie = scaleform_movie

Example

--- Draws a scaleform 3d movie.
utils.draw.scaleform_movie({
    mode = '3d',
    scaleform = scaleform_handle,
    coords = vector3(100.0, 200.0, 300.0),
    rotation = vector3(0.0, 0.0, 90.0),
    scale = vector3(2.0, 2.0, 2.0),
    colour = {255, 100, 100, 255}
})

showroom()

Draws a showroom.

Function

local function showroom(params)
    local p0 = params.p0 or "CELEBRATION_WINNER"
    local ped = params.ped or PlayerPedId()
    local p2 = params.p2 or 0
    local coords = params.coords or vector3(0.5, 0.5, 0.0)
    DrawShowroom(params.p0, params.ped, params.p2, params.coords.x, params.coords.y, params.coords.z)
end

exports('draw_showroom', showroom)
utils.draw.showroom = showroom

Example

--- Draw showroom.
utils.draw.showroom({
    p0 = "CELEBRATION_WINNER",
    ped = GetPlayerPed(-1),
    p2 = 1,
    coords = vector3(100.0, 200.0, 300.0)
})

sphere()

Draws a sphere in the game world.

Function

local function sphere(params)
    local coords = params.coords or vector3(0.5, 0.5, 0.0)
    local radius = params.radius or 1.0
    local colour = params.colour or {255, 0, 0, 255}
    local opacity = (colour[4] / 255)
    opacity = math.min(math.max(opacity, 0.0), 1.0)
    DrawSphere(coords.x, coords.y, coords.z, radius, colour[1], colour[2], colour[3], opacity)
end

exports('draw_sphere', sphere)
utils.draw.sphere = sphere

Example

--- Draws a sphere.
utils.draw.sphere({
    coords = vector3(100.0, 200.0, 300.0),
    radius = 5.0,
    colour = {255, 100, 100, 200}
})

spot_light()

Draws a spotlight with or without shadow based on parameters.

Function

local function spot_light(params)
    local coords = params.coords or vector3(0.5, 0.5, 0.0)
    local direction = params.direction or vector3(1.0, 0.0, 0.0)
    local colour = params.colour or {255, 0, 0}
    local distance = params.distance or 100.0
    local brightness = params.brightness or 1.0
    local hardness = params.hardness or 0.0
    local radius = params.radius or 13.0
    local falloff = params.falloff or 1.0
    if params.shadow_id then
        DrawSpotLightWithShadow(params.coords.x, params.coords.y, params.coords.z, params.direction.x, params.direction.y, params.direction.z, params.colour[1], params.colour[2], params.colour[3], params.distance, params.brightness, params.roundness, params.radius, params.falloff, params.shadow_id)
    else
        DrawSpotLight(params.coords.x, params.coords.y, params.coords.z, params.direction.x, params.direction.y, params.direction.z, params.colour[1], params.colour[2], params.colour[3], params.distance, params.brightness, params.hardness, params.radius, params.falloff)
    end
end

exports('draw_spot_light', spot_light)
utils.draw.spot_light = spot_light

Example

--- Draws a spotlight with shadow.
utils.draw.spot_light({
    coords = vector3(100.0, 200.0, 300.0),
    direction = vector3(0.0, 1.0, -0.5),
    colour = {255, 255, 100},
    distance = 150.0,
    brightness = 2.0,
    hardness = 0.5,
    radius = 20.0,
    falloff = 0.8,
    shadow_id = 250
})

sprite()

Draws a 2D sprite on screen.

Function

local function sprite(params)
    local texture_dict = params.texture_dict or 'CommonMenu'
    local texture_name = params.texture_name or 'last_team_standing_icon'
    local coords = params.coords or vector2(0.5, 0.5)
    local size = params.size or {width = 1.0, height = 1.0}
    local rotation = params.rotation or 0.0
    local colour = params.colour or {255, 255, 255, 255}
    DrawSprite(texture_dict, texture_name, coords.x, coords.y, size.width, size.height, rotation, table.unpack(colour))
end

exports('draw_sprite', sprite)
utils.draw.sprite = sprite

Example

--- Draws a 2d sprite.
utils.draw.sprite({
    texture_dict = 'CommonMenu',
    texture_name = 'interaction_bgd',
    coords = vector2(0.5, 0.5),
    size = {width = 0.2, height = 0.2},
    rotation = 45.0,
    colour = {255, 100, 100, 200}
})

draw_sprite_poly()

Draws a sprite polygon in the world.

Function

local function sprite_poly(params)
    local vertices = params.vertices or {vector3(0.0, 0.0, 0.0), vector3(0.0, 0.0, 0.0), vector3(0.0, 0.0, 0.0)}
    local texture_dict = params.texture_dict or "deadline"
    local texture_name = params.texture_name or "deadline_trail"
    local UVW = params.UVW or {{0.0, 0.0, 0.0}, {0.0, 0.0, 0.0}, {0.0, 0.0, 0.0}}
    local mode = params.mode or "single"
    
    if mode == "single" then
        local colour = params.colour or {255, 0, 0, 255}
        DrawSpritePoly(vertices[1].x, vertices[1].y, vertices[1].z, vertices[2].x, vertices[2].y, vertices[2].z, vertices[3].x, vertices[3].y, vertices[3].z, colour[1], colour[2], colour[3], colour[4], texture_dict, texture_name, UVW[1][1], UVW[1][2], UVW[1][3], UVW[2][1], UVW[2][2], UVW[2][3], UVW[3][1], UVW[3][2], UVW[3][3])
    elseif mode == "multi" then
        local colours = params.colours or {{255, 255, 255, 255}, {255, 255, 255, 255}, {255, 255, 255, 255}}
        DrawSpritePoly_2(vertices[1].x, vertices[1].y, vertices[1].z, vertices[2].x, vertices[2].y, vertices[2].z, vertices[3].x, vertices[3].y, vertices[3].z, colours[1][1], colours[1][2], colours[1][3], colours[1][4], colours[2][1], colours[2][2], colours[2][3], colours[2][4], colours[3][1], colours[3][2], colours[3][3], colours[3][4], texture_dict, texture_name, UVW[1][1], UVW[1][2], UVW[1][3], UVW[2][1], UVW[2][2], UVW[2][3], UVW[3][1], UVW[3][2], UVW[3][3])
    end
end

exports('draw_sprite_poly', sprite_poly)
utils.draw.sprite_poly = sprite_poly

Example

--- Draws a single sprite polygon.
utils.draw.sprite_poly({
    vertices = {
        vector3(100.0, 200.0, 300.0),
        vector3(150.0, 250.0, 300.0),
        vector3(100.0, 250.0, 350.0)
    },
    colour = {255, 100, 100, 200},
    texture_dict = 'generic_textures',
    texture_name = 'test_texture',
    UVW = {{0.0, 0.0}, {1.0, 0.0}, {0.5, 1.0}},
    mode = 'single'
})

sprite_uv()

Draws a 2D sprite with specific UV coordinates.

Function

local function sprite_uv(params)
    local texture_dict = params.texture_dict or 'CommonMenu'
    local texture_name = params.texture_name or 'last_team_standing_icon'
    local coords = params.coords or vector2(0.5, 0.5)
    local size = params.size or {width = 1.0, height = 1.0}
    local uv_coords = params.uv_coords or {top_left = {u = 0.0, v = 0.0}, bottom_right = {u = 1.0, v = 1.0}}
    local rotation = params.rotation or 0.0
    local colour = params.colour or {255, 255, 255, 255}
    DrawSpriteUv(texture_dict, texture_name, coords.x, coords.y, size.width, size.height, uv_coords.top_left.u, uv_coords.top_left.v, uv_coords.bottom_right.u, uv_coords.bottom_right.v, rotation, table.unpack(colour))
end

exports('draw_sprite_uv', sprite_uv)
utils.draw.sprite_uv = sprite_uv

Example

--- Draws a sprite at UV coords.
utils.draw.sprite_uv({
    texture_dict = 'generic_textures',
    texture_name = 'example_texture',
    coords = vector2(0.5, 0.5),
    size = {width = 0.2, height = 0.2},
    uv_coords = {
        top_left = {u = 0.25, v = 0.25},
        bottom_right = {u = 0.75, v = 0.75}
    },
    rotation = 45,
    colour = {128, 128, 255, 200}
})

tv_channel()

Draws a TV channel on screen.

Function

local function tv_channel(params)
    local coords = params.coords or vector2(0.5, 0.5)
    local size = params.size or {width = 1.0, height = 1.0}
    local rotation = params.rotation or 0.0
    local colour = params.colour or {255, 255, 255, 255}
    DrawTvChannel(coords.x, coords.y, size.width, size.height, rotation, table.unpack(colour))
end

exports('draw_tv_channel', tv_channel)
utils.draw.tv_channel = tv_channel

Example

--- Draws a tv channel.
utils.draw.tv_channel({
    coords = vector2(0.3, 0.3),
    size = {width = 0.4, height = 0.3},
    rotation = 10,
    colour = {255, 200, 200, 255}
})