clover's Lua 5.4 scripting engine, with a Roblox-style API for reading the game, drawing overlays and building menus.

Write scripts in the Lua VM editor and run them with Ctrl+Enter. All scripts share one VM; callbacks, tasks and signals keep running about 60 times per second.

Why use it

• Real Lua 5.4. Integers and floats, bitwise operators, integer division, goto and the utf8 library, plus familiar helpers such as table.find, math.clamp, string.split and Random.new.
• Roblox-style API. game, workspace, Instance, Vector2, Vector3, CFrame, Color3, Enum, task, RunService, UserInputService and TweenService are available with Roblox names.
• Executor compatibility. Common executor functions are built in, including readfile, getgenv, loadstring, decompile, getgc, fireserver, queue_on_teleport, crypt and WebSocket.
• Fast overlays. Immediate-mode draw.* calls (up to 500000 commands per frame) and retained Drawing.new objects render on top of the game.
• Menus in a few lines. Clover:CreateWindow builds windows with tabs, sections, buttons, toggles, sliders, inputs, dropdowns, keybinds and color pickers, and can save and load configs.
• Any naming style. Helper namespaces such as draw, utility, mouse and file accept PascalCase, snake_case and camelCase names for the same function.
• Safe by default. There is no io, no require and only a small os subset. HTTP, WebSocket, the clipboard, setfflag and the debug library stay off until you allow them, files never leave the workspace folder, the Lua heap is capped at 1 GB, and a runaway loop can always be stopped with Reset VM.
• Teleport aware. Scripts queued with queue_on_teleport run in a fresh VM after the game teleports.
• Agent ready. A built-in MCP server lets AI coding agents run Lua, read the log, edit editor tabs, manage workspace files and inspect the game.

Where to go next

How the clover VM is built and reset, how it schedules your code, and how it reports output and errors.

local steps = 0

clover.on_tick(function()
    steps = steps + 1
end)

clover.on_render(function()
    draw.Text(20, 40, "scheduler steps: " .. steps, 1, 1, 1, 1)
end)

task.spawn(function()
    while true do
        task.wait(5)
        print("steps so far:", steps)
    end
end)

print("setup done")

VM lifecycle

There is exactly one VM. clover starts it while it starts its modules, and the first Run starts it if it is not running yet. It is stopped when clover exits. In between it can be reset any number of times.

How the VM is built

1. A new Lua state is created with an allocator that caps the VM at 1 GB of Lua memory.
2. The standard libraries are opened and restricted (see Sandbox & Safety). debug is opened only when the unsafe API is allowed.
3. The clover table is registered, together with global shortcuts such as readfile, getgenv, tick, typeof, notify and WorldToScreen.
4. The Roblox-style layer is registered: the data types, print and warn, task, bit32, the services and HTTP functions, Drawing, Instance, game and workspace, the script and GC helpers, WebSocket and crypt. Then three Lua chunks add the standard library extensions, Enum with the input and service helpers, and the compatibility shims.
5. clover.ui is registered, the instruction-count hook is installed, and the Lua prelude builds the draw, utility, keyboard, mouse, cheat and file tables and the Clover menu library.

The scheduler step

A dedicated script thread drives the VM in a loop. Each pass, called a step here, does the following and then sleeps for 16 ms, so the VM steps roughly 60 times per second at most:

1. Apply a pending reset, if one was requested.
2. If the master switch is off, clear the draw list and skip the rest of the step.
3. Run every queued chunk in order: editor runs, MCP lua_execute calls and teleport scripts.
4. Call every tick callback, then every render callback.
5. Pump the engine: refresh game and workspace and fire player and child signals, advance tweens, resume task.wait threads whose time is up, start due task.delay and task.defer functions, fire the RunService step signals (Heartbeat, RenderStepped, Stepped) with the step's delta time, deliver key and mouse input events and WebSocket events, then run queued UI callbacks.
6. Publish the draw commands queued during this step to the overlay.

Reset

A reset throws the whole Lua state away and builds a new one at the start of the next step. It happens when:

• you press Reset VM in the Lua VM window, or an agent calls the MCP lua_reset tool;
• the Allow unsafe Lua API setting changes, from the settings card or the MCP lua_set_unsafe_api tool;
• a teleport is detected while scripts are queued with queue_on_teleport. The queued scripts then run in the new VM (see Teleport).

A reset stops running code (execution interrupted), cancels queued chunks and clears every global, callback, task, connection, tween, Drawing, window and WebSocket. It also empties the teleport queue.

Master switch

Scripts only run while the master switch is on. With it off, Run is refused and running code stops with master switch is off. The VM isn't reset, so callbacks resume when it's turned back on.

Running code

Each run is compiled as a chunk named script and started in a new coroutine, so top-level code can call task.wait.

Because of the chunk name, positions in error messages look like [string "script"]:12:.

Callbacks

Code that must run on every step is registered as a callback instead of being written as a loop. There are two callback lists, documented on the cheat page:

• Both lists run on the script thread, in registration order, with no arguments. Render callbacks are the place for draw.* calls, because the draw list is rebuilt every step.
• Callbacks are called with a plain protected call on the VM's main thread, so they cannot yield: calling task.wait inside one raises an error. Start a task with task.spawn when a callback needs to wait.
• A callback that raises an error is logged as [clover error 3] and removed for good. There is no function to unregister a callback; it stays until it errors or the VM resets.
• cheat.register silently ignores event names it does not know.

Tasks and signals

task is a coroutine scheduler. task.wait sleeps (rounded up to whole ticks), task.spawn runs a function now, and task.delay/task.defer run one later. An error ends only that task.

Signals like RunService.Heartbeat and InputBegan fire during each tick. Handlers can't yield, and one that errors is disconnected. :Wait() pauses until the next fire.

Naming conventions

Engine functions live on clover (for example clover.draw_line) and are re-exported in PascalCase, snake_case and camelCase. All spellings are the same function.

• Single-word names have two spellings: draw.Line and draw.line, file.Read and file.read.
• A few raw functions have a second raw name: clover.printl for clover.print, clover.errorl for clover.error, clover.getbase for clover.module_base, clover.iskeypressed for clover.is_key_down and clover.WorldToScreen for clover.world_to_screen.
• Frequently used functions are also globals: readfile, writefile, appendfile, isfile, isfolder, makefolder, delfile, listfiles, getgenv, tick, typeof, base64encode, base64decode, notify, WorldToScreen and world_to_screen. The Globals page lists every global name.
• Roblox-style APIs keep Roblox's PascalCase (game:GetService, Instance.new, Vector3.new), and the standard library adds capitalized Roblox-era globals such as Wait, Spawn and Delay.
• The menu library is the global Clover and uses PascalCase methods such as Clover:CreateWindow and Window:AddTab (see ui).

Printing and the log

Output goes to one log (newest 4096 lines), shown in Output and Console and readable through the MCP server.

Arguments are converted with tostring. clover.error only logs; use error to stop code. For toasts use notify (see Globals).

The console does not show the severity. It colors a line red when its text contains error and amber when it contains warn.

Errors

Errors never escape the VM. Where an error is raised decides how it is reported and what survives it:

Console lines carry the [vm] or [lua] prefix in front of these texts. The MCP lua_execute tool also returns the error of its own chunk with a full traceback.

Error codes

Reports are written as [clover error N]: message with severity error and source vm.

Time and memory limits

• No execution time limit. A script may run as long as it likes. A loop that never yields freezes the VM (no callbacks, tasks or draws) until you press Reset VM or turn the master switch off.
• Always interruptible. An instruction-count hook runs every 1000 VM instructions, and long string pattern matches check periodically, so even while true do end stops on a reset. A C function that is blocked in the middle of a call, such as an HTTP request, finishes first.
• Bounded MCP waits. lua_execute waits 100 to 120000 ms (10000 by default) for its chunk. When the wait runs out it reports a timeout, but the script keeps running until it finishes or the VM is reset.
• 1 GB of Lua memory. The VM's allocator refuses to grow past 1 GB in total, and the allocation then fails with Lua's not enough memory error. The MCP lua_status tool reports the current usage.

The other caps (draw commands, file sizes, listings) are listed under Sandbox & Safety.

What's removed from standard Lua, what the unsafe API unlocks, and how files are confined.

local ok, result = pcall(HttpGet, "https://example.com")
if ok then
    print("downloaded", #result, "bytes")
else
    warn(result)
end

Standard libraries

The VM opens a fixed set of Lua 5.4 libraries and then removes or replaces the parts that could reach outside the sandbox.

Loading code

load and loadstring are the same function. They only compile Lua source text: precompiled bytecode and the standard reader-function form are rejected.

load(source, [chunkname], [mode], [env])

Compiles source as a Lua chunk and returns it as a function without running it. A leading UTF-8 byte order mark is skipped.

Parameters:

• source: string - Lua source text. Passing a function, as standard Lua allows, raises an argument error.
• chunkname: string (optional, default "script") - Name used in error messages. As in standard Lua, a name starting with = or @ is shown as written, anything else as [string "..."].
• mode: string (optional, default "t") - Must be exactly "t". Any other value, including "b" and "bt", makes the call return nil and Only text Lua chunks are allowed.
• env: table (optional) - When this argument is present it becomes the chunk's _ENV. Passing an explicit nil therefore gives the chunk no environment at all.

Returns:

• chunk: function? - The compiled chunk, or nil if compiling failed.
• message: string? - The syntax error message when chunk is nil.

Aliases: loadstring

local chunk, problem = loadstring("return 6 * 7", "=calc")
if chunk then
    print(chunk())
else
    warn(problem)
end

local scoped = load("print(answer)", "=scoped", "t", {print = print, answer = 42})
scoped()

The os subset

os is rebuilt as a new table that holds only four standard functions. os.exit, os.execute, os.getenv, os.remove, os.rename, os.tmpname and os.setlocale do not exist.

Allow unsafe Lua API

Enable it in Settings > Lua VM > Allow unsafe Lua API and confirm the dialog. The MCP server can also change it without a dialog.

Every change resets the VM, because the set of opened libraries is fixed when a VM is built. The log then shows Unsafe Lua APIs enabled. Files remain confined to the Clover workspace. or Unsafe Lua APIs disabled; running scripts are being reset.

Workspace file sandbox

All file access is confined to C:\clover\workspace\. This covers the file table, the global file functions, loadfile, dofile, configs and the MCP workspace_* tools. Rules:

• Paths are relative to the workspace. Separate folders with / or \, for example configs/main.cfg.
• Absolute and drive paths such as C:\x, C:x, /x or \\server\share are refused, and so are . and .. components.
• A path component may not be empty, end with a dot or a space, contain : < > " | ? * or a control character, or be a reserved Windows device name (CON, PRN, AUX, NUL, CONIN$, CONOUT$, CLOCK$, COM0 to COM9, LPT0 to LPT9), with or without an extension.
• Paths must be valid UTF-8, contain no NUL byte and be at most 4096 bytes long. An empty path is refused, except that listing an empty path lists the workspace root.
• Symbolic links, junctions and other reparse points are refused anywhere along the path, files with more than one hard link are refused, and only regular disk files can be opened. The folders along the path are held open while an operation runs, so they cannot be swapped for a link half-way through.
• Reads and writes are limited to 16 MB (16777216 bytes) per file, and appendfile refuses to grow a file past that size.
• Writing creates missing parent folders and replaces the whole file.
• Deleting works on files only; folders cannot be deleted.
• Listing returns at most 10000 names and skips links and names that break the rules above.
• The global file functions and the MCP workspace_list tool ignore trailing slashes. The file.* functions and the other MCP workspace tools do not, so file.read("notes/") is refused.

How a refusal is reported depends on the function. readfile, writefile, appendfile, makefolder, delfile and listfiles raise an error, while isfile, isfolder and the file.* functions return false or nil instead. See file for each function.

Limits

Stopping scripts

Scripts can't hang clover: the VM runs on its own thread and a hook checks every 1000 instructions. A reset or the master switch interrupts running code. See Core Concepts.

Which Lua 5.4 libraries are loaded, and the Roblox-style helpers clover adds to table, math and string.

Loaded libraries

table extensions

Each function is only installed when the name is not already defined.

table.find(t, value, [init])

Linear search of the array part of t for value using ==.

Parameters:

• t: table - Array to search.
• value: any - Value to look for.
• init: integer (optional, default 1) - Index to start from.

Returns:

• integer? - Index of the first match, or nil.

local names = {"Head", "Torso", "HumanoidRootPart"}
print(table.find(names, "Torso"))

table.clone(t)

Shallow copy of every key and value in t. The copy keeps the original metatable.

Parameters:

• t: table - Table to copy.

Returns:

• table - The new table.

table.clear(t)

Removes every key from t in place.

Parameters:

• t: table - Table to empty.

table.create(count, [value])

Creates an array of count copies of value. When value is nil the result is an empty table.

Parameters:

• count: integer - Number of slots to fill.
• value: any (optional) - Value stored in every slot.

Returns:

• table

table.getn(t)

Returns #t.

Parameters:

• t: table

Returns:

• integer

table.foreach(t, callback)

Calls callback(key, value) for every pair. Stops early and returns the callback's result as soon as it returns a non-nil value.

Parameters:

• t: table
• callback: function - Receives (key, value).

Returns:

• any - The first non-nil callback result, or nothing.

table.foreachi(t, callback)

Like table.foreach, but walks indices 1 to #t in order and calls callback(index, value).

Parameters:

• t: table
• callback: function - Receives (index, value).

Returns:

• any - The first non-nil callback result, or nothing.

math extensions

math.clamp(value, low, high)

Returns low when value < low, high when value > high, otherwise value.

Parameters:

• value: number
• low: number
• high: number

Returns:

• number

math.sign(value)

Returns 1, -1 or 0.

Parameters:

• value: number

Returns:

• integer

math.round(value)

Rounds half away from zero, so 2.5 becomes 3 and -2.5 becomes -3.

Parameters:

• value: number

Returns:

• number

string extensions

string.split(text, [separator])

Splits text on a plain (non-pattern) separator. An empty separator splits into single characters. Consecutive separators produce empty strings.

Parameters:

• text: string
• separator: string (optional, default ",") - Plain text to split on.

Returns:

• {string} - The pieces, in order.

Aliases: text:split(separator)

for _, part in ipairs(("a,b,,c"):split(",")) do
    print(part)
end

Extra globals

Random

A Roblox-style random number generator built on a 64-bit xorshift. Every Random object keeps its own state, so two objects created with the same seed produce the same sequence.

local rng = Random.new(1234)
print(rng:NextInteger(1, 6))
print(rng:NextNumber())
print(rng:NextNumber(10, 20))
local deck = rng:Shuffle({1, 2, 3, 4, 5})
print(table.concat(deck, " "))

Random.new([seed])

Creates a generator. Without a seed it mixes os.time, os.clock and an internal counter, so two calls in the same frame still differ. Non-integer seeds are floored.

Parameters:

• seed: number (optional) - Seed value.

Returns:

• Random

Random:NextNumber([low], [high])

With no arguments, returns a float in [0, 1). With both arguments, returns low + u * (high - low).

Parameters:

• low: number (optional)
• high: number (optional) - Required when low is given.

Returns:

• number

Random:NextInteger(low, high)

Returns an integer from low to high, both inclusive.

Parameters:

• low: integer
• high: integer

Returns:

• integer

Random:NextUnitVector()

Returns a random direction of length 1.

Returns:

• Vector3

Random:Shuffle(list)

Shuffles the array in place (Fisher-Yates) and returns the same table.

Parameters:

• list: table

Returns:

• table - The same table, shuffled.

Random:Clone()

Returns a new generator with the same current state.

Returns:

• Random

Open the Lua VM window, run your first script and find the workspace folder your scripts can read and write.

Running your first script

1. Open the Lua VM

   In the clover menu, go to Settings and find the Lua VM card. Click Open Lua VM (it reads Focus Lua VM when the window is already open).

2. Write some code

   The window opens with a tab named untitled.lua that already contains a hello-world line. The editor autocompletes globals and API names as you type.

   luaCopy

   print("hello from clover")
   notify("clover is running")

3. Run it

   Click Run or press Ctrl+Enter. The script is queued and runs on the VM thread on its next tick. Its print output and any error show up in the Output panel under the editor and in the Console tab of the side panel.

4. Keep it running

   A script ends when its main chunk returns, but anything it registered keeps running: render callbacks, task timers and signal connections. See Core Concepts.

   luaCopy

   local frames = 0
   local white = { R = 1, G = 1, B = 1, A = 1 }
   cheat.register("onDraw", function()
       frames = frames + 1
       draw.Text(20, 20, "frames: " .. frames, white)
   end)

The Lua VM window

The workspace folder

Scripts can only touch files inside C:\clover\workspace\. clover creates the folder on first use. Every path you pass to file functions and to readfile, writefile, listfiles, loadfile and dofile is relative to it.

writefile("notes/hello.txt", "saved at " .. os.date())
print(readfile("notes/hello.txt"))
for _, name in ipairs(listfiles("notes")) do
    print(name)
end

Unsafe API

Allow unsafe Lua API in the same card unlocks HTTP, WebSockets and the clipboard. Enabling it resets the VM. Only use it for scripts you trust. See Sandbox & Safety.

Limits

• The VM may use up to 1 GB of Lua memory. Allocations past that fail with a Lua memory error.
• Scripts are text only. Precompiled bytecode is rejected.
• An infinite loop without task.wait blocks the VM. Press Reset VM to stop it.

Next steps

Hotkeys, held keys and bound actions.

Step by step

1. Listen for a key press

   UserInputService.InputBegan passes an input object and false. Compare input.KeyCode with an Enum.KeyCode item. Mouse buttons arrive with KeyCode.Unknown and a UserInputType of MouseButton1, MouseButton2 or MouseButton3.

   luaCopy

   UserInputService.InputBegan:Connect(function(input)
       if input.KeyCode == Enum.KeyCode.F then
           print("F pressed at", input.Position.X, input.Position.Y)
       elseif input.UserInputType == Enum.UserInputType.MouseButton2 then
           print("right click")
       end
   end)

2. Toggle a feature with a hotkey

   Keep the state in a local and flip it on each press. notify shows a toast in the clover menu; its second argument is "success", "warning" or "error".

   luaCopy

   local enabled = false
   
   UserInputService.InputBegan:Connect(function(input)
       if input.KeyCode ~= Enum.KeyCode.Insert then
           return
       end
       enabled = not enabled
       notify(enabled and "Feature on" or "Feature off", enabled and "success" or "warning")
   end)

3. Hold a key

   Pair InputBegan with InputEnded, or poll UserInputService:IsKeyDown every tick. IsKeyDown returns false whenever Roblox is not focused.

   luaCopy

   local holding = false
   
   UserInputService.InputBegan:Connect(function(input)
       if input.KeyCode == Enum.KeyCode.LeftAlt then
           holding = true
       end
   end)
   
   UserInputService.InputEnded:Connect(function(input)
       if input.KeyCode == Enum.KeyCode.LeftAlt then
           holding = false
       end
   end)
   
   RunService.Heartbeat:Connect(function()
       if UserInputService:IsKeyDown(Enum.KeyCode.LeftShift) then
           print("shift is down")
       end
   end)

4. Bind an action to several inputs

   ContextActionService:BindAction calls your function with the action name, the input state and the input object, for every listed KeyCode or UserInputType. Binding the same name again replaces the old binding. It is not a global; get it with game:GetService.

   luaCopy

   local ContextActionService = game:GetService("ContextActionService")
   
   ContextActionService:BindAction("Dash", function(name, state, input)
       if state == Enum.UserInputState.Begin then
           print(name, "via", tostring(input.KeyCode))
       end
   end, false, Enum.KeyCode.Q, Enum.UserInputType.MouseButton3)

5. Clean up

   Connect returns a connection. Call Disconnect when you no longer need it, and UnbindAction for bound actions. A Reset VM removes everything at once.

   luaCopy

   local connection = UserInputService.InputBegan:Connect(function(input)
       print(input.KeyCode.Name)
   end)
   
   task.delay(10, function()
       connection:Disconnect()
       game:GetService("ContextActionService"):UnbindAction("Dash")
       print("stopped listening")
   end)

Full example

Press Insert to turn a crosshair on and off, and hold Right mouse to make it bigger.

local enabled = true
local aiming = false
local color = { R = 1, G = 0.8, B = 0.2, A = 1 }

UserInputService.InputBegan:Connect(function(input)
    if input.KeyCode == Enum.KeyCode.Insert then
        enabled = not enabled
        notify(enabled and "Crosshair on" or "Crosshair off")
    elseif input.UserInputType == Enum.UserInputType.MouseButton2 then
        aiming = true
    end
end)

UserInputService.InputEnded:Connect(function(input)
    if input.UserInputType == Enum.UserInputType.MouseButton2 then
        aiming = false
    end
end)

cheat.register("onDraw", function()
    if not enabled then
        return
    end
    local w, h = clover.screen_size()
    if w == 0 then
        return
    end
    local size = aiming and 14 or 6
    draw.Line(w / 2 - size, h / 2, w / 2 + size, h / 2, color, 2)
    draw.Line(w / 2, h / 2 - size, w / 2, h / 2 + size, color, 2)
end)

Things to know

• Running a script twice connects its handlers twice. Press Reset VM before re-running.
• An error inside a signal handler is logged and that handler is disconnected, so it never runs again. Wrap risky code in pcall if the handler must survive.
• InputChanged, TextBoxFocused and the window focus signals exist but never fire.
• For keybinds the user can change in a menu, use AddKeybind from the ui library instead.

Related

Build a crosshair settings window with toggles, sliders, a dropdown, a keybind, a color picker and configs.

Step by step

1. Keep the settings in one table

   Element callbacks write into this table and the render callback reads from it, so the two never have to know about each other. Colors are plain { R, G, B } tables from 0 to 1, which is exactly what draw expects.

   luaCopy

   local settings = {
       enabled = true,
       visible = true,
       size = 8,
       thickness = 2,
       style = "Cross",
       color = { R = 1, G = 0.8, B = 0.2 },
   }

2. Create the window, a tab and a section

   Size must be a plain table such as { X = 420, Y = 380 }. A Vector2 is userdata and is ignored, so the window would fall back to 580 by 460.

   luaCopy

   local Window = Clover:CreateWindow({
       Title = "Crosshair",
       SubTitle = "clover docs example",
       Size = { X = 420, Y = 380 },
   })
   local Main = Window:AddTab({ Title = "Main" })
   local Look = Main:AddSection("Look")

3. Add a toggle and two sliders

   Every element takes one options table. Give it an Id so SaveConfig can store it. Callback runs on the script thread after the user changes the value. Rounding is the number of decimals the slider keeps.

   luaCopy

   Look:AddToggle({
       Id = "CrosshairEnabled",
       Title = "Enabled",
       Default = settings.enabled,
       Callback = function(on)
           settings.enabled = on
       end,
   })
   
   Look:AddSlider({
       Id = "CrosshairSize",
       Title = "Size",
       Min = 2,
       Max = 30,
       Default = settings.size,
       Rounding = 0,
       Callback = function(value)
           settings.size = value
       end,
   })
   
   Look:AddSlider({
       Id = "CrosshairThickness",
       Title = "Thickness",
       Min = 1,
       Max = 6,
       Default = settings.thickness,
       Rounding = 1,
       Callback = function(value)
           settings.thickness = value
       end,
   })

4. Add a dropdown and a color picker

   A single-choice dropdown passes the chosen option string. The color picker passes a { R, G, B } table. Set the dropdown's Default to its first option: the handle's cached Value always starts at the first option, whatever Default says.

   luaCopy

   Look:AddDropdown({
       Id = "CrosshairStyle",
       Title = "Style",
       Options = { "Cross", "Dot", "Both" },
       Default = "Cross",
       Callback = function(choice)
           settings.style = choice
       end,
   })
   
   Look:AddColorpicker({
       Id = "CrosshairColor",
       Title = "Color",
       Default = settings.color,
       Callback = function(color)
           settings.color = color
       end,
   })

5. Add a keybind

   In the default Toggle mode the callback receives true or false every time the bound key is pressed. Use your own variable for the state; Keybind:GetState() only reports the latch in Always mode. Key names are A-Z, 0-9, F1-F12, Space, Enter, Insert, LeftShift, RightShift and similar.

   luaCopy

   local Binds = Main:AddSection("Binds")
   Binds:AddKeybind({
       Title = "Hide crosshair",
       Default = "X",
       Mode = "Toggle",
       Callback = function(toggled)
           settings.visible = not toggled
       end,
   })

6. Save and load configs

   SaveConfig writes every element with an Id to C:\clover\workspace\configs\<name>.cfg. LoadConfig sets the values back but does not call the callbacks, so copy the loaded values into your settings table yourself.

   luaCopy

   local Configs = Main:AddSection("Config")
   
   Configs:AddButton({
       Title = "Save",
       Callback = function()
           if Clover:SaveConfig("crosshair") then
               notify("Crosshair saved")
           end
       end,
   })
   
   Configs:AddButton({
       Title = "Load",
       Callback = function()
           if not Clover:LoadConfig("crosshair") then
               notify("No saved crosshair yet", "warning")
               return
           end
           local o = Clover.Options
           settings.enabled = o.CrosshairEnabled.Value
           settings.size = o.CrosshairSize.Value
           settings.thickness = o.CrosshairThickness.Value
           settings.style = o.CrosshairStyle.Value
           settings.color = o.CrosshairColor.Value
       end,
   })

7. Draw from the settings

   The render callback runs every pass and only reads the settings table. clover.screen_size returns 0, 0 until the game view is known, so skip drawing until then.

   luaCopy

   cheat.register("onDraw", function()
       if not settings.enabled or not settings.visible then
           return
       end
       local w, h = clover.screen_size()
       if w == 0 then
           return
       end
       local cx, cy = w / 2, h / 2
       local s = settings.size
       if settings.style ~= "Dot" then
           draw.Line(cx - s, cy, cx + s, cy, settings.color, settings.thickness)
           draw.Line(cx, cy - s, cx, cy + s, settings.color, settings.thickness)
       end
       if settings.style ~= "Cross" then
           draw.CircleFilled(cx, cy, settings.thickness + 1, settings.color, 16)
       end
   end)

Things to know

• Element callbacks run on the script thread during its next pass and cannot yield. Wrap slow work in task.spawn.
• SetValue and LoadConfig never fire Callback. Toggles, sliders and inputs move on screen; dropdowns, keybinds and color pickers only update their cached Value.
• While a script window exists the overlay takes the mouse and keyboard. Call Window:Destroy() or Clover:Destroy() to give them back to the game.
• Errors inside callbacks are caught and logged as ui callback: ... warnings instead of stopping the script.

Where to go next

Let AI agents on your PC run Lua, edit script tabs, browse the game and read memory.

Starting the server

1. Open the MCP panel

   Open the Lua VM window and pick MCP in the side panel.

2. Start it

   Click Start server and confirm. clover listens on 127.0.0.1 on a random free port and logs MCP server listening on 127.0.0.1:<port> to the console. A new random token is made every time the server starts.

3. Connect your agent

   Use Copy config for clients that read an mcpServers JSON block, or Copy command for Claude Code. Copy URL and Copy token copy the two parts on their own.

4. Stop it

   Click Stop server. Open connections are closed and the token stops working.

{
  "mcpServers": {
    "clover": {
      "type": "http",
      "url": "http://127.0.0.1:<port>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

claude mcp add --transport http clover http://127.0.0.1:<port>/mcp --header "Authorization: Bearer <token>"

Connection rules

Tools

Lua VM

Editor

Workspace

Game and memory

Remote spy

Every global name and where it's documented, plus the small global functions.

local name, version = identifyexecutor()
print("executor:", name, version)
print("place:", clover.getplaceid(), clover.getgamename())
print(typeof(Vector3.new(1, 2, 3)), typeof(game), typeof({}))

getgenv().TourRuns = (getgenv().TourRuns or 0) + 1
notify("Tour ran " .. TourRuns .. " time(s)", "success")
clover.warn("clover.warn joins", "with spaces")

Global index

Names are grouped by origin. Each row links to the page that documents it.

Lua standard library

Roblox-style API

clover namespaces

Executor-style functions

Names that are not globals

• Library is a local inside the UI prelude. Use the global Clover (local Library = Clover). See ui.
• getgamename and getplaceid exist only as clover.getgamename and clover.getplaceid.
• The memory functions exist only on the clover table (clover.memory_read, clover.read_int, ...). See memory.
• setclipboard and toclipboard are not globals. Use utility.SetClipboard or clover.setclipboard. See utility.
• ContextActionService and StarterGui are only returned by game:GetService. See services.

Functions

print(...)

Converts every argument with tostring rules (so __tostring and __name apply), joins them with a tab and writes one line to the clover log at info level. It replaces Lua's built-in print.

Parameters:

• ...: any - Values to print. With no arguments an empty line is logged.

• The global print tags lines as vm; clover.print tags them as lua.
• printconsole is the same function. See compat.
• The log keeps the most recent 4096 entries.

print("health", 100, true)
print(Vector3.new(1, 2, 3))

warn(...)

Same as print but logs at warning severity. It replaces Lua 5.4's warn: control messages such as "@on" and "@off" are not special and are logged like any other text.

Parameters:

• ...: any - Values to log, joined with a tab.

local camera = workspace and workspace.CurrentCamera
if not camera then
    warn("no camera yet")
end

notify(text, [status])

Shows a toast notification in the clover overlay, titled "Clover", with text as the message. Returns nothing.

Parameters:

• text: string - The message. Numbers are converted to strings; other types raise an error.
• status: string (optional, default "success") - "success", "warning" or "error" picks the style. Any other value shows a success notification.

Aliases: clover.notify

• Clover:Notify and StarterGui:SetCore("SendNotification", ...) both end up calling this function.

notify("ESP enabled")
notify("Target lost", "warning")

identifyexecutor()

Returns the executor name and version.

Returns:

• name: string - Always "clover".
• version: string - Always "1.0".

• getexecutorname returns only the name.

local name, version = identifyexecutor()
print(name, version)

getgenv()

Returns the shared global table, the same as _G.

Returns:

• table - The global table.

Aliases: clover.getgenv

• There is no separate game environment; getrenv does not exist.
• Values survive between script runs and are cleared only when the VM resets.

if getgenv().MyEspLoaded then
    print("already running")
    return
end
getgenv().MyEspLoaded = true
print(MyEspLoaded, getgenv() == _G)

typeof(value)

Like type, but engine userdata report their type name, such as Vector3.

Parameters:

• value: any - The value to inspect. It is required: typeof() with no argument raises an error, while typeof(nil) returns "nil".

Returns:

• string - The type name. See the table below.

Aliases: clover.typeof

print(typeof(Vector3.new()), typeof(Color3.new(1, 0, 0)), typeof(workspace))
print(typeof(42), typeof("x"), typeof(newproxy(true)))

tick()

Returns the current Unix time (seconds since 1970-01-01 UTC) from the system clock, as a float with sub-second precision.

Returns:

• number - Seconds since the Unix epoch.

Aliases: clover.tick

• time() returns seconds since the VM started instead. See stdlib.

local started = tick()
task.wait(1)
print(string.format("waited %.2f s", tick() - started))

newproxy([base])

Creates an empty userdata (zero bytes, no user values). Useful as a unique key or as an object whose behaviour comes entirely from its metatable.

Parameters:

• base: any (optional) - A userdata copies its metatable, true gives a new empty metatable, and nil/false gives none.

Returns:

• userdata - The new proxy. Read its metatable with getmetatable.

local proxy = newproxy(true)
local mt = getmetatable(proxy)
mt.__tostring = function() return "my proxy" end
mt.__index = function(_, key) return key .. "!" end
print(tostring(proxy), proxy.hello, typeof(proxy))

clover-only functions

These live only on the clover table. The clover logging functions differ from the globals of the same name: they join arguments with a single space and tag lines as script output (lua).

clover.print(...)

Converts the arguments with tostring rules, joins them with a single space and writes one info line to the clover log.

Parameters:

• ...: any - Values to log.

Aliases: clover.printl

clover.print("loaded", 3, "modules")

clover.warn(...)

Like clover.print but logs at warning severity.

Parameters:

• ...: any - Values to log.

clover.warn("config missing, using defaults")

clover.error(...)

Like clover.print but logs at error severity. It does not raise an error and the script keeps running.

Parameters:

• ...: any - Values to log.

Aliases: clover.errorl

local ok, problem = pcall(function() error("boom") end)
if not ok then
    clover.error("caught:", problem)
end
print("still running")

clover.getgamename()

Returns the Name of the current DataModel, the same text game.Name gives.

Returns:

• string - The name, or an empty string when Roblox is not attached or no DataModel is found.

local name = clover.getgamename()
if name ~= "" then
    print("in", name)
end

clover.getplaceid()

Returns the PlaceId of the current game, read from the DataModel. game.PlaceId reads the same field.

Returns:

• integer - The PlaceId, or 0 when Roblox is not attached or no DataModel is found.

local placeId = clover.getplaceid()
if placeId == 0 then
    print("not in a game yet")
else
    print("place", placeId)
end

The clover table

clover holds the raw engine functions. draw, utility, keyboard, mouse, cheat and file are built from it. clover.ui is the low-level UI table.

The Clover global

The UI prelude stores its library table in _G.Clover. It is the entry point for menus; see ui for the full API. Its top-level fields:

Handles to the Roblox DataModel and Workspace, plus GetService and IsLoaded.

if not game then
    warn("Roblox is not loaded yet")
    return
end

local Players = game:GetService("Players")
print("place", game.PlaceId, "universe", game.GameId, "server", game.JobId)
print("players online:", #Players:GetPlayers())

local me = Players.LocalPlayer
if me then
    print("playing as", me.Name, me.UserId)
end

Players.PlayerAdded:Connect(function(player)
    print(player.Name .. " joined")
end)

Players.PlayerRemoving:Connect(function(player)
    print(player.Name .. " left")
end)

Globals

game

The DataModel as an Instance, or nil when no game is loaded. Updated automatically when the game changes.

• game:GetFullName() returns an empty string, because full names stop at the DataModel.
• Assigning your own value to the global game works until the DataModel address changes, then the engine overwrites it.

workspace

The Workspace as an Instance, or nil. Updated together with game.

• There is no capitalised Workspace global; use workspace, game.Workspace or game:GetService("Workspace").

DataModel methods

game:GetService(name)

Returns a service by name, checking three sources in order (see the table below): the engine's Lua shim tables, the global service tables, then the children of the instance it is called on.

Parameters:

• name: string - Service name. Numbers are converted to strings; any other type raises an error.

Returns:

• Instance | table | nil - The service Instance, one of the Lua service tables, or nil when nothing matches. It never raises an error for an unknown name.

• GetService is registered on every Instance. On anything other than game, step 3 searches that instance's own children.
• Services are not created on demand. A service that is not a child of the DataModel resolves to nil.

local Players = game:GetService("Players")
local Lighting = game:GetService("Lighting")
local RunService = game:GetService("RunService")

if Lighting then
    RunService.Heartbeat:Connect(function()
        Lighting.ClockTime = 12
    end)
end
print(#Players:GetPlayers(), "players")

game:IsLoaded()

Returns true when the engine currently resolves a DataModel in the Roblox process, false otherwise.

Returns:

• boolean - Whether a DataModel address is available right now.

• It ignores the instance it is called on and does not wait for the place to finish loading. It only reports whether the DataModel pointer resolves.
• Registered on every Instance, so workspace:IsLoaded() gives the same answer.

game:HttpGet(url)

Same as the global HttpGet. Returns the response body.

Parameters:

• url: string - Full http or https URL.

Returns:

• string - The response body for a 2xx status.

Aliases: game:HttpGetAsync(url), HttpGet(url)

• Raises HTTP access requires Allow unsafe Lua API. when the unsafe API toggle is off (see Sandbox).
• Raises HttpGet failed: HTTP <status> for a non-2xx status and HttpGet failed: <reason> when the request itself fails.
• The request runs synchronously on the script thread. See http for limits and the other request functions.

DataModel properties

game.PlaceId

The current place id, read as a 64-bit integer from the DataModel.

Returns:

• integer - Place id.

game.GameId

The universe (experience) id, read as a 64-bit integer from the DataModel.

Returns:

• integer - Universe id.

game.JobId

The server job id string, or an empty string when its pointer is not readable.

Returns:

• string - Job id.

game.Workspace

The Workspace Instance, resolved the same way as the workspace global, or nil.

Returns:

• Instance | nil - Workspace.

Aliases: game.workspace

game.Loaded

Compatibility stand-in: the game counts as already loaded, so Connect and Once run the callback right away and Wait returns immediately.

• This is a plain Lua table, not an engine signal; it has no Fire method.

if not game:IsLoaded() then
    game.Loaded:Wait()
end
print("ready in place", game.PlaceId)

Players service

game:GetService("Players") returns the real Players Instance. These members are available when the instance's ClassName is exactly Players. For a lighter, pre-read list of players with positions and health, see players.

Players.LocalPlayer

The local Player Instance, or nil when its pointer is not valid (for example while joining).

Returns:

• Instance | nil - The local Player.

Players:GetPlayers()

Returns an array of the instance's children whose ClassName is Player, in child order.

Returns:

• {Instance} - Array of Player instances. Empty when there are none.

• Call it on the Players service. game:GetPlayers() returns an empty table.

for _, player in ipairs(game:GetService("Players"):GetPlayers()) do
    local character = player.Character
    print(player.Name, player.DisplayName, character ~= nil)
end

Players.PlayerAdded

Fires with the new Player when someone joins. Players already in the server when the engine starts watching don't fire.

Parameters:

• player: Instance - Passed to the callback: the Player that joined.

• The connection is not tied to one Players instance: every PlayerAdded connection receives every join.
• Returns an engine signal with Connect, Once, Wait and Fire.

Players.PlayerRemoving

Fires with the Player Instance when a previously seen player is no longer a child of the Players service. It is detected after the player is gone, so properties read from it may already be empty.

Parameters:

• player: Instance - Passed to the callback: the Player that left.

• Like PlayerAdded, every connection receives every leave. Returns an engine signal.

Player instances also have Character, CharacterAdded, DisplayName, UserId and Team; see Instance class properties and Player.CharacterAdded.

Workspace properties

workspace.CurrentCamera

The current Camera Instance, or nil. Available when the instance's ClassName is exactly Workspace.

Returns:

• Instance | nil - The Camera. Its FieldOfView is readable and writable (see Instance).

workspace.DistributedGameTime

Seconds of game time since the server started, read as a double.

Returns:

• number - Game time in seconds.

clover helpers

clover.getgamename()

Returns the DataModel's Name without going through the game global.

Returns:

• string - The DataModel name, or an empty string when there is no DataModel or the name is empty.

• Only available on the clover table; there is no global getgamename.

clover.getplaceid()

Returns the current place id without going through the game global.

Returns:

• integer - The place id, or 0 when there is no DataModel.

• Only available on the clover table; there is no global getplaceid.

A handle to a live Roblox object: reading a property reads game memory.

local player = game:GetService("Players").LocalPlayer
local character = player and player.Character
if not character then
    return
end

local humanoid = character:FindFirstChildOfClass("Humanoid")
local root = character:FindFirstChild("HumanoidRootPart")
if humanoid and root then
    print(root:GetFullName(), humanoid.Health, root.Position)
    humanoid.WalkSpeed = 24
end

for _, child in ipairs(character:GetChildren()) do
    if child:IsA("BasePart") then
        child.Transparency = 0.5
    end
end

character.ChildAdded:Connect(function(child)
    print("added", child.Name, child.ClassName)
end)

Constructor

Instance.new(className, [parent])

Creates a real object in Roblox, such as a Part or Folder, and returns it.

Parameters:

• className: string - Exact class name, case-sensitive.
• parent: Instance (optional, default nil) - Parent to set after creation. Must be an Instance or nil.

Returns:

• Instance - The new object.

• Failure raises Instance.new failed (<code>); the codes are listed below.
• Fails with code 2 on unsupported Roblox builds.
• If setting parent fails (code 12) the object has already been created but no handle is returned.
• Name cannot be written, so new objects keep their default name.

local ok, part = pcall(Instance.new, "Part", workspace)
if ok then
    part.Anchored = true
    part.Size = Vector3.new(4, 1, 4)
    part.Position = Vector3.new(0, 50, 0)
    part.Color = Color3.fromRGB(255, 120, 200)
else
    warn(part)
end

Properties

Instance.Name

The object's name.

Returns:

• string - The name, or an empty string when it cannot be read. Names longer than 255 bytes also read as an empty string.

• Writing Name is ignored.

Instance.ClassName

The object's class name, read from its class descriptor.

Returns:

• string - The class name, or an empty string when it cannot be read.

Instance.Address

The object's memory address. Use it as a table key or with the memory functions.

Returns:

• integer - The raw address.

local seen = {}
for _, child in ipairs(workspace:GetChildren()) do
    seen[child.Address] = child.Name
end

Instance.Parent

The parent Instance, or nil when the parent pointer is not valid. Writing it reparents the object by calling the game's own SetParent function.

Returns:

• Instance | nil - The parent.

• Assign an Instance or nil. Any other type raises an error. inst.Parent = nil takes the object out of the tree; there is no Destroy method.
• A failed reparent is silent.
• The script thread waits for the engine call, up to 3 seconds.

Class-specific properties

Only available when ClassName matches exactly. BasePart covers Part, MeshPart, UnionOperation, TrussPart, WedgePart, CornerWedgePart, SpawnLocation, Seat and VehicleSeat. Parts without physics read zeros and ignore writes.

Value on other value classes (CFrameValue, Color3Value, ...) is not supported and falls through to the child lookup.

Value conversion

• Floats stored by the game (Transparency, Health, Brightness, ...) read as Lua floats. Ids and integers (UserId, Address, IntValue.Value) read as Lua integers.
• Strings are read from game memory and are limited to 255 bytes; longer or unreadable strings read as "".
• number writes need a number or a numeric string. Anything else raises a number expected error.
• boolean writes use Lua truthiness: nil and false clear the value, anything else sets it.
• Vector3 writes accept a Vector3 or a table with X, Y, Z (or x, y, z) fields; missing fields count as 0. Other values are ignored.
• Color3 writes accept a Color3 or a table with R, G, B (or r, g, b) fields, each 0 to 1. Other values are ignored.
• CFrame writes accept a CFrame (position and rotation), or a Vector3 or table (position only).
• After a write the engine handles, it fires that property's GetPropertyChangedSignal connections. For Parent this only happens when the reparent succeeded.

Indexing rules

inst.key is resolved in this order, and the first match wins:

1. Methods on the Instance metatable (GetChildren, FindFirstChild, ...).
2. If the stored address is not a plausible pointer, every other key reads nil.
3. Name, ClassName, Address, Parent, ChildAdded, ChildRemoved, DescendantAdded.
4. The class-specific properties for the object's ClassName.
5. The first direct child whose Name or ClassName equals the key. character.Humanoid therefore also finds a renamed Humanoid when no child is literally named Humanoid before it.

Methods

Instance:GetChildren()

Returns the direct children in the game's own child order. Each call builds a new table of new handles.

Returns:

• {Instance} - Array of children. Empty when there are none or the address is not valid.

• As a safety limit, an object with more than 10,000 children reports none at all.

Instance:GetDescendants()

Returns every descendant, depth first: each child is followed by its own descendants before the next sibling.

Returns:

• {Instance} - Array of descendants, capped at 50,000 entries.

• Walking a large tree such as game or workspace reads a lot of memory in one call. Prefer FindFirstChild chains or a narrower root when you can.

local count = 0
for _, item in ipairs(workspace:GetDescendants()) do
    if item:IsA("BasePart") then
        count = count + 1
    end
end
print(count, "parts in workspace")

Instance:FindFirstChild(name)

Returns the first direct child whose Name or ClassName equals name exactly (case-sensitive), or nil.

Parameters:

• name: string - Name (or class name) to look for.

Returns:

• Instance | nil - The first match.

• Only direct children are searched. A second recursive argument is accepted but ignored; loop over GetDescendants() for a deep search.
• Matching ClassName as well as Name differs from Roblox: FindFirstChild("Humanoid") also returns a Humanoid that was renamed.

Instance:FindFirstChildOfClass(className)

Returns the first direct child whose ClassName equals className exactly, or nil. Inheritance is not considered, and names are not matched.

Parameters:

• className: string - Exact class name.

Returns:

• Instance | nil - The first child of that class.

Instance:FindFirstChildWhichIsA(className)

Returns the first direct child whose Name equals className or whose class passes IsA(className), or nil.

Parameters:

• className: string - A class name or one of the class groups.

Returns:

• Instance | nil - The first match.

local player = game:GetService("Players").LocalPlayer
local character = player and player.Character
local part = character and character:FindFirstChildWhichIsA("BasePart")
print(part and part.Name)

Instance:WaitForChild(name, [timeout])

Returns the child, waiting (checking every 0.05 s) until it appears or timeout runs out.

Parameters:

• name: string - Name (or class name) to wait for. The same Name-or-ClassName match as FindFirstChild.
• timeout: number (optional, default 5) - Seconds to wait. Negative values count as 0. With 0 a missing child returns nil right away without yielding.

Returns:

• Instance | nil - The child, or nil on timeout. A timeout raises no error and logs no warning.

• The timeout is counted in 0.05 second steps per check, so the real wait can run slightly longer than timeout.
• Can't yield inside engine callbacks; call it from the script body or task.spawn.

local player = game:GetService("Players").LocalPlayer
local gui = player:WaitForChild("PlayerGui", 10)
if gui then
    print(gui:GetFullName())
else
    warn("PlayerGui did not appear")
end

Instance:IsA(className)

Returns true when the object's ClassName equals className, when className is "Instance", or when className is a class group (table below) that contains the object's ClassName.

Parameters:

• className: string - Class name or group name.

Returns:

• boolean - Whether the object counts as that class.

• There is no full class tree; unlisted abstract names only match an exact ClassName.

IsA class groups

Instance:IsDescendantOf(ancestor)

Walks up the parent chain (at most 64 levels) and returns true if ancestor is one of the parents. An object is not a descendant of itself.

Parameters:

• ancestor: Instance - The possible ancestor. Any non-Instance value returns false instead of raising an error.

Returns:

• boolean - Whether ancestor is above this object.

Instance:GetFullName()

Returns the dot-separated path from the topmost ancestor below the DataModel down to this object, for example Workspace.Map.Door. The DataModel itself is never part of the path.

Returns:

• string - The path. game:GetFullName() returns an empty string.

• At most 64 levels are walked. For an object outside the DataModel the path starts at its topmost ancestor.

Instance:GetPropertyChangedSignal(property)

Returns a signal that fires when a clover script changes property on this object. Changes made by the game aren't seen.

Parameters:

• property: string - Property (or attribute) name, case-sensitive.

Returns:

• signal - Signal with Connect, Once, Wait and Fire. Callbacks receive no arguments.

• Read-only properties such as Name never fire, since writes to them are ignored.

local part = workspace:FindFirstChild("Baseplate")
if part then
    part:GetPropertyChangedSignal("Transparency"):Connect(function()
        print("Transparency is now", part.Transparency)
    end)
    part.Transparency = 0.5
end

Instance:Fire(...)

Fires a BindableEvent's Event or a ProximityPrompt's Triggered for your own connections only. The game doesn't see it.

Parameters:

• ...: any (optional) - Values passed to each callback.

• Any other class raises Fire: unsupported instance.
• To activate a real prompt in the game use fireproximityprompt (see Remotes).

local event = workspace:FindFirstChildOfClass("BindableEvent")
if event then
    event.Event:Connect(function(message)
        print("got", message)
    end)
    event:Fire("hello")
end

RemoteEvent:FireServer(...)

Sends a RemoteEvent to the server through the game's own networking code. The object's ClassName must be exactly RemoteEvent. See Remotes for the full rules and error list.

Parameters:

• ...: any (optional) - Up to 16 values: booleans, numbers, strings, Vector2, Vector3, Color3, CFrame or Instances. nil and tables are rejected.

Aliases: fireserver

• Problems raise an error that starts with FireServer: (wrong class, unsupported Roblox build, unsupported argument type, too many arguments).
• It does not yield: the script thread waits for the game to run the call, which takes at least 0.6 seconds for a successful send.

local storage = game:GetService("ReplicatedStorage")
local remote = storage and storage:FindFirstChild("SetTeam")
if remote and remote:IsA("RemoteEvent") then
    local ok, err = pcall(function()
        remote:FireServer("Red", 1)
    end)
    if not ok then
        warn(err)
    end
end

RemoteFunction:InvokeServer(...)

Invokes the RemoteFunction and returns the server's reply. See Remotes.

Parameters:

• ...: any (optional) - Up to 16 arguments, same types as FireServer.

Returns:

• ... - The values the server returned. Booleans, numbers, strings, Vector2, Vector3, Color3, CFrame and Instances are converted; other types come back as nil.

Aliases: invokeserver

• Raises an error after 10 seconds without a reply, or when the server errors.

Methods documented elsewhere

No other methods exist. inst:Destroy(), inst:Clone() or inst:ClearAllChildren() fall through to the child lookup and fail with an attempt to call error.

Events

Every event is an engine signal with Connect, Once, Wait and Fire. Each access returns a new signal table, but connections are matched by event and object, so connecting through different accesses behaves the same.

Instance.ChildAdded

Fires with each new direct child. Watching starts the first time you read the signal.

Parameters:

• child: Instance - Passed to the callback: the new child.

Instance.ChildRemoved

Fires with a direct child that disappeared since the previous tick. The object may already be destroyed, so its properties can read as empty.

Parameters:

• child: Instance - Passed to the callback: the removed child.

Instance.DescendantAdded

Fires right after ChildAdded, with the same child. Despite the name it only sees direct children of the object; objects added deeper in the tree do not fire it.

Parameters:

• descendant: Instance - Passed to the callback: the new direct child.

Player.CharacterAdded

Fires with the new character model when a player's Character pointer changes to a different model. The engine checks every player once per tick, whether or not anything is connected.

Parameters:

• character: Instance - Passed to the callback: the new character model.

• Characters that already exist when the engine first scans the players do not fire. There is no CharacterRemoving.

local player = game:GetService("Players").LocalPlayer
player.CharacterAdded:Connect(function(character)
    print("respawned as", character:GetFullName())
end)

BindableEvent.Event

Fires only when a clover script calls :Fire(...), not when the game does.

Parameters:

• ...: any - Passed to the callback: the values given to Fire.

RemoteEvent.OnClientEvent

Exists for compatibility but never fires from the network; only from your own :Fire(...).

Parameters:

• ...: any - Passed to the callback: the values given to Fire.

ProximityPrompt.Triggered

Fires only when a clover script calls :Fire(...), not when a player uses the prompt.

Parameters:

• ...: any - Passed to the callback: the values given to Fire.

• To trigger the real prompt, or to call the game's own connections, use fireproximityprompt or firesignal (see Remotes).

Metamethods

Read game attributes on any Instance and attach your own.

local player = game:GetService("Players").LocalPlayer
if not player then
    return
end

print("Level from the game:", player:GetAttribute("Level"))

player:GetPropertyChangedSignal("Marked"):Connect(function()
    print("Marked is now", player:GetAttribute("Marked"))
end)
player:SetAttribute("Marked", true)

for name, value in pairs(player:GetAttributes()) do
    print(name, typeof(value), value)
end

Methods

Instance:GetAttribute(name)

Returns the script value stored under name if there is one, otherwise the game's attribute of that name.

Parameters:

• name: string - Attribute name, case-sensitive. Numbers are converted to strings; other types raise an error.

Returns:

• boolean | number | string | Vector3 | CFrame | nil - The value, or nil when neither layer has it, when the game attribute's type cannot be read, or when game attributes are unavailable on this build.

local part = workspace:FindFirstChild("Door")
if part then
    local locked = part:GetAttribute("Locked")
    print("locked:", locked == true)
end

Instance:SetAttribute(name, value)

Stores a script value on this object, or removes it when value is nil. Fires GetPropertyChangedSignal(name).

Parameters:

• name: string - Attribute name. An empty name does nothing (no value stored, no signal).
• value: boolean | number | string | Vector3 | CFrame | nil (optional, default nil) - The value. Other types raise SetAttribute: unsupported value type.

• Numbers and numeric strings are stored as floats: 5 reads back as 5.0.
• Removing a script value with nil does not remove the game's attribute; the game value shows through again.
• If the object's address is not a plausible pointer, the call does nothing.

local character = workspace:FindFirstChild("Enemy")
if character then
    character:SetAttribute("Target", true)
    character:SetAttribute("Seen", os.clock())
    character:SetAttribute("Target", nil)
end

Instance:GetAttributes()

Returns every attribute the engine can see on the object as a name = value table. Game attributes are added first, then script values, so a script value replaces a game value with the same name.

Returns:

• table - Map from attribute name to value. Empty when there are none. Game attributes whose type cannot be read are left out.

Value types

Values you can set

Writing into the game's copy overwrites the value bytes of the existing entry in place. The engine never adds attributes to the game, removes them, or changes their type.

Game attribute types the engine reads

Storage

• Script values live in a table inside the engine keyed by object address, so every handle to the same object sees them. They are never saved and are cleared when the VM resets. They are not removed when the game destroys the object, so a new object that reuses the same address can show them until the next reset.
• Game attributes are found through the object's component map. The attribute component holds its entries either as a flat array or as a hash table, with at most 4,096 entries.
• Every read checks the container's header, collects the entries, then reads the header again. If the game changed it in between (for example by adding an attribute), the result is thrown away and the call behaves as if the object had no game attributes: GetAttribute returns the script value or nil, and GetAttributes returns only script values. String values are verified the same way before they are returned.
• Each GetAttribute call scans the entries and compares names in game memory. Read values once and keep them in locals rather than calling it many times per frame.

Lua versions of RunService, UserInputService, TweenService, ContextActionService, StarterGui and HttpService.

local dot = Drawing.new("Circle")
dot.Radius = 6
dot.Filled = true
dot.Color = Color3.fromRGB(255, 200, 40)
dot.Position = Vector2.new(100, 100)

local info = TweenInfo.new(0.4, Enum.EasingStyle.Back, Enum.EasingDirection.Out)

RunService:BindToRenderStep("follow", Enum.RenderPriority.Last.Value, function(dt)
    if UserInputService:IsKeyDown(Enum.KeyCode.LeftShift) then
        dot.Position = UserInputService:GetMouseLocation()
    end
end)

UserInputService.InputBegan:Connect(function(input)
    if input.UserInputType == Enum.UserInputType.MouseButton1 then
        TweenService:Create(dot, info, {Radius = 18}):Play()
    elseif input.UserInputType == Enum.UserInputType.MouseButton2 then
        TweenService:Create(dot, info, {Radius = 6}):Play()
    end
end)

RunService

Heartbeat, RenderStepped and Stepped are one engine event (see Signals). It fires once per scheduler tick with the tick length dt in seconds and is not synchronized with Roblox frames. Handlers cannot yield.

RunService.Heartbeat

Fires once per scheduler tick, after sleeping threads, delays and tweens have been processed.

Parameters:

• dt: number - Seconds since the previous tick.

Aliases: RunService.PostSimulation

local frames = 0
RunService.Heartbeat:Connect(function(dt)
    frames = frames + 1
end)

RunService.RenderStepped

The same event as Heartbeat, under its render name.

Parameters:

• dt: number - Seconds since the previous tick.

Aliases: RunService.PreRender

RunService.Stepped

The same event as Heartbeat. Unlike Roblox, which passes (time, dt), handlers receive only dt.

Parameters:

• dt: number - Seconds since the previous tick.

Aliases: RunService.PreAnimation, RunService.PreSimulation

RunService:BindToRenderStep(name, priority, callback)

Connects callback to RenderStepped under name. Binding a name that is already bound disconnects the previous callback first.

Parameters:

• name: string - Key used to unbind or replace the binding.
• priority: number - Accepted for compatibility and ignored; bindings run in no particular order.
• callback: function - Called with dt every tick.

• The callback runs as a signal handler: it cannot yield, and an error disconnects it.
• If the callback errors, unbinding that name later can remove an unrelated connection.

local cursor = Drawing.new("Circle")
cursor.Radius = 4

RunService:BindToRenderStep("cursor", Enum.RenderPriority.Last.Value, function()
    cursor.Position = UserInputService:GetMouseLocation()
end)

task.wait(10)
RunService:UnbindFromRenderStep("cursor")
cursor:Remove()

RunService:UnbindFromRenderStep(name)

Disconnects the callback bound under name. Unknown names are ignored.

Parameters:

• name: string - Name given to BindToRenderStep.

The environment checks always return the same values:

UserInputService

Keyboard and mouse state comes from Windows key polling, not from Roblox. Key and button queries return false or an empty table while Roblox is not the foreground window. Only keys with a mapping in the KeyCode table are reported.

Events

UserInputService.InputBegan

Fires when a key or mouse button goes down while Roblox is focused.

Parameters:

• input: InputObject - See InputObject; UserInputState is Begin.
• gameProcessed: boolean - Always false.

UserInputService.InputBegan:Connect(function(input, gameProcessed)
    if input.KeyCode == Enum.KeyCode.Insert then
        print("toggle menu")
    end
end)

UserInputService.InputEnded

Fires when a key or button whose press was delivered by InputBegan is released, even if Roblox lost focus in between.

Parameters:

• input: InputObject - UserInputState is End.
• gameProcessed: boolean - Always false.

These Lua-side signals exist so scripts can connect to them, but the engine never fires them (see Lua-side signals):

Fields

Methods

UserInputService:IsKeyDown(keyCode)

Returns whether the key is held right now.

Parameters:

• keyCode: EnumItem - An Enum.KeyCode item.

Returns:

• boolean - false when Roblox is not the foreground window or the KeyCode has no key mapping.

if UserInputService:IsKeyDown(Enum.KeyCode.LeftControl) then
    print("ctrl is held")
end

UserInputService:IsMouseButtonPressed(inputType)

Returns whether a mouse button is held right now.

Parameters:

• inputType: EnumItem - Enum.UserInputType.MouseButton1, MouseButton2 or MouseButton3.

Returns:

• boolean - false for any other input type or when Roblox is not the foreground window.

UserInputService:GetMouseLocation()

Returns the cursor position in pixels, relative to the top-left corner of the foreground window's client area (normally Roblox).

Returns:

• Vector2

UserInputService:GetMouseDelta()

Returns how far the cursor moved, in pixels, since the previous call to GetMouseDelta from any script. The first call returns (0, 0).

Returns:

• Vector2

UserInputService:GetKeysPressed()

Returns one InputObject for every mapped keyboard key that is held, in no particular order, each with UserInputState Begin. Mouse buttons are not included.

Returns:

• {InputObject} - Empty when Roblox is not the foreground window.

UserInputService:GetMouseButtonsPressed()

Returns InputObjects for the held mouse buttons, checked in the order MouseButton1, MouseButton2, MouseButton3.

Returns:

• {InputObject} - Empty when Roblox is not the foreground window.

UserInputService:GetFocusedTextBox()

Always returns nil.

Returns:

• nil

UserInputService:GetLastInputType()

Always returns Enum.UserInputType.Keyboard.

Returns:

• EnumItem

UserInputService:IsGamepadButtonDown()

Always returns false; arguments are ignored.

Returns:

• boolean

InputObject

Input events, GetKeysPressed and GetMouseButtonsPressed produce plain Lua tables with the fields below. A new table is built for every event.

TweenService

Animates number, Vector2, Vector3 and Color3 values on a Lua table or a Drawing object. Tweens advance once per scheduler tick and write each new value straight into the target.

TweenService:Create(target, tweenInfo, goals)

Creates a stopped tween that moves each property in goals from its value at Play time to the goal value.

Parameters:

• target: table | Drawing - Object whose properties are animated.
• tweenInfo: TweenInfo | table | number (optional) - Timing. A number is used as Time, nil uses every default, and any table with TweenInfo fields works.
• goals: table - Property name to end value. Values must be finite numbers, Vector2, Vector3 or Color3.

Returns:

• tween: Tween - See Tween. Call Play to start it.

• Can also be called with a dot: TweenService.Create(target, tweenInfo, goals).
• Raises an error for an unsupported target, empty goals, or a goal whose type differs from the current value.

local fade = {Alpha = 0}
local tween = TweenService:Create(fade, TweenInfo.new(2, Enum.EasingStyle.Sine), {Alpha = 1})
tween:Play()
tween.Completed:Wait()
print("faded in", fade.Alpha)

TweenService:GetValue(alpha, [easingStyle], [easingDirection])

Returns the eased value for alpha without creating a tween.

Parameters:

• alpha: number - Progress from 0 to 1; values outside are clamped. Must be finite.
• easingStyle: EnumItem | string (optional, default "Quad") - An Enum.EasingStyle item or its name.
• easingDirection: EnumItem | string (optional, default "Out") - An Enum.EasingDirection item or its name.

Returns:

• number

• Can also be called with a dot.
• Raises an error for a non-finite alpha or an unknown style or direction.

for i = 0, 4 do
    print(i / 4, TweenService:GetValue(i / 4, Enum.EasingStyle.Quad, Enum.EasingDirection.InOut))
end

TweenInfo

TweenInfo.new([time], [easingStyle], [easingDirection], [repeatCount], [reverses], [delayTime])

Validates the timing values and returns them as a plain table. Call it with a dot.

Parameters:

• time: number (optional, default 1) - Seconds for one pass; finite and at least 0.
• easingStyle: EnumItem | string (optional, default "Quad") - An Enum.EasingStyle item or its name.
• easingDirection: EnumItem | string (optional, default "Out") - An Enum.EasingDirection item or its name.
• repeatCount: number (optional, default 0) - Extra cycles after the first. A whole number from -1 to 1000000; -1 repeats forever and needs a non-zero time or delayTime.
• reverses: boolean (optional, default false) - Play each cycle forward, then backward to the start value.
• delayTime: number (optional, default 0) - Seconds to wait at the start of every cycle; finite and at least 0.

Returns:

• info: table - Fields Time, EasingStyle, EasingDirection, RepeatCount, Reverses and DelayTime. Style and direction are stored as name strings such as "Quad", not as EnumItems.

• Invalid values raise an error immediately.

local info = TweenInfo.new(0.5, Enum.EasingStyle.Back, Enum.EasingDirection.Out, 0, true, 0.1)
print(info.Time, info.EasingStyle, info.Reverses)

One cycle is DelayTime + Time (doubled Time with Reverses), repeated RepeatCount + 1 times. The final value is written before Completed fires.

Styles: Linear, Sine, Back, Quad, Quart, Quint, Bounce, Elastic, Exponential, Circular, Cubic (see EasingStyle). Directions: In, Out, InOut.

Tween

Tween properties are read-only: assigning any key raises Tween properties are read-only. After Destroy, Play, Pause and Cancel raise Tween has been destroyed.

Tween:Play()

Starts or resumes the tween. Cancels other tweens on the same target that animate the same properties.

local box = {Size = Vector2.new(10, 10)}
local grow = TweenService:Create(box, 0.25, {Size = Vector2.new(40, 40)})
grow:Play()

Tween:Pause()

Stops a playing tween and keeps its progress; PlaybackState becomes Paused. Completed does not fire.

Tween:Cancel()

Stops the tween and fires Completed with Cancelled. Values already written stay.

Tween:Destroy()

Stops the tween without firing Completed, disconnects every Completed handler and releases the target. Calling it again does nothing.

Tween.PlaybackState

Current state: Begin after creation, then Delayed, Playing, Paused, Completed or Cancelled. These are bare Enum.PlaybackState items, so compare them with ==.

Returns:

• EnumItem

Tween.Completed

Fires when the tween finishes or is cancelled. Handlers may yield.

Parameters:

• playbackState: EnumItem - Enum.PlaybackState.Completed or Enum.PlaybackState.Cancelled.

local state = {Value = 0}
local tween = TweenService:Create(state, 1, {Value = 100})
tween.Completed:Connect(function(playbackState)
    print("tween ended:", playbackState.Name, state.Value)
end)
tween:Play()

Tween.Instance

The target table or Drawing object; nil after Destroy.

Returns:

• table | Drawing | nil

Tween.TweenInfo

A fresh copy of the tween's TweenInfo table each time it is read.

Returns:

• table

Tween.Error

The error that stopped the tween during an update, otherwise nil.

Returns:

• string | nil

ContextActionService

Get it with game:GetService("ContextActionService"). Bindings are built on UserInputService.InputBegan and InputEnded, so the same key mapping and focus rules apply, and the callback runs on both press and release.

ContextActionService:BindAction(name, callback, createTouchButton, ...)

Binds callback to the given inputs under name, replacing any binding with the same name.

Parameters:

• name: string - Action name, passed back to the callback.
• callback: function - Called as callback(name, state, input) with an InputObject.
• createTouchButton: boolean - Ignored.
• ...: EnumItem - Enum.KeyCode or Enum.UserInputType items. An input matches when its KeyCode or its UserInputType equals one of them.

• The callback runs inside a signal handler, so it cannot yield.
• If the callback errors, its connection is dropped and a later UnbindAction can remove an unrelated one.

local CAS = game:GetService("ContextActionService")
CAS:BindAction("sprint", function(name, state, input)
    if state == Enum.UserInputState.Begin then
        print(name, "started with", input.KeyCode)
    else
        print(name, "stopped")
    end
end, false, Enum.KeyCode.LeftShift, Enum.KeyCode.RightShift)

ContextActionService:BindActionAtPriority(name, callback, createTouchButton, priority, ...)

Same as BindAction; priority is ignored.

ContextActionService:UnbindAction(name)

Removes the binding with that name. Unknown names are ignored.

Parameters:

• name: string - Name given to BindAction.

ContextActionService:UnbindAllActions()

Removes every binding.

ContextActionService:GetBoundActionInfo()

Always returns an empty table.

Returns:

• table

StarterGui

Get it with game:GetService("StarterGui"). Only notifications do anything.

StarterGui:SetCore(name, value)

Only "SendNotification" does anything: it shows a notify toast with Title: Text.

Parameters:

• name: string - Only "SendNotification" is handled.
• value: table - Title and Text, converted with tostring. Duration does not control how long the notification stays, and other keys are ignored.

local StarterGui = game:GetService("StarterGui")
StarterGui:SetCore("SendNotification", {Title = "clover", Text = "Script loaded"})

StarterGui:GetCore()

Always returns nil.

Returns:

• nil

StarterGui:SetCoreGuiEnabled()

Does nothing.

StarterGui:GetCoreGuiEnabled()

Always returns true.

Returns:

• boolean

HttpService

The global HttpService wraps the engine's HTTP and JSON functions. Network calls need the unsafe API toggle; see http for request options, limits and the response format.

Plain-table snapshots of the players in the server.

local me = clover.local_player()
if not me then
    print("no local player yet")
    return
end

for _, p in ipairs(clover.players()) do
    if not p.is_local and p.humanoid ~= 0 then
        local dx = p.pos.x - me.pos.x
        local dy = p.pos.y - me.pos.y
        local dz = p.pos.z - me.pos.z
        local distance = math.sqrt(dx * dx + dy * dy + dz * dz)
        print(string.format("%s (%d) %.0f studs", p.name, p.user_id, distance))
    end
end

Functions

clover.players()

Returns every player the scanner currently knows about, the local player included.

Returns:

• players: table - Array of player tables, indexed from 1. Never nil: it is an empty table outside a game, while the game is loading, or before the scanner has found the Players service.

• The order of the array is not stable between calls. Sort it yourself if you need a fixed order.
• Entries with an empty name and a user_id of 0 are left out.
• Players without a character are normally still listed, with humanoid set to 0 and pos at 0, 0, 0. Check for that before projecting pos.

clover.local_player()

Returns the entry for your own player from the same snapshot that clover.players() uses.

Returns:

• player: table | nil - A player table without the is_local field, or nil when the snapshot has no local player (outside a game, while loading, or before the first scan).

local me = clover.local_player()
if me then
    print(me.name, me.user_id, me.pos.x, me.pos.y, me.pos.z)
end

Player table

To use pos with the data types, convert it: Vector3.new(p.pos.x, p.pos.y, p.pos.z). To put it on screen, pass the three numbers to world_to_screen.

local function enemies()
    local me = clover.local_player()
    local out = {}
    for _, p in ipairs(clover.players()) do
        local teammate = me ~= nil and p.team ~= 0 and p.team == me.team
        if not p.is_local and not teammate and p.humanoid ~= 0 then
            out[#out + 1] = p
        end
    end
    return out
end

print(#enemies(), "enemies")

Immediate-mode 2D drawing that you repeat every frame, plus world-to-screen projection.

local white = { R = 1, G = 1, B = 1, A = 1 }
local shade = { R = 0, G = 0, B = 0, A = 0.5 }

clover.on_render(function()
    local w, h = clover.screen_size()
    if w == 0 then
        return
    end
    local cx, cy = w / 2, h / 2
    draw.Line(cx - 8, cy, cx + 8, cy, white, 1)
    draw.Line(cx, cy - 8, cx, cy + 8, white, 1)

    local label = "clover"
    local tw, th = draw.GetTextSize(label)
    draw.RectangleFilled(10, 10, 10 + tw + 12, 10 + th + 8, shade, 4)
    draw.Text(16, 14, label, white)
end)

Each function also has snake_case and camelCase aliases plus the raw clover.draw_* name. Only draw.GetTextSize returns a value.

Colors

Every [color] parameter on this page is read the same way:

• All components are clamped to 0-1. Use n / 255 to convert byte values.
• The number form takes four argument slots, so the parameters after it shift by four. Always pass all four numbers: draw.Line(0, 0, 50, 50, 1, 0, 0, 2) reads 2 as alpha (clamped to 1) and leaves the thickness at its default.
• You cannot skip the color and still pass a later argument. A nil in the color slot is read as the red number, and the next arguments are consumed as green, blue and alpha.
• Color3 values are userdata and are rejected with an argument error. Convert them with { R = c.R, G = c.G, B = c.B, A = 1 }. The value of a Library colorpicker is already a plain { R, G, B } table and can be passed directly.

local red = { R = 1, G = 0, B = 0, A = 1 }
local accent = Color3.fromRGB(255, 170, 0)

local function rgba(c, a)
    return { R = c.R, G = c.G, B = c.B, A = a or 1 }
end

clover.on_render(function()
    draw.Line(10, 10, 200, 10, red, 2)
    draw.Line(10, 20, 200, 20, 0, 1, 0, 1, 2)
    draw.Line(10, 30, 200, 30, rgba(accent, 0.5), 2)
end)

Shapes

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

Draws a straight line from (x1, y1) to (x2, y2).

Parameters:

• x1: number - Start x in pixels.
• y1: number - Start y in pixels.
• x2: number - End x in pixels.
• y2: number - End y in pixels.
• color: table | numbers (optional, default white) - See Colors.
• thickness: number (optional, default 1) - Line width in pixels. Zero or negative values draw at 1.

Aliases: draw.line, clover.draw_line

draw.Rectangle(x1, y1, x2, y2, [color], [thickness], [rounding])

Draws the outline of an axis-aligned rectangle. (x1, y1) and (x2, y2) are two opposite corners, not a position and a size: pass x + w, y + h as the second pair.

Parameters:

• x1: number - Left edge in pixels.
• y1: number - Top edge in pixels.
• x2: number - Right edge in pixels.
• y2: number - Bottom edge in pixels.
• color: table | numbers (optional, default white) - See Colors.
• thickness: number (optional, default 1) - Outline width in pixels. Zero or negative values draw at 1.
• rounding: number (optional, default 0) - Corner radius in pixels, applied to all four corners.

Aliases: draw.rectangle, clover.draw_rect

local box = { R = 0.3, G = 0.8, B = 1, A = 1 }
local x, y, w, h = 100, 100, 80, 40

clover.on_render(function()
    draw.Rectangle(x, y, x + w, y + h, box, 2, 6)
end)

clover.draw_box(x1, y1, x2, y2, [color], [thickness])

Draws a rectangle outline. Same as draw.Rectangle without rounding.

Parameters:

• x1: number - Left edge in pixels.
• y1: number - Top edge in pixels.
• x2: number - Right edge in pixels.
• y2: number - Bottom edge in pixels.
• color: table | numbers (optional, default white) - See Colors.
• thickness: number (optional, default 1) - Outline width in pixels. Zero or negative values draw at 1.

draw.RectangleFilled(x1, y1, x2, y2, [color], [rounding])

Fills an axis-aligned rectangle between two opposite corners.

Parameters:

• x1: number - Left edge in pixels.
• y1: number - Top edge in pixels.
• x2: number - Right edge in pixels.
• y2: number - Bottom edge in pixels.
• color: table | numbers (optional, default white) - See Colors. Use alpha below 1 for a translucent panel.
• rounding: number (optional, default 0) - Corner radius in pixels.

Aliases: draw.rectangle_filled, draw.rectangleFilled, clover.draw_rect_filled

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

Draws the outline of a circle centered on (x, y). The number of segments is chosen automatically from the radius.

Parameters:

• x: number - Center x in pixels.
• y: number - Center y in pixels.
• radius: number - Radius in pixels.
• color: table | numbers (optional, default white) - See Colors.
• thickness: number (optional, default 1) - Outline width in pixels. Zero or negative values draw at 1.

Aliases: draw.circle, clover.draw_circle

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

Fills a circle centered on (x, y).

Parameters:

• x: number - Center x in pixels.
• y: number - Center y in pixels.
• radius: number - Radius in pixels.
• color: table | numbers (optional, default white) - See Colors.
• segments: integer (optional, default 0) - Number of segments. 0 or less picks a count automatically from the radius; a small value such as 6 draws a polygon.

Aliases: draw.circle_filled, draw.circleFilled, clover.draw_circle_filled

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

Draws the outline of the triangle with corners (x1, y1), (x2, y2) and (x3, y3).

Parameters:

• x1: number - First corner x.
• y1: number - First corner y.
• x2: number - Second corner x.
• y2: number - Second corner y.
• x3: number - Third corner x.
• y3: number - Third corner y.
• color: table | numbers (optional, default white) - See Colors.
• thickness: number (optional, default 1) - Outline width in pixels. Zero or negative values draw at 1.

Aliases: draw.triangle, clover.draw_triangle

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

Fills the triangle with corners (x1, y1), (x2, y2) and (x3, y3).

Parameters:

• x1: number - First corner x.
• y1: number - First corner y.
• x2: number - Second corner x.
• y2: number - Second corner y.
• x3: number - Third corner x.
• y3: number - Third corner y.
• color: table | numbers (optional, default white) - See Colors.

Aliases: draw.triangle_filled, draw.triangleFilled, clover.draw_triangle_filled

draw.Gradient(x1, y1, x2, y2, [color1], [color2], [vertical])

Fills the rectangle between two opposite corners with a two-color linear gradient. By default color1 is on the left edge and color2 on the right edge. There is no rounding.

Parameters:

• x1: number - Left edge in pixels.
• y1: number - Top edge in pixels.
• x2: number - Right edge in pixels.
• y2: number - Bottom edge in pixels.
• color1: table | numbers (optional, default white) - Start color. See Colors.
• color2: table | numbers (optional, default white) - End color.
• vertical: boolean (optional, default false) - true for top-to-bottom. Defaults to left-to-right.

Aliases: draw.gradient, clover.draw_gradient

local red = { R = 1, G = 0, B = 0, A = 1 }
local blue = { R = 0, G = 0, B = 1, A = 1 }
local clear = { R = 0, G = 0, B = 0, A = 0 }
local dark = { R = 0, G = 0, B = 0, A = 0.8 }

clover.on_render(function()
    draw.Gradient(20, 60, 220, 80, red, blue)
    draw.Gradient(20, 90, 220, 140, clear, dark, true)
end)

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

Draws connected line segments through a list of points.

Parameters:

• points: table - Array of { X, Y } tables or flat numbers read as x, y pairs. Vector2 values are skipped. Needs at least two points.
• color: table | numbers (optional, default white) - See Colors.
• thickness: number (optional, default 1) - Line width in pixels. Zero or negative values draw at 1.
• closed: boolean (optional, default false) - Any truthy value also connects the last point back to the first. You must pass thickness to reach this argument.

Aliases: draw.polyline, clover.draw_polyline

local cyan = { R = 0.4, G = 0.8, B = 1, A = 1 }
local roof = { { x = 100, y = 100 }, { x = 160, y = 60 }, { x = 220, y = 100 } }
local zigzag = { 100, 140, 130, 120, 160, 140, 190, 120 }

clover.on_render(function()
    draw.Polyline(roof, cyan, 2, true)
    draw.Polyline(zigzag, cyan, 1)
end)

Text

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

Draws a string with its top-left corner at (x, y). Newlines start a new line.

Parameters:

• x: number - Left edge in pixels.
• y: number - Top edge in pixels.
• text: string - The text. Numbers are converted to strings; other types raise an error.
• color: table | numbers (optional, default white) - See Colors.

Aliases: draw.text, clover.draw_text

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

Draws text with a 1-pixel outline, readable on any background. Good for ESP labels.

Parameters:

• x: number - Left edge in pixels.
• y: number - Top edge in pixels.
• text: string - The text. Numbers are converted to strings; other types raise an error.
• color: table | numbers (optional, default white) - Fill color. See Colors.
• outlineColor: table | numbers (optional, default opaque black) - Outline color. Read only when an argument is present after color; an explicit nil there counts as present and gives a white outline.

Aliases: draw.text_outlined, draw.textOutlined, clover.draw_text_outlined

draw.GetTextSize(text)

Measures a string with the overlay's current ImGui font, the font that draw.Text and draw.TextOutlined draw with. Use it to center or right-align labels.

Parameters:

• text: string - The text to measure. Numbers are converted to strings.

Returns:

• width: number - Width in pixels.
• height: number - Height in pixels. Both values are 0 while the overlay has no ImGui context or font yet.

Aliases: draw.get_text_size, draw.getTextSize, clover.draw_get_text_size

local white = { R = 1, G = 1, B = 1, A = 1 }

clover.on_render(function()
    local w = clover.screen_size()
    local text = "centered"
    local tw = draw.GetTextSize(text)
    draw.TextOutlined(w / 2 - tw / 2, 40, text, white)
end)

Screen and projection

world_to_screen(x, y, z)

Projects a world position onto the screen with the game camera's current view matrix. The result is in the same pixel space as the draw functions.

Parameters:

• x: number - World X.
• y: number - World Y.
• z: number - World Z. A Vector3 is not accepted; pass v.X, v.Y, v.Z.

Returns:

• x: number - Screen x in pixels.
• y: number - Screen y in pixels.
• onScreen: boolean - true when the point is inside the view on both axes.

Aliases: WorldToScreen, clover.world_to_screen, clover.WorldToScreen

• Returns 0, 0, false when the camera cannot be read (for example outside a game) or when the point is behind the camera or extremely close to it.
• Points off-screen still return their coordinates, with false.

local yellow = { R = 1, G = 0.9, B = 0.2, A = 1 }

clover.on_render(function()
    local me = clover.local_player()
    if not me then
        return
    end
    local x, y, onScreen = world_to_screen(me.pos.x, me.pos.y, me.pos.z)
    if onScreen then
        draw.CircleFilled(x, y, 4, yellow)
    end
end)

clover.screen_size()

Returns the size of the game view in pixels, read from the engine. This is the space that world_to_screen maps into. cheat.GetWindowSize returns the same values.

Returns:

• width: number - Width in pixels, or 0 when the size cannot be read.
• height: number - Height in pixels, or 0 when the size cannot be read.

Retained objects: create a Line, Text, Circle or Square once and it stays on screen until removed.

local label = Drawing.new("Text")
label.Text = "clover"
label.Size = 18
label.Center = true
label.Outline = true
label.Color = Color3.fromRGB(255, 200, 80)
label.Position = Vector2.new(400, 300)

local ring = Drawing.new("Circle")
ring.Position = Vector2.new(400, 300)
ring.Radius = 40
ring.Thickness = 2
ring.Color = Color3.new(1, 1, 1)

task.delay(5, function()
    label:Remove()
    ring:Remove()
end)

Functions

Drawing.new(type)

Creates a drawing object. It is visible right away, so set its properties immediately.

Parameters:

• type: string - "Line", "Text", "Circle" or "Square" (case-insensitive). Anything else raises an error.

Returns:

• object: Drawing - The new object. typeof(object) is "Drawing" and tostring(object) is "Drawing(Line)", "Drawing(Text)", "Drawing(Circle)" or "Drawing(Square)".

Drawing.clear()

Removes every drawing object created by any script. Existing handles behave like removed objects afterwards.

Aliases: cleardrawcache

Methods

Drawing:Remove()

Removes the object for good. Afterwards properties read as nil. Safe to call twice.

Aliases: Drawing:Destroy

Common properties

These exist on every type. Reading a property that does not belong to the object's type returns nil, and writing one is silently ignored (for example Radius on a Line).

Drawing.Visible

boolean, default true. Assignments use Lua truthiness, so nil hides the object. A hidden object keeps its properties and can be shown again.

Drawing.ZIndex

integer, default 0. Lower values draw first, higher values on top; equal values keep creation order. Assigning a number without an integer value (such as 1.5) or a non-number raises an error.

Drawing.Transparency

number, default 0. 0 is opaque, 1 is invisible.

Drawing.Color

Color3, default white. Also accepts a { R, G, B } table with 0-1 values. Alpha comes from Transparency.

Drawing.Thickness

number, default 1. Stroke width in pixels for lines and unfilled shapes.

Positions and sizes typed Vector2 below accept a Vector2 or a table with X/x and Y/y fields (a missing field counts as 0); any other value is silently ignored. Reading them returns a Vector2. Number properties raise an error when assigned a non-number.

Line

Text

Text uses the overlay's ImGui font; there is no Font property. For an exact measurement of the default-size font use draw.GetTextSize.

Circle

Square

Tweening

Drawing objects are valid targets for TweenService:Create (see Services). Number, Vector2 and Color3 properties can be tweened; ZIndex, NumSides and TextBounds cannot and raise an error.

local label = Drawing.new("Text")
label.Text = "saved"
label.Size = 16
label.Outline = true
label.Position = Vector2.new(20, 20)

local fade = TweenService:Create(label, TweenInfo.new(1.5), { Transparency = 1 })
fade.Completed:Connect(function()
    label:Remove()
end)
fade:Play()

Random numbers, timing, cursor position, menu state and clipboard.

local count = 0
local rate = 0
local started = utility.GetTickCount()

cheat.register("onDraw", function()
    count = count + 1
    local now = utility.GetTickCount()
    if now - started >= 1000 then
        rate = count
        count = 0
        started = now
    end
    if utility.GetMenuState() then
        return
    end
    local pos = utility.GetMousePos()
    draw.Text(pos.X + 14, pos.Y + 14, rate .. " callbacks/s", 1, 1, 1, 1)
end)

Functions

utility.RandomInt(min, max)

Returns a random integer from min to max, inclusive. Independent of math.random.

Parameters:

• min: integer - Lower bound. Must have an integer value: a number with a fractional part or a non-numeric value raises an error.
• max: integer - Upper bound, same rules as min.

Returns:

• integer - The random value. When max is less than min, min is returned unchanged.

Aliases: utility.random_int, utility.randomInt, clover.utility_random_int

local roll = utility.RandomInt(1, 6)
print("rolled", roll)

utility.RandomFloat(min, max)

Returns a uniformly distributed random float from min up to, but not including, max. Uses its own generator of the same kind as RandomInt.

Parameters:

• min: number - Lower bound.
• max: number - Upper bound.

Returns:

• number - The random value.

Aliases: utility.random_float, utility.randomFloat, clover.utility_random_float

• Keep min less than or equal to max. Unlike RandomInt there is no special case for reversed bounds.

local jitter = utility.RandomFloat(-0.5, 0.5)
print(string.format("jitter %.3f", jitter))

utility.GetTickCount()

Returns the number of milliseconds since Windows started (GetTickCount64). Subtract two readings to measure an interval.

Returns:

• integer - Milliseconds since system start.

Aliases: utility.get_tick_count, utility.getTickCount, clover.utility_get_tick_count

• For seconds since the Unix epoch use the global tick(), listed on Globals.

local started = utility.GetTickCount()
task.delay(2, function()
    print("elapsed ms", utility.GetTickCount() - started)
end)

utility.GetDeltaTime()

Returns the time in seconds between the overlay's last two rendered frames (ImGui's DeltaTime). Returns 0 while the overlay's ImGui context does not exist.

Returns:

• number - Overlay frame time in seconds, or 0.

Aliases: utility.get_delta_time, utility.getDeltaTime, clover.utility_get_delta_time

• This is the overlay's frame time. RunService.Heartbeat handlers get the script loop's time instead.

utility.GetMousePos()

Returns the cursor position in pixels, matching draw coordinates while Roblox is focused.

Returns:

• table - { X = x, Y = y, x = x, y = y }. Both spellings hold the same float values.

Aliases: utility.get_mouse_pos, utility.getMousePos, clover.utility_get_mouse_pos, mouse.GetPosition, mouse.get_position, mouse.getPosition

• When no window has focus the values are screen coordinates.
• The global getmousepos returns the same position as two numbers instead of a table.

cheat.register("onDraw", function()
    local pos = utility.GetMousePos()
    draw.Circle(pos.X, pos.Y, 6, 1, 0.2, 0.2, 1)
end)

utility.GetMenuState()

Returns whether the clover menu is currently open.

Returns:

• boolean - true while the menu is visible, false while it is hidden.

Aliases: utility.get_menu_state, utility.getMenuState, clover.utility_get_menu_state

cheat.register("onDraw", function()
    if not utility.GetMenuState() then
        draw.Text(10, 10, "menu hidden", 1, 1, 1, 1)
    end
end)

utility.GetClipboard()

Returns the text on the Windows clipboard.