Getting started / Overview
Getting started

Luau API

SunketsWare has a Luau runtime built in. Paste a script, press Run, and it runs alongside the menu. It can read the game, draw over it, send input, add its own menu tabs and write files.

Read only

Nothing is written back to the game. Players and parts are a snapshot taken from the same data the ESP reads. part.Position is the real position, but setting it only changes your copy. The client never sees it.

Everything a script creates (drawings, tabs, callbacks, sounds) belongs to that script and is removed when it stops.

A whole script

A box around every player:

local function paint()
    for _, player in ipairs(Players:GetPlayers()) do
        local box = player.BoundingBox
        if box.visible then
            draw.Rect(box.x, box.y, box.w, box.h, Color3.fromRGB(224, 36, 58), 1)
        end
    end
end

cheat.register("onPaint", paint)
Note

Draw calls cover the frame they were made in, so the box is painted from a callback, not once at the top of the script.

Getting started

Your first script

Open the editor, paste, press Run. Nothing to install.

Where scripts go

The LuaU icon in the top dock opens the editor: file list on the left, code on the right, Run on the toolbar. The Output window next to it shows prints and errors.

Scripts you run are normal files in the workspace folder, so they survive a restart. See Files for reading and writing your own data next to them.

Start with something you can see

Press Run and watch the Output window:

print("hello from", identifyexecutor())
print("players in server:", #Players:GetPlayers())

local me = Players.LocalPlayer
if me then
    print("me:", me.Name, "at", me.Position)
end

Now draw something

Health bars over every player:

local function paint()
    for _, player in ipairs(Players:GetPlayers()) do
        if player.Self then
            continue
        end

        local box = player.BoundingBox
        if not box.visible then
            continue
        end

        -- bar sits just above the box
        local w, h = box.w, 3
        local x, y = box.x, box.y - 7
        draw.RectFilled(x, y, w, h, Color3.fromRGB(20, 20, 24), 1)

        local frac = math.clamp(player.Health / math.max(player.MaxHealth, 1), 0, 1)
        draw.RectFilled(x, y, w * frac, h, Color3.fromRGB(224, 36, 58), 1)
    end
end

cheat.register("onPaint", paint)

When nothing appears

SymptomCause
Nothing at allThe script errored on the first line. Check the Output window.
Players missingBoundingBox.visible is false for anyone off screen or behind the camera.
Drawn once, then goneThe draw call was outside a per-frame callback. Read How a script runs.
Nothing while Roblox is unfocusedThe overlay paints over the game, so the game window has to be in front.
Getting started

How a script runs

A script gets its own thread and a slice of every frame. It runs top to bottom, then stays alive only while something holds it: a callback, a task, or a loop with a wait in it.

Threads and slices

Each running script is a coroutine with a budget of 50 ms per frame. When the slice runs out, the script pauses and resumes next frame. A long loop slows that script down instead of freezing the menu or the game.

A loop with no yield still resumes next frame, so it does not lock anything up. It just never gets through a frame of work. Yield with task.wait() or wait().

while true do
    -- your work
    task.wait()          -- hand the frame back
end

Callback order

Callbacks run off the app's clock, not your script's loop, so they keep firing while the script sits in a wait. Each frame, in this order:

EventWhen
onUpdateOnce per frame, before painting.
onPaintOnce per frame, after onUpdate.
RenderSteppedEvery frame.
SteppedEvery frame, after RenderStepped.
HeartbeatEvery frame, after Stepped.
onSlowUpdateOnce a second. Cheap checks, roster scans, config saves.
newPlaceWhen the game swaps place. Re-read anything you cached.
shutdownWhen the script stops or reloads.

RenderStepped, Stepped and Heartbeat are also signals on RunService. They are the same moments, so Stepped plus PreSimulation gives two calls per frame.

Drawing goes in a callback

The draw list is cleared at the start of every frame, so a call made once shows once. Drawing objects behave the same way: the host re-emits them each frame and you only move them.

Stopping

Stop from the editor, or let the script finish. Either way the host removes its callbacks, Drawing objects, tabs, sounds and pending tasks. shutdown fires first, so a script that keeps state on disk can write one last time.

Errors

An error stops that script and prints the script name and line number. Other scripts keep running.

Functions

Global functions

Installed as globals, so they work on the first line.

Printing, timing, request and the rest are on their own pages. What is left is the three below, plus a pile of executor shims covered on Compatibility.

getgenv

getgenv() → table

One table shared by every script in the process. Use it to expose a function from one script to another, or to keep a setting across a script restart.

-- script A
getgenv().shared = getgenv().shared or {}
getgenv().shared.speed = 24

-- script B
print(getgenv().shared and getgenv().shared.speed)
Note

getrenv() answers this same table. The real global environment stays hidden, which is the point of the sandbox.

loadstring

loadstring(source, [chunkName]) → function, or nil + message

Compiles a string as Luau and gives you a function to call. The usual shape is download, compile, run.

local source = game:HttpGet("https://example.com/script.lua")
if not source then
    warn("download failed")
    return
end

local chunk, problem = loadstring(source, "=downloaded")
if not chunk then
    warn("compile failed:", problem)
    return
end

chunk()

A leading = in the chunk name is the Lua convention for "this is a file name", so errors read downloaded:12 instead of [string "downloaded"]:12.

require

require(path) → any

Runs a .lua or .luau file from the workspace folder and returns what it returns. Each file runs once and the result is cached, so two scripts requiring the same module share one copy.

-- lib/mathx.lua
local M = {}
function M.clamp01(v)
    return math.clamp(v, 0, 1)
end
return M

-- main.lua
local mathx = require("lib/mathx.lua")
print(mathx.clamp01(1.4))
Functions

Console

Everything a script prints goes to the Output window. That is where errors show up too.

print

print(...any) → nil

Writes one line. Every argument joins that line.

local me = Players.LocalPlayer
print("local player:", me and me.Name or "none")
print("players:", #Players:GetPlayers())
print(string.format("%.1f studs away", 12.345))

warn

warn(...any) → nil

The same line with a warn: prefix.

notify

notify(message, [title]) → nil

Writes a notify line, with the title in brackets when you pass one. This is a console line only. It does not raise the in-game notification card.

notify("loaded in " .. tostring(playerCount) .. " players", "My Script")

console

console.print(...), console.printl(...), console.warn(...)

The same writers under one table. Both forms reach the same output.

Functions

Input

Reading keys and sending key or mouse events. The events are real injected input, so they go to whatever window has focus.

Reading keys

iskeydown(key) → boolean

True while the key is held. Takes a single character ("w"), a named key ("space", "lshift", "f1"), or an Enum.KeyCode. Full list on Key names.

if iskeydown("w") and iskeydown("lshift") then
    print("sprinting")
end

Sending keys

keypress(key) — down and up together keyrelease(key) — up only keyboard.Press(key) — down only keyboard.Release(key)— up only keyboard.Click(key) — down and up keyboard.IsPressed(key) → boolean

Use press and release for anything held. keypress is a tap: down and up in one call.

-- hold space for half a second
keyboard.Press("space")
task.wait(0.5)
keyboard.Release("space")

Mouse

mouse1click() mouse1press() mouse1release() mouse2click() mouse2press() mouse2release() mousemoverel(dx, dy) mousemoveabs(x, y) mouse.Scroll(delta) mouse.Click(button) — "left", "right", "middle" mouse.IsClicked(button) → boolean

mouse.IsClicked is true only on the frame the button goes down. For the held state use iskeydown("leftmouse").

local function clicker()
    if not isrbxactive() then
        return
    end

    if mouse.IsClicked("left") then
        print("you clicked at", utility.GetMousePos())
    end
end

cheat.register("onUpdate", clicker)

Is the game focused

isrbxactive() → boolean

True when the Roblox window has focus. Guard anything that presses keys with this, or the input lands wherever you are.

input

input(key) → boolean input.IsKeyDown(key) → boolean input.mouse, input.keyboard

The older spelling. input("w") is iskeydown("w"), and the two nested tables are the same mouse and keyboard libraries.

Functions

Files

Scripts get a folder of their own. Relative paths resolve inside it.

Where the files live

Relative paths resolve under %APPDATA%\SunketsWare\workspace, created the first time you ask for it. It sits next to the app's own script folder, not inside it, so a pasted script cannot overwrite the app's files by asking for "luatest.lua".

Absolute paths work only inside those folders. writefile("C:\\Windows\\…") does nothing.

Functions

CallReturns
readfile(path)The whole file as a string.
writefile(path, data)Creates or replaces a file.
appendfile(path, data)Adds to the end of a file.
isfile(path)Boolean.
isdir(path), isfolder(path)Boolean.
makefolder(path)Creates a folder, including parents.
delfile(path)Deletes one file.
delfolder(path), deletefolder(path)Deletes a folder and its contents.
listfiles(path)An array of names in that folder.
getcustomasset(path)A resolvable asset reference, or nil if refused.

All of them also exist on a file table: file.read, file.write, file.append, file.exists, file.isfile, file.isdir, file.isfolder, file.makefolder, file.delete, file.delfolder, file.list.

Saving a setting

local CONFIG = "myconfig.txt"

local function save(speed, colour)
    local text = string.format("%s\n%s\n", tostring(speed), tostring(colour))
    writefile(CONFIG, text)
end

local function load()
    if not isfile(CONFIG) then
        return 20, "#e0243a"
    end

    local speed, colour = readfile(CONFIG):match("([^\n]*)\n([^\n]*)")
    return tonumber(speed) or 20, colour or "#e0243a"
end

Using a picture

Images are read as bytes, not as a path, because that is what the decoder wants. This is the same call behind an Image drawing object.

if isfile("logo.png") then
    local id = utility.LoadImage(readfile("logo.png"))
    print("loaded image id", id)
end
Note

Bytes that are not a picture decode to 0, which draws nothing. Passing the path instead of the bytes is the usual mistake.

Functions

Memory

Typed reads and writes against the game process, through the same bridge the built-in features use.

Read

memory.read(kind, address) → value, or nil

Type first, then address. An address that cannot be read answers nil instead of throwing, so a loop over pointers survives a bad entry.

Write

memory.write(kind, address, value) → boolean

Addresses

memory.getBase() → number memory.rebase(offset) → number

getBase() is the module base. rebase(offset) is base plus offset in one call. Dump offsets are written against the base, so memory.rebase(0x1A2B3C) is usually the address you want.

Kinds

NameReads
"byte", "short", "ushort", "int", "uint"Integers of that width.
"int64", "uint64"64-bit integers.
"float", "double"Floating point.
"bool"A byte, as a boolean.
"pointer", "ptr"A machine pointer.
"string"Bytes up to the first zero, capped at 4096.
"vector2", "vector3", "color3", "cframe"Structs, as the matching object.

Example

local walkSpeed = memory.read("float", memory.rebase(0x2F1A40))
if walkSpeed and walkSpeed > 1 and walkSpeed < 500 then
    print("walk speed", walkSpeed)
end

memory.write("int", memory.rebase(0x2F1A44), 1)
Note

A read on a stale address answers nil or garbage. A write to one is not checked at all. Read and print first, then write. Keep the offset somewhere, because a game update moves it.

Functions

HTTP

Three ways to request a URL, all backed by the same fetch in the app. They block, so the request finishes before the call returns.

game:HttpGet

game:HttpGet(url) → body string, or nil

The one almost every script uses. Anything outside a 2xx status answers nil instead of throwing, so the next line (usually loadstring) does not die on its own.

local raw = game:HttpGet("https://example.com/data.txt")
if raw then
    print(#raw .. " bytes")
end

http.Get and http.Post

http.Get(url, [headers], [callback]) http.Post(url, [headers], [body], [callback])

Headers are the second argument, the callback the last. The callback gets the body on a 2xx response and nil otherwise. The call still blocks, so the callback runs before the next line. A callback that yields is an error; this boundary cannot resume across it.

http.Get("https://example.com/version", {
    ["User-Agent"] = "SunketsWare",
}, function(body)
    print("version:", body)
end)

http.Post("https://example.com/log", nil, "hello")

request

request{ Url, Method, Headers, Body } → { Success, StatusCode, Body, Headers }

The table form behind syn.request and fluxus.request. Method defaults to GET. The result has a boolean, the numeric status, the body, and an empty headers table.

local response = request({
    Url = "https://example.com/api",
    Method = "POST",
    Headers = { ["Content-Type"] = "application/json" },
    Body = '{"event":"loaded"}',
})

if response.Success then
    print(response.StatusCode, response.Body)
else
    warn("request failed:", response.StatusCode)
end
Note

A slow URL stalls that frame for the whole fetch. Fetch once and keep the result instead of fetching from a per-frame callback.

Functions

Audio

Play a WAV you loaded yourself, or a generated tone. Sounds belong to the script that started them.

playSound

audio.playSound(data, [loop], [volume], [pitch]) → boolean

data is the file's bytes, not its name. Volume clamps to 2, pitch to 0.25–4. Returns whether a voice started.

if isfile("click.wav") then
    local ok = audio.playSound(readfile("click.wav"), false, 0.8, 1.0)
    print("playing:", ok)
end

beep

audio.beep([frequency], [milliseconds]) → boolean

A tone with no file behind it. Handy while you build.

audio.beep(660, 90)

stopAll

audio.stopAll() → nil

Stops every voice the app is playing, including loops.

Note

Only WAV is decoded. An MP3 renamed to .wav fails the parse and the call answers false. A file over 32 MB or longer than 60 seconds is refused the same way.

24 sounds play at once. Starting a 25th stops the oldest one that is not looping.

Functions

Miscellaneous

Scheduling, the registration table, entity shortcuts, and a few small things that do not need their own page.

task

task.spawn(fn, ...) task.defer(fn, ...) task.delay(seconds, fn, ...) task.cancel(thread)

spawn and defer start the function now on its own thread. delay starts it after a wait. cancel stops a thread you kept a handle to.

task.delay(2, function()
    print("two seconds later")
end)

local worker = task.spawn(function()
    while true do
        task.wait(0.5)
    end
end)

-- later
task.cancel(worker)

task.wait(n) and wait(n) are the yield points. A loop with one of them in it keeps going indefinitely.

cheat

cheat.register(event, fn) → connection cheat.getWindowSize() → width, height

register is how a script hears frames and lifecycle events. The returned connection can be disconnected. Event list on Events.

entity

entity.GetPlayers([onlyEnemies]) → array of Player entity.GetLocalPlayer() → Player or nil

The same roster Players:GetPlayers() returns. The optional filter keeps only enemies.

Enum

Four enums: Enum.KeyCode, Enum.UserInputType, Enum.HumanoidStateType and Enum.HumanoidRigType. They hold the real member names, so Enum.KeyCode.W works.

setfpscap and getfpscap

setfpscap(value) → previous value getfpscap() → value

The client's frame cap cannot be reached from outside, so this stores the value and reports it back. Nothing is throttled.

typeof

typeof(value) → string

The class name for anything the runtime builds ("Vector3", "Color3", "Player", "Part"), and the normal Lua type for everything else.

Functions

Utility

Timing, mouse position, screen projection, clipboard and image loading.

CallReturns
utility.RandomInt(lo, hi)Whole number in range.
utility.RandomFloat(lo, hi)Fractional number in range.
utility.GetTickCount()Milliseconds since the machine started.
utility.GetDeltaTime()Seconds the last frame took.
utility.GetMousePos()A Vector2 in screen pixels.
utility.GetMenuState()Whether the menu is open.
utility.WorldToScreen(position)x, y, onScreen.
utility.LoadImage(bytes)An image id, or 0.
utility.SetClipboard(text), GetClipboard()System clipboard.
utility.MoveMouse(dx, dy)Moves the cursor by a delta.
utility.GetFingerprint()Machine name, or "sun-unknown".

Every name also exists in snake_case: utility.world_to_screen, utility.get_mouse_pos, and so on.

Projecting a point

utility.WorldToScreen(position) → x, y, onScreen

The third value says whether the point is in front of the camera, so a marker behind you is not drawn at a mirrored spot.

local function paint()
    for _, player in ipairs(Players:GetPlayers()) do
        local x, y, visible = utility.WorldToScreen(player.Position)
        if visible then
            draw.CircleFilled(x, y, 3, Color3.fromRGB(224, 36, 58))
            draw.text(player.Name, x + 8, y - 7, Color3.fromRGB(255, 255, 255))
        end
    end
end

cheat.register("onPaint", paint)
Note

draw.text takes (text, x, y, colour). The older (x, y, text, colour) order is also accepted, so ported scripts keep working.

Classes

Instance

The base of everything the game tree hands you: parts, models, players, the workspace. Each one is a table built from the snapshot.

Fields

FieldType
Namestring
ClassNamestring, e.g. "Part"
ParentInstance or nil

Parts add Position, CFrame and Size. Models add PrimaryPart. Everything below works on all of them.

Methods

CallResult
FindFirstChild(name, [recursive])First child with that name, or nil.
FindFirstChildOfClass(class)First child of that class.
FindFirstChildWhichIsA(class)First child that is or inherits from that class.
GetChildren()Array of direct children.
GetDescendants()Array of everything below it.
IsA(class)Boolean, walks the class chain (Part is a BasePart, and a PVInstance, and an Instance).
GetFullName()Path built by walking parents.
WaitForChild(name)Same lookup as FindFirstChild, and it does not block.
IsDescendantOf(other), IsAncestorOf(other)Boolean.
FindFirstAncestor([name]), FindFirstAncestorOfClass(class)Upwards lookups.
FindFirstDescendant([name]), FindFirstDescendantOfClass(class)Downwards lookups.
GetAttribute(name), GetAttributes(), SetAttribute(name, value)Values stored on your copy.
Clone()A deep copy of your table.
Destroy()Unparents it and drops it from the parent's list.
WorldToScreenPoint()x, y, onScreen for this instance's position.
SetHighlightOnTop(), SetHighlightTransparency(v)Records a highlight hint on your copy.

Instance.new

Instance.new(className, [parent]) → Instance

Builds an empty instance you own. A part starts at the origin with a default size, so set what you need. This is for your own data. It does not create anything in the game.

local group = Instance.new("Model")
group.Name = "MyTargets"

for _, player in ipairs(Players:GetPlayers()) do
    if not player.Self then
        local marker = Instance.new("Part", group)
        marker.Name = player.Name
        marker.Position = player.Position
    end
end

print(#group:GetChildren() .. " markers")
Classes

Player

One entry from the roster, refreshed from the snapshot every frame. Most scripts work through this object.

Fields

FieldMeaning
NameAccount name.
DisplayNameDisplay name, when it differs.
UserIdAlways 0: identity is not exposed to scripts.
TeamTeam name, if the place has teams.
TeamColorThe team's colour as a Color3.
Health, MaxHealthHumanoid health.
IsAliveBoolean.
DistanceStuds from your character.
SelfTrue for your own entry.
Visible, IsVisibleWhether the player is on screen and not occluded.
IsEnemy, IsWhitelistedFrom the cheat's own targeting rules.
WeaponEquipped weapon name, when the place has one.
Position, VelocityWorld space Vector3.
BoundingBoxScreen box: { x, y, w, h, visible }.
ClassName"Player".

Every field also exists in lowercase (player.name, player.position) for older scripts.

BoundingBox

The box is already projected, so it is the quickest way to draw around a player. visible is false when the box is off screen or the player is behind geometry. Test it before drawing.

local function paint()
    for _, player in ipairs(Players:GetPlayers()) do
        local box = player.BoundingBox
        if box.visible and not player.Self then
            draw.Rect(box.x, box.y, box.w, box.h, Color3.fromRGB(224, 36, 58), 1)
            draw.text(player.Name, box.x, box.y - 15, Color3.fromRGB(255, 255, 255))
        end
    end
end

cheat.register("onPaint", paint)

Bones

player:GetBonePosition(bone) → Vector3 player:GetBoneSize(bone) → number player:GetBoneRotation(bone) → table player:GetBoneInstance(bone) → Part

Bone names follow R15: Head, HumanoidRootPart, UpperTorso, LowerTorso, LeftUpperArm, LeftLowerArm, LeftHand, RightUpperArm, RightLowerArm, RightHand, LeftUpperLeg, LeftLowerLeg, LeftFoot, RightUpperLeg, RightLowerLeg, RightFoot. The R6 names (Torso, Left Arm, Left Leg) map to the same slots.

local head = player:GetBonePosition("Head")
local x, y, visible = utility.WorldToScreen(head)
if visible then
    draw.CircleFilled(x, y, 4, Color3.fromRGB(224, 36, 58))
end
Note

The snake_case spellings work too: player:get_bone_position("Head").

Classes

Players

The service that hands out the roster, plus the events for people joining and leaving.

Methods

Players:GetPlayers() → array of Player Players:GetChildren() → same array Players:GetPlayerByName(name) → Player or nil

GetPlayers builds a fresh array each call. Keep the result for the frame instead of calling it inside a nested loop.

local roster = Players:GetPlayers()

local closest, best = nil, math.huge
for _, player in ipairs(roster) do
    if not player.Self and player.Distance < best then
        closest, best = player, player.Distance
    end
end

if closest then
    print("closest:", closest.Name, math.floor(best) .. " studs")
end

LocalPlayer

Players.LocalPlayer → Player

Your own entry. It is read through the service's index, so it stays correct across a respawn. Read it when you need it instead of caching it at the top of the script.

Events

Players.PlayerAdded:Connect(function(player) end) Players.PlayerRemoving:Connect(function(player) end)

Fired from the roster diff on the frame it changes. Events covers disconnecting.

Players.PlayerAdded:Connect(function(player)
    notify(player.Name .. " joined", "Roster")
end)

Players.PlayerRemoving:Connect(function(player)
    notify(player.Name .. " left", "Roster")
end)
Classes

Humanoid

The state of a character: health, movement speed, whether it is standing.

Fields

FieldMeaning
Health, MaxHealthNumbers, 0 to 100 by default.
WalkSpeedStuds per second. The default is 16.
IsAliveBoolean.
MoveDirectionDirection the character is moving, as a Vector3.
Name, ClassName"Humanoid".

Getting one

local character = workspace:FindFirstChild(Players.LocalPlayer.Name)
local humanoid = character and character:FindFirstChildOfClass("Humanoid")

if humanoid and humanoid.IsAlive then
    print(string.format("%d / %d hp", humanoid.Health, humanoid.MaxHealth))
end
Note

Writing humanoid.Health changes your copy only. Raw reads and writes belong to Memory.

Classes

Model

A group of parts with a primary part. Characters are models, and so is anything the game builds as one unit.

Fields

FieldMeaning
NameUsually the player's name for a character.
ClassName"Model".
PrimaryPartThe part that stands for the whole model, usually the humanoid root.
ParentWhere it hangs in the tree.

Everything on Instance works here too: FindFirstChild, GetChildren, GetDescendants, IsA.

Example

local character = workspace:FindFirstChild("MyTarget")
if character and character:IsA("Model") then
    local root = character.PrimaryPart
    if root then
        local x, y, visible = utility.WorldToScreen(root.Position)
        if visible then
            draw.text("target", x, y, Color3.fromRGB(255, 255, 255))
        end
    end
end
Classes

BasePart

Any physical geometry: Part, MeshPart, WedgePart. They all share these fields.

Fields

FieldMeaning
PositionWorld position as a Vector3.
CFramePosition as a CFrame.
SizeVector3, in studs.
Name, ClassNameStrings.
ParentThe model or folder it belongs to.

Example

local function paint()
    for _, part in ipairs(workspace:GetDescendants()) do
        if part:IsA("BasePart") and part.Name == "Objective" then
            local x, y, visible = utility.WorldToScreen(part.Position)
            if visible then
                draw.text("here", x, y, Color3.fromRGB(224, 36, 58))
            end
        end
    end
end

cheat.register("onPaint", paint)
Classes

Workspace

The root of the game tree, and where the camera lives. Reachable as workspace or game.Workspace.

Fields

FieldMeaning
Name"Workspace".
CurrentCameraThe active Camera.
ViewportSizeScreen size as a Vector2.

The walking methods come from Instance, so workspace:GetDescendants() and workspace:FindFirstChild(name) work.

Example

local viewport = workspace.ViewportSize
print("screen:", viewport.X, viewport.Y)

local character = workspace:FindFirstChild(Players.LocalPlayer.Name)
print("character found:", character ~= nil)
Classes

Camera

Where the view is. You need it to relate a world position to what the player can see.

Fields

FieldMeaning
Name"Camera".
PositionWorld position as a Vector3.
CFrameThe same position as a CFrame.
ViewportSizeVector2.

WorldToScreenPoint

camera:WorldToScreenPoint(position) → Vector3, visible

Projects a world point. Screen x and y come back in X and Y. The boolean says whether the point is in front of the camera. Instances have the same method.

local camera = workspace.CurrentCamera
if camera then
    local screen = camera:WorldToScreenPoint(Vector3.new(0, 10, 0))
    print("origin is at", screen.X, screen.Y)
end
Note

utility.WorldToScreen gives plain numbers instead of a vector, which is easier in an expression. Same projection.

Classes

HttpGet Service

Fetch a URL through the game object.

Call

game:HttpGet(url) → string, or nil

The body on a 2xx status, nil for anything else. The second argument some scripts pass is accepted and ignored; nothing is cached.

local body = game:HttpGet("https://example.com/script.lua")
if not body then
    warn("download failed")
    return
end

local chunk = loadstring(body)
if chunk then
    chunk()
end

The game object

game answers a fixed set of keys, resolved on read so they are always current: placeId, Name, ClassName, Parent, Workspace, CurrentCamera, CameraPosition, Players, players, localPlayer, playerCount, Character, RunService. Methods: GetService, GetPlayers, FindFirstChild, GetChildren, GetDescendants, IsA, FindFirstChildOfClass, HttpGet.

print("place", game.placeId, "with", game.playerCount, "players")

local players = game:GetService("Players")
print("same roster:", #players:GetPlayers())
Datatypes

Vector2

Two numbers for anything screen-shaped: mouse position, viewport size, drawing points.

Creating

Vector2.new([x], [y]) → Vector2

Both default to 0. Passing an existing Vector2 copies it.

local point = Vector2.new(120, 40)
print(point.X, point.Y)

Fields

FieldType
X, Ynumbers

Methods

a:Dot(b) → number a:Lerp(b, t) → Vector2

There is no magnitude or arithmetic on a Vector2. For direction maths use a Vector3 and drop the Z.

local mouse = utility.GetMousePos()
local centre = workspace.ViewportSize
local half = Vector2.new(centre.X / 2, centre.Y / 2)

if mouse.X > half.X then
    print("cursor is on the right")
end
Datatypes

Vector3

A point or direction in the world. Most script maths ends up here.

Creating

Vector3.new([x], [y], [z]) → Vector3

Components default to 0. Passing an existing Vector3 copies it.

local a = Vector3.new(0, 0, 0)
local b = Vector3.new(0, 10, 0)
print((b - a).Magnitude)      -- 10

Fields

FieldType
X, Y, Znumbers
MagnitudeThe vector's length.
UnitSame direction, length 1. Zero stays zero.

Methods

a:Dot(b) → number a:Cross(b) → Vector3 a:Lerp(b, t) → Vector3 a:FuzzyEq(b, [epsilon]) → boolean

Operators

+, -, *, / and unary - work, plus == and tostring. Multiplying by a number scales the vector.

local me = Players.LocalPlayer

local function nearest()
    local best, bestDistance = nil, math.huge

    for _, player in ipairs(Players:GetPlayers()) do
        if player.Self then
            continue
        end

        local distance = (player.Position - me.Position).Magnitude
        if distance < bestDistance then
            best, bestDistance = player, distance
        end
    end

    return best, bestDistance
end

local target, distance = nearest()
if target then
    print(target.Name, math.floor(distance))
end

Interpolating

local from = Vector3.new(0, 0, 0)
local to = Vector3.new(0, 20, 0)
print(from:Lerp(to, 0.5))      -- (0, 10, 0)
Datatypes

Color3

A colour with red, green and blue channels. Every draw call takes one.

Creating

Color3.new(r, g, b) — 0 to 1 Color3.fromRGB(r, g, b) — 0 to 255

Use fromRGB when you have hex in mind. The numbers match what a colour picker shows.

local red = Color3.fromRGB(224, 36, 58)
local white = Color3.new(1, 1, 1)
local dark = Color3.fromRGB(20, 20, 24)

Fields

FieldRange
R, G, B0 to 1, not bytes.

Methods

a:Lerp(b, t) → Color3
local low = Color3.fromRGB(224, 36, 58)
local high = Color3.fromRGB(90, 220, 120)

local function healthColour(fraction)
    return low:Lerp(high, math.clamp(fraction, 0, 1))
end

print(healthColour(0.5))
Note

Draw calls also take a table { r, g, b, a } in bytes, a packed 0xRRGGBB number, or four separate integers. Immediate drawing shows where each one goes.

Datatypes

CFrame

A position with an orientation. Here it is only the position; rotation is not part of this runtime's CFrame.

Creating

CFrame.new([x], [y], [z]) → CFrame

Fields

FieldMeaning
X, Y, ZThe position, component by component.
Position, pThe same position as a Vector3.

Example

Read a part's CFrame when you want the position in the form other Roblox code expects. Take .Position to get a Vector3 back.

local camera = workspace.CurrentCamera
print(camera.CFrame.Position)

local here = CFrame.new(0, 5, 0)
print(here.X, here.Y, here.Z)
Note

With no rotation there is nothing to multiply two CFrames for. For angles, use Vector3 maths.

Drawing

Drawing

A Drawing object is a shape you create once and keep. Set its fields and it is painted every frame until you remove it.

Creating

Drawing.new(kind) → DrawingObject, or nil

kind decides which fields the object reads. Any unknown name becomes a rectangle, so Drawing.new("Square") and Drawing.new("Rectangle") both give a box.

KindFields it reads
"Line"From, To, Thickness
"Circle"Position, Radius, Filled, Thickness
"Triangle"PointA, PointB, PointC, Filled
"Quad"PointA, PointB, PointC, PointD, Filled, Thickness
"Polygon"Points (array of Vector2), Filled, Thickness
"Text"Text, Position, Size, Center, Outline
"Image"Data, Position, Size, Rounding
anything elsePosition, Size, Filled, Thickness, Rounding

Every kind also reads Visible, Color and Transparency. DrawingObject goes through each kind.

Example

A box and a label that follow a player. Both are made once, outside the callback:

local box = Drawing.new("Quad")
box.Color = Color3.fromRGB(224, 36, 58)
box.Thickness = 1
box.Filled = false

local label = Drawing.new("Text")
label.Size = 13
label.Color = Color3.fromRGB(255, 255, 255)
label.Center = true

local function paint()
    local player = Players:GetPlayers()[2]
    local rect = player and player.BoundingBox

    if not rect or not rect.visible then
        box.Visible = false
        label.Visible = false
        return
    end

    local left, top = rect.x, rect.y
    local right, bottom = left + rect.w, top + rect.h

    box.PointA = Vector2.new(left, top)
    box.PointB = Vector2.new(right, top)
    box.PointC = Vector2.new(right, bottom)
    box.PointD = Vector2.new(left, bottom)
    box.Visible = true

    label.Text = player.Name
    label.Position = Vector2.new(left + rect.w / 2, top - 16)
    label.Visible = true
end

cheat.register("onPaint", paint)

Removing one

object:Remove() — also object:Destroy()

Hides the object and drops it next frame. Stopping the script removes everything it made, so cleanup only matters if the script keeps making new shapes.

ForceRender

Drawing.ForceRender() → true

Exists because scripts call it. Live objects are already re-emitted every frame, so there is nothing to flush.

Limit

4096 objects at once, across every script. Past that Drawing.new answers nil and the console says so once. Reuse objects instead of making one per frame.

Drawing

DrawingObject

The fields each kind of Drawing object reads. Anything not listed for your kind is stored but not painted.

On every object

FieldType
Visibleboolean. False skips the object entirely.
ColorColor3.
Transparency0 to 1, multiplied into the colour's alpha.
PositionVector2, unless the kind says otherwise.

Objects paint in creation order. Make backgrounds first and text last.

Line

local line = Drawing.new("Line")
line.From = Vector2.new(0, 0)
line.To = Vector2.new(200, 200)
line.Thickness = 1

Circle

Radius is in pixels. Filled picks a disc or a ring. Thickness only matters for the ring.

local dot = Drawing.new("Circle")
dot.Position = Vector2.new(100, 100)
dot.Radius = 4
dot.Filled = true

Triangle and Quad

Corners are absolute screen points, not offsets. A Quad is the shape for a box: four corners, outline or filled.

local quad = Drawing.new("Quad")
quad.Filled = true
quad.PointA = Vector2.new(10, 10)
quad.PointB = Vector2.new(90, 10)
quad.PointC = Vector2.new(90, 40)
quad.PointD = Vector2.new(10, 40)

Polygon

Points is a plain array of Vector2. Assign a new table to update it.

local fan = Drawing.new("Polygon")
fan.Filled = true
fan.Points = {
    Vector2.new(100, 100),
    Vector2.new(160, 60),
    Vector2.new(180, 140),
}

Text

FieldMeaning
TextThe string. An empty string draws nothing.
SizePixel height, 13 by default.
CenterTrue centres the text horizontally on Position.
OutlineTrue draws an outline behind the text.

Size is the one thing draw.text cannot do. That is usually why you reach for a Text object.

local name = Drawing.new("Text")
name.Text = "target"
name.Position = Vector2.new(400, 200)
name.Size = 14
name.Center = true
name.Outline = true

Image

Data is a file the app can resolve, usually a path in the workspace. An unreadable path draws nothing instead of erroring.

local icon = Drawing.new("Image")
icon.Data = "logo.png"
icon.Position = Vector2.new(20, 20)
icon.Size = Vector2.new(32, 32)
icon.Rounding = 6

A bar that fills

local back = Drawing.new("Square")
back.Color = Color3.fromRGB(18, 18, 22)
back.Filled = true

local fill = Drawing.new("Square")
fill.Color = Color3.fromRGB(224, 36, 58)
fill.Filled = true

local function paint()
    local player = Players.LocalPlayer
    local rect = player and player.BoundingBox

    if not rect or not rect.visible then
        back.Visible = false
        fill.Visible = false
        return
    end

    local fraction = math.clamp(player.Health / math.max(player.MaxHealth, 1), 0, 1)
    local height = 4
    local y = rect.y - 8

    back.Position = Vector2.new(rect.x, y)
    back.Size = Vector2.new(rect.w, height)
    back.Visible = true

    fill.Position = Vector2.new(rect.x, y)
    fill.Size = Vector2.new(rect.w * fraction, height)
    fill.Visible = true
end

cheat.register("onPaint", paint)
Drawing

Immediate drawing

The draw table: one call, one shape, that frame. No objects involved.

Signatures

CallShape
draw.line(x1, y1, x2, y2, color, [thickness])Line.
draw.rect(x, y, w, h, color, [rounding])Filled rectangle.
draw.RectFilled(x, y, w, h, color, [rounding])The same filled rectangle.
draw.Rect(x, y, w, h, color, [thickness], [rounding], [alpha])Outline rectangle.
draw.circle(x, y, r, color, [segments], [alpha])Filled circle.
draw.CircleFilled(x, y, r, color)The same filled circle.
draw.Circle(x, y, r, color, [thickness], [segments], [alpha])Ring.
draw.triangle(x1, y1, x2, y2, x3, y3, color, [thickness])Triangle outline.
draw.TriangleFilled(...)Filled triangle.
draw.Gradient(x, y, w, h, color1, color2, [horizontal])Rectangle blending two colours.
draw.Polyline(points, color, [closed], [thickness], [alpha])Open or closed path.
draw.ConvexPolyFilled(points, color, [alpha])Filled hull of the points.
draw.ComputeConvexHull(points)→ array of Vector2, the hull.
draw.GetPartCorners(part)→ the part's corners on screen.
draw.text(text, x, y, color)Text, one fixed size.
draw.TextOutlined(text, x, y, color)The same text with an outline.
draw.GetTextSize(text, [size])→ width, height.
draw.Image(id, x, y, w, h, r, g, b, a)An image from utility.LoadImage.

PascalCase and lowercase are the same function, so draw.line and draw.Line both work. draw.text also takes the older (x, y, text, color) order.

Colours

Any colour slot takes a Color3, a table { r, g, b, a } in bytes, a packed 0xRRGGBB number, or four separate integers. That last one is for ports: 255, 60, 60, 255 after the coordinates lands in the right place.

local red = Color3.fromRGB(224, 36, 58)

draw.Rect(10, 10, 60, 20, red)                 -- Color3
draw.Rect(10, 40, 60, 20, 0xE0243A)            -- packed
draw.Rect(10, 70, 60, 20, 224, 36, 58, 255)    -- rgb + alpha

Draw every frame

The draw list is cleared at the start of each frame, so a call made once shows once. Put calls in onPaint:

local function paint()
    draw.Gradient(20, 20, 220, 80,
        Color3.fromRGB(224, 36, 58),
        Color3.fromRGB(70, 8, 16), true)

    draw.text("SunketsWare", 32, 32, Color3.fromRGB(255, 255, 255))
    draw.Rect(20, 20, 220, 80, Color3.fromRGB(255, 255, 255), 1, 6)
end

cheat.register("onPaint", paint)
Note

draw.text has no size argument; it draws at one size. Use a Text object when you need size, centring or outline.

Drawing

Fonts

The Drawing.Fonts table, and what actually changes how text looks.

The table

Drawing.Fonts.System → 0 Drawing.Fonts.Plex → 1 Drawing.Fonts.Monospace → 2 Drawing.Fonts.UI → 3

It exists so scripts that read Drawing.Fonts do not fall over, and so a Text object can take a Font value without erroring.

Note

Text always draws in the app's own face. Setting Font changes nothing. Size, Center and Outline are what matter.

Measuring text

Ask for the size instead of guessing. It defaults to 13, the size draw.text draws at, so a plain measurement matches what you see:

local width, height = draw.GetTextSize("SunketsWare")

draw.text("SunketsWare", 200 - width / 2, 100, Color3.new(1, 1, 1))

Pass a number as the second argument to measure at another size, which you need to centre a Text object. An older spelling put a face name there and the size third. Both orders work.

Interface

ui

Scripts can add a real tab to the menu, with checkboxes, sliders, dropdowns, colour pickers, buttons and text fields. It behaves like a built-in tab because it is one.

The shape of it

Everything is addressed by name. A tab has a name, a container has a name inside that tab, a widget has a name inside that container. ui.getValue takes those same three names.

ui.newTab("example", "Example")
ui.newContainer("example", "main", "Main")

ui.newCheckbox("example", "main", "Enabled")
ui.newSliderInt("example", "main", "Distance", 0, 500, 150)
ui.newSliderFloat("example", "main", "Smoothing", 0.0, 1.0, 0.25)
ui.newDropdown("example", "main", "Mode", { "Legit", "Rage" }, 1)
ui.newButton("example", "main", "Reset", function()
    ui.setValue("example", "main", "Distance", 150)
end)

local function paint()
    local on = ui.getValue("example", "main", "Enabled")
    if not on then
        return
    end

    local distance = ui.getValue("example", "main", "Distance")
    for _, player in ipairs(Players:GetPlayers()) do
        if player.Distance <= distance and not player.Self then
            local rect = player.BoundingBox
            if rect.visible then
                draw.Rect(rect.x, rect.y, rect.w, rect.h, Color3.fromRGB(224, 36, 58))
            end
        end
    end
end

cheat.register("onPaint", paint)

The tab appears when the script runs and goes away when it stops.

Tabs and containers

ui.newTab(name, [title]) ui.newContainer(tab, name, [title], [options])

The name is the key you pass to every other call. The title is what the strip shows and defaults to the name. A tab name that already exists is ignored, so running the same script again does not duplicate it.

The options table takes:

OptionEffect
visibleBoolean. Starts the container hidden. The only option here that does anything.
autosize, next, halfsizeAccepted for compatibility. Layout is one column, so they do nothing.

Widgets

CallValue it reports
newCheckbox(tab, container, name)boolean
newSliderInt(tab, container, name, lo, hi, default)whole number
newSliderFloat(tab, container, name, lo, hi, default)number
newDropdown(tab, container, name, options, [default])1-based index
newMultiselect(tab, container, name, options)array of booleans
newColorpicker(tab, container, name, colour){ r, g, b, a }, 0–255
newInputText(tab, container, name, [default])string
newListbox(tab, container, name, options, callback)1-based index
newButton(tab, container, name, callback)nothing, it calls you

The name is also the row label, so write it the way you want it read: "Distance", not "dist".

A checkbox starts off, a multiselect starts empty, a listbox starts on its first entry. The extra inline flag that newCheckbox and newColorpicker accept is stored and ignored.

Reading and writing

ui.getValue(tab, container, name) → value, or nil ui.setValue(tab, container, name, value) ui.setVisibility(tab, container, name, visible)

setVisibility shows or hides one widget's row. It does not touch the container. Hide every widget and the card stays, empty.

local picked = ui.getValue("example", "main", "Mode")     -- 1 or 2

local flags = ui.getValue("example", "main", "Targets")   -- { true, false, true }
for index, on in ipairs(flags) do
    if on then
        print("target group", index)
    end
end

local tint = ui.getValue("example", "main", "Colour")
print(tint.r, tint.g, tint.b, tint.a)

Reacting to a button

Buttons and listboxes take a callback. It runs during the next frame with one number: press count for a button, the picked index for a listbox. It runs inside the frame rather than on your script's thread, so it must not yield.

ui.newButton("example", "main", "Announce", function(presses)
    notify("clicked " .. presses .. " time(s)", "Example")
end)

ui.newListbox("example", "main", "Targets", { "Head", "Torso" }, function(picked)
    print("now targeting", picked)      -- 1 or 2
end)
Limit

12 script tabs, 24 containers per tab, 96 widgets per container, 256 options per list. Past those the call does nothing. For the widget and container caps the console says why once.

Events

Events

Two ways to get called: cheat.register for lifecycle moments, signals for things the game changes.

cheat.register

cheat.register(event, callback) → connection
EventFires
"onUpdate"Once per frame, before painting.
"onPaint"Once per frame, after onUpdate.
"RenderStepped"Every frame.
"Stepped"Every frame, after RenderStepped.
"Heartbeat"Every frame, after Stepped.
"onSlowUpdate"Once a second.
"newPlace"When the game swaps place.
"PlayerAdded"When someone joins. The callback gets the player.
"PlayerRemoving"When someone leaves. The callback gets the player.
"shutdown"When the script stops or reloads.

A name outside this table is accepted and never fires, so a typo looks exactly like a callback that never runs. The same store backs the signals below: cheat.register("PlayerAdded", fn) and Players.PlayerAdded:Connect(fn) are the same hook.

local frame = 0

cheat.register("onUpdate", function()
    frame = frame + 1
end)

cheat.register("onSlowUpdate", function()
    print("alive for", frame, "frames")
end)

cheat.register("shutdown", function()
    writefile("state.txt", tostring(frame))
end)

Connections

connection:Disconnect() — also connection:disconnect()

cheat.register returns a connection, so you can cut a callback without stopping the script:

local connection = cheat.register("onSlowUpdate", function()
    print("one second")
end)

task.delay(5, function()
    connection:Disconnect()
end)

Signals

signal:Connect(fn) → connection signal:Once(fn) → connection signal:Wait() → 0, after one frame

Signals exist on Players (PlayerAdded, PlayerRemoving) and on RunService (RenderStepped, Stepped, Heartbeat, plus PreRender, PreSimulation, PostSimulation).

Wait() yields for a frame and returns 0. The host ticks once per frame and cannot park a script until an event arrives, so this is a paced loop, not a real wait. Use Connect when you need the event itself.

local connection = Players.PlayerAdded:Connect(function(player)
    notify(player.Name .. " joined")
    connection:Disconnect()          -- first one only
end)
Note

Stepped and PreSimulation are the same moment. Connecting to both gives two calls per frame, which is easy to misread while debugging.

Reference

Key names

Every input function takes the same spellings: a single character, a name from the table, or an Enum.KeyCode.

Single characters

Any single letter or digit passes through, and case does not matter. Punctuation works too: , . / ; ' - = [ ] \ ` and a space.

Numbers

A whole number is read as a Windows virtual-key code, so 0x57 and "w" are the same key. Anything outside 1–255 finds nothing.

Named keys

GroupNames
Arrowsleft right up down
Whitespacespace tab enter return backspace
Editingdelete insert home end pageup pagedown
Modifiersshift ctrl alt lshift rshift lctrl rctrl lalt ralt
Systemescape esc capslock
Mouseleftmouse lbutton rightmouse rbutton middlemouse mbutton mouse4 mouse5
Functionf1 through f24

Examples

iskeydown("w")
iskeydown("space")
iskeydown("lshift")
iskeydown("leftmouse")
iskeydown("f5")
iskeydown(Enum.KeyCode.E)

An unknown name answers false instead of raising, so a typo looks like a key that is never down.

Reference

Limits

The caps are wide enough for real work and tight enough that one bad loop cannot take the app down. Hitting one writes a line to the console.

WhatCap
Frame slice per script50 ms, then paused and resumed next frame.
Drawing objects4096 alive at once, across all scripts.
Widgets per container96
Containers per tab24
Options per dropdown or listbox256
String read through memory.read4096 bytes.
Image passed to utility.LoadImage12 MB of encoded bytes.
Images held at once64; the oldest is dropped when a new one arrives.
Sound fileWAV only, 32 MB and 60 seconds at most. Volume is clamped to 2, pitch to 0.25–4.
Sounds at once24; starting another stops the oldest one-shot.

Stopping a script releases everything it owned: objects, widgets, callbacks, sounds. The counters go back to zero.

Reference

Compatibility

Three naming conventions run side by side, because scripts are written for different environments. All of them reach the same paint list, so a script written for any of them runs without edits.

The three styles

StyleLooks like
SerotoninPascalCase: draw.Rect, draw.Circle, entity.GetPlayers()
Older executor scriptslowercase: draw.rect, draw.circle, getgenv()
Matchaobjects: Drawing.new("Text"), fields on the object

Where the same name exists in two styles, the name decides the shape: draw.rect is filled and takes a corner radius as its last argument, while draw.Rect is an outline and takes thickness and radius last.

What is a shim

Some executor internals exist only so scripts do not die while probing for them. What each one answers:

CallAnswers
cloneref, newcclosureThe argument it was given.
checkcallertrue
islclosurefalse
getgc, getconnectionsAn empty table.
sethiddenpropertyfalse
gethiddenpropertyA placeholder read of the field the object already carries.
firetouchinterest, queue_on_teleport, getnamecallmethodnil

None of these do real work. A script that depends on one for correctness will not get the behaviour it expects.

identifyexecutor() answers "SunketsWare". setfpscap stores its value without throttling anything. notify writes a console line rather than raising a card.

Note

There is no Roblox replication: no RemoteEvents, nothing fired to the server, no reading internal scripts out of the DataModel. A script that needs those will not work.