Overview

The cheadle_api provides a wide range of Lua functions and tables that allow you to create hooks, draw shapes, manipulate game states, handle input, configure settings, debug, and more. This document outlines each function and table namespace, along with their parameters, return values, and descriptions.

Paths used by RunFile are relative to %appdata%/cheadleware-v2/lua. Paths used by File.* and DrawTexture are relative to %appdata%/cheadleware-v2/data.

Global Functions

The following functions are accessible directly under the cheadle_api table.

CreateHook

Syntax: cheadle_api.CreateHook(name, identifier, func)

• Parameters:
  • name (string): The name of the hook to listen to.
  • identifier (string): A unique identifier for this listener. Reusing the same identifier overwrites the previous one.
  • func (function): The Lua function that will be called when the hook fires.
• Description: Registers a callback for a cheadle hook. See the Hooks section for the list of available hooks.

RemoveHook

Syntax: cheadle_api.RemoveHook(name, identifier)

• Parameters:
  • name (string): The hook name.
  • identifier (string): The identifier passed to CreateHook.
• Description: Removes a previously registered hook callback.

DrawRect

Syntax: cheadle_api.DrawRect(x, y, w, h, color, rounding = 0)

• Parameters:
  • x (number): The X-coordinate of the rectangle.
  • y (number): The Y-coordinate of the rectangle.
  • w (number): Width.
  • h (number): Height.
  • color (table): Color table with fields r, g, b, optional a.
  • rounding (number, optional): Corner rounding radius (default 0).
• Description: Draws a filled rectangle. Must be called from a draw hook (Paint, EngineDrawing, Player_DrawExtra, ImGui paint function, etc.).

DrawText

Syntax: cheadle_api.DrawText(x, y, text, color, align = 0, font = nil)

• Parameters:
  • x (number): X-coordinate.
  • y (number): Y-coordinate.
  • text (string): The text to draw.
  • color (table): Color table.
  • align (number, optional): 0 left, 1 center, 2 right.
  • font (string, optional): Name of a font registered through BuildFont.
• Description: Draws text at the given position.

DrawCircle

Syntax: cheadle_api.DrawCircle(x, y, radius, color, filled = false)

• Parameters:
  • x (number): Center X.
  • y (number): Center Y.
  • radius (number): Radius.
  • color (table): Color table.
  • filled (boolean, optional): If true, fills the circle (default false).
• Description: Draws a circle.

DrawLine

Syntax: cheadle_api.DrawLine(x1, y1, x2, y2, color)

• Parameters:
  • x1, y1 (number): Start point.
  • x2, y2 (number): End point.
  • color (table): Color table.
• Description: Draws a line between two points.

DrawTexture

Syntax: cheadle_api.DrawTexture(texture_name, x, y, w, h)

• Parameters:
  • texture_name (string): File path relative to %appdata%/cheadleware-v2/data.
  • x, y (number): Top-left position.
  • w, h (number): Draw size.
• Description: Draws a texture loaded from disk. Textures are cached after the first load.

BuildFont

Syntax: cheadle_api.BuildFont(title, path, size)

• Parameters:
  • title (string): Name to register the font under (used by DrawText/DrawExtra).
  • path (string): Path to the font file.
  • size (number): Font size.
• Description: Loads a font and registers it under the given title.

DrawExtra

Syntax: cheadle_api.DrawExtra(text, color, side, font = "Default", ignore_dormant = false)

• Parameters:
  • text (string): Text to draw.
  • color (table): Color table.
  • side (number): Side to draw on. Use ESP_LEFT, ESP_TOP, ESP_RIGHT, ESP_BOTTOM.
  • font (string, optional): Font name.
  • ignore_dormant (boolean, optional): If true, the line still shows on dormant entities.
• Description: Adds an extra ESP line to the player or entity currently being drawn. Only valid inside the Player_DrawExtra and Entity_DrawExtra hooks.

PushDarkRPVars

Syntax: cheadle_api.PushDarkRPVars()

• Description: Pushes the global DarkRPVars table onto the Lua stack.

getDarkRPVar

Syntax: cheadle_api.getDarkRPVar(ply, var_name)

• Parameters:
  • ply (Player): The player whose DarkRP var to retrieve.
  • var_name (string): The DarkRP var name.
• Returns: The value of the requested var, or nil.

InviteFriend

Syntax: cheadle_api.InviteFriend(steamid64)

• Parameters:
  • steamid64 (string): SteamID64 of the friend, decimal or 0x-prefixed hex.
• Description: Sends a Steam invite to the given SteamID64.

SendAchievement

Syntax: cheadle_api.SendAchievement(achievement_id)

• Parameters:
  • achievement_id (number): The achievement ID.
• Description: Sends an achievement_earned message to the server.

BlockTraceEntity

Syntax: cheadle_api.BlockTraceEntity(entity)

• Parameters:
  • entity (Entity): Entity to add to the aimbot trace skip list.
• Description: Adds the entity to the autowall trace filter for this aimbot pass. Intended for use inside Aimbot_IgnoreEntities. The skip list is cleared every aimbot tick.

BlockAimbotTarget

Syntax: cheadle_api.BlockAimbotTarget(entity)

• Parameters:
  • entity (Entity): Player entity to remove from the aimbot’s candidate list.
• Description: Adds the player to the aimbot target skip list for this tick. Intended for use inside Aimbot_IgnoreEntities. The skip list is cleared every aimbot tick.

IsFreecamming

Syntax: cheadle_api.IsFreecamming()

• Returns: boolean — true if freecam is active.

FreecamPos

Syntax: cheadle_api.FreecamPos()

• Returns: Vector of the freecam position, or nil if freecam is not active.

FreecamAng

Syntax: cheadle_api.FreecamAng()

• Returns: Angle of the freecam orientation, or nil if freecam is not active.

GetAimbotTarget

Syntax: cheadle_api.GetAimbotTarget()

• Returns: The current aimbot target Entity, or nil.

GetTeamData

Syntax: cheadle_api.GetTeamData(team_id_or_entity)

• Parameters:
  • team_id_or_entity (number or Entity): A team number or a player entity.
• Returns: A table { name = string, color = { r, g, b, a } }, or nil if the team is unknown.

Log

Syntax: cheadle_api.Log(message)

• Parameters:
  • message (string): Message to log.
• Description: Logs a message to the cheadle console.

Syntax: cheadle_api.Log(color, prefix, message)

• Parameters:
  • color (table): Color table for the prefix.
  • prefix (string): Prefix shown before the message.
  • message (string): The message body.
• Description: Logs a colored prefixed message to the console.

FindCFunction

Syntax: cheadle_api.FindCFunction(function_name)

Syntax: cheadle_api.FindCFunction(table_name, function_name)

• Parameters:
  • table_name (string, optional): The metatable / library name ("GLOBAL" for globals). If omitted, defaults to "GLOBAL".
  • function_name (string): Name of the C function to look up.
• Returns: The C function, or nil if not found.
• Description: Looks up a C function pointer from a Lua library or metatable.

Notification

Syntax: cheadle_api.Notification(message)

Syntax: cheadle_api.Notification(message, color, duration_ms)

• Parameters:
  • message (string): Notification text.
  • color (table, optional): Color table.
  • duration_ms (number, optional): Time on screen, in milliseconds.
• Description: Displays an in-game notification.

RunFile

Syntax: cheadle_api.RunFile(file_path)

• Parameters:
  • file_path (string): Path relative to %appdata%/cheadleware-v2/lua.
• Description: Loads and runs a Lua file inside the cheadle environment.

RunString

Syntax: cheadle_api.RunString(code)

• Parameters:
  • code (string): Lua source to execute.
• Description: Executes Lua source inside the cheadle environment.

RichPresence

Syntax: cheadle_api.RichPresence(text)

• Parameters:
  • text (string): Rich presence string.
• Description: Updates Steam rich presence.

IsMenuOpen

Syntax: cheadle_api.IsMenuOpen()

• Returns: boolean — whether the cheadle menu is open.

NewCClosure

Syntax: cheadle_api.NewCClosure(func)

• Parameters:
  • func (function): A Lua function.
• Returns: A C closure that, when called, forwards its arguments to func and returns its results.
• Description: Wraps a Lua function in a C closure. Useful for code that distinguishes between Lua and C functions.

getrawmetatable

Syntax: cheadle_api.getrawmetatable(table)

• Parameters:
  • table (table): Any table.
• Returns: The table’s metatable, ignoring __metatable, or nil if it has none.

OpenURL

Syntax: cheadle_api.OpenURL(url)

• Parameters:
  • url (string): URL to open.
• Description: Opens a URL in the user’s default browser.

GetEngineSpread

Syntax: cheadle_api.GetEngineSpread(cmd, spread)

• Parameters:
  • cmd (CUserCmd): The command being processed.
  • spread (number): The weapon’s spread cone in radians.
• Returns: An Angle representing the angular correction needed to compensate for engine spread on this command.
• Description: Computes the spread correction angle for cmd based on its command_number. Useful for nospread / silent-aim implementations.

GetRandomSpread

Syntax: cheadle_api.GetRandomSpread(cmd, seed)

• Parameters:
  • cmd (CUserCmd): The command.
  • seed (number): A seed value (currently unused — derives from cmd.command_number).
• Returns: Two numbers (randX, randY) in roughly the range [-1, 1], representing the engine’s per-shot random spread offsets.

SetTickCount

Syntax: cheadle_api.SetTickCount(cmd, tick)

• Parameters:
  • cmd (CUserCmd): The command to modify.
  • tick (number): New tick_count.
• Description: Overwrites the command’s tick_count field.

SetCommandNumber

Syntax: cheadle_api.SetCommandNumber(cmd, number)

• Parameters:
  • cmd (CUserCmd)
  • number (number): New command_number. Also recomputes random_seed from it.

GetRandomSeed

Syntax: cheadle_api.GetRandomSeed(cmd)

• Parameters:
  • cmd (CUserCmd)
• Returns: number — the command’s random_seed.

SetRandomSeed

Syntax: cheadle_api.SetRandomSeed(cmd, seed)

• Parameters:
  • cmd (CUserCmd)
  • seed (number): Desired seed.
• Description: Searches forward from cmd.command_number for a command_number whose derived seed matches seed, then writes both fields. Used for seed-prediction exploits.

SetIsTyping

Syntax: cheadle_api.SetIsTyping(cmd, typing)

• Parameters:
  • cmd (CUserCmd)
  • typing (boolean)
• Description: Sets the is_typing flag on the command.

StartPrediction

Syntax: cheadle_api.StartPrediction(cmd)

• Parameters:
  • cmd (CUserCmd)
• Description: Begins an engine-prediction block for the given command. Pair with FinishPrediction.

FinishPrediction

Syntax: cheadle_api.FinishPrediction()

• Description: Ends the engine-prediction block opened by StartPrediction.

cheadle_api.Config

Manages cheadle configuration values, keybinds, colors, friend lists, and entity ESP whitelist.

The category argument is the config tab ("combat", "visuals", "ents", "misc", "exploits"). The feature argument is the in-cheat name of the option (e.g. "Chams").

GetBool

Syntax: cheadle_api.Config.GetBool(category, feature)

• Returns: boolean, or nil if the option doesn’t exist.

SetBool

Syntax: cheadle_api.Config.SetBool(category, feature, value)

GetInt

Syntax: cheadle_api.Config.GetInt(category, feature)

• Returns: number, or nil.

SetInt

Syntax: cheadle_api.Config.SetInt(category, feature, value)

GetFloat

Syntax: cheadle_api.Config.GetFloat(category, feature)

• Returns: number, or nil.

SetFloat

Syntax: cheadle_api.Config.SetFloat(category, feature, value)

GetString

Syntax: cheadle_api.Config.GetString(category, feature)

• Returns: string, or nil.

SetString

Syntax: cheadle_api.Config.SetString(category, feature, value)

GetColor

Syntax: cheadle_api.Config.GetColor(category, feature)

• Returns: A color table { r, g, b, a }, or nil.

SetColor

Syntax: cheadle_api.Config.SetColor(category, feature, value)

• Parameters: value is a color table.

GetKeybind

Syntax: cheadle_api.Config.GetKeybind(category, feature)

• Returns: A table { key = number, feature = string, mode = number }, or nil.
• Description: key is a Windows virtual-key code (see SetKeybind example).

SetKeybind

Syntax: cheadle_api.Config.SetKeybind(category, feature, value)

• Parameters:

  • value (table): { key = number, mode = number }. The feature field is preserved by the cheat; only key and mode are read.

• Example:

-- Uses Windows virtual-key codes, NOT Source ButtonCode_t.
-- https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes
cheadle_api.Config.SetKeybind("exploits", "Speedhack Key", { key = 0x48 --[[ H ]], mode = 0 })

IsKeybindActive

Syntax: cheadle_api.Config.IsKeybindActive(category, feature)

• Returns: boolean — whether the keybind is currently held / toggled active.

LoadConfig

Syntax: cheadle_api.Config.LoadConfig(name)

• Parameters:
  • name (string): Config file name to load from disk.

EntListSet

Syntax: cheadle_api.Config.EntListSet(entClass, enabled)

• Parameters:
  • entClass (string): Entity class name.
  • enabled (boolean): Whether to draw this entity class on the entity ESP.

GetFriendStatus

Syntax: cheadle_api.Config.GetFriendStatus(ply)

• Parameters:
  • ply (Player)
• Returns: number — 0 neutral, 1 friend, 2 enemy.

SetFriendStatus

Syntax: cheadle_api.Config.SetFriendStatus(ply, status)

• Parameters:
  • ply (Player)
  • status (number): 0 neutral, 1 friend, 2 enemy.

cheadle_api.Input

Functions to simulate keyboard / mouse input through the engine’s input system.

ButtonDown

Syntax: cheadle_api.Input.ButtonDown(button_code)

• Parameters:
  • button_code (number): Source ButtonCode_t.
• Description: Simulates the button being pressed down.

ButtonUp

Syntax: cheadle_api.Input.ButtonUp(button_code)

• Parameters:
  • button_code (number): Source ButtonCode_t.
• Description: Simulates the button being released.

ButtonClick

Syntax: cheadle_api.Input.ButtonClick(button_code)

• Parameters:
  • button_code (number)
• Description: Simulates a press + release of the button.

MouseClick

Syntax: cheadle_api.Input.MouseClick(button)

• Parameters:
  • button (number): 0 left, 1 right, 2 middle, etc.
• Description: Simulates a mouse click.

ButtonToVirtual

Syntax: cheadle_api.Input.ButtonToVirtual(button_code)

• Parameters:
  • button_code (number): Source ButtonCode_t.
• Returns: The corresponding Windows virtual-key code.

VirtualToButton

Syntax: cheadle_api.Input.VirtualToButton(vk_code)

• Parameters:
  • vk_code (number): Windows virtual-key code.
• Returns: The corresponding Source ButtonCode_t.

cheadle_api.debug

Debugging helpers.

GetRegistry

Syntax: cheadle_api.debug.GetRegistry()

• Returns: The Lua registry table.
• Description: Pushes the Lua registry (LUA_REGISTRYINDEX) onto the stack so Lua can iterate or inspect it.

cheadle_api.GlobalVars

Read and write CGlobalVarsBase fields. All getters return numbers; all setters take a number.

GetAbsoluteFrametime / SetAbsoluteFrametime

Syntax:

• cheadle_api.GlobalVars.GetAbsoluteFrametime() → number
• cheadle_api.GlobalVars.SetAbsoluteFrametime(value)

GetCurtime / SetCurtime

Syntax:

• cheadle_api.GlobalVars.GetCurtime() → number
• cheadle_api.GlobalVars.SetCurtime(value)

GetFramecount / SetFramecount

Syntax:

• cheadle_api.GlobalVars.GetFramecount() → number
• cheadle_api.GlobalVars.SetFramecount(value)

GetFrametime / SetFrametime

Syntax:

• cheadle_api.GlobalVars.GetFrametime() → number
• cheadle_api.GlobalVars.SetFrametime(value)

GetInterpolationAmount / SetInterpolationAmount

Syntax:

• cheadle_api.GlobalVars.GetInterpolationAmount() → number
• cheadle_api.GlobalVars.SetInterpolationAmount(value)

GetIntervalPerTick / SetIntervalPerTick

Syntax:

• cheadle_api.GlobalVars.GetIntervalPerTick() → number
• cheadle_api.GlobalVars.SetIntervalPerTick(value)

GetMaxClients / SetMaxClients

Syntax:

• cheadle_api.GlobalVars.GetMaxClients() → number
• cheadle_api.GlobalVars.SetMaxClients(value)

GetNetworkProtocol / SetNetworkProtocol

Syntax:

• cheadle_api.GlobalVars.GetNetworkProtocol() → number
• cheadle_api.GlobalVars.SetNetworkProtocol(value)

GetRealtime / SetRealtime

Syntax:

• cheadle_api.GlobalVars.GetRealtime() → number
• cheadle_api.GlobalVars.SetRealtime(value)

GetSimTicksThisFrame / SetSimTicksThisFrame

Syntax:

• cheadle_api.GlobalVars.GetSimTicksThisFrame() → number
• cheadle_api.GlobalVars.SetSimTicksThisFrame(value)

GetTickcount / SetTickcount

Syntax:

• cheadle_api.GlobalVars.GetTickcount() → number
• cheadle_api.GlobalVars.SetTickcount(value)

cheadle_api.channel

Wrapper around INetChannelInfo / INetChannel for the active client connection. All getters return nil if there is no active channel.

The flow argument used by several functions is 0 for outgoing and 1 for incoming.

GetName

Syntax: cheadle_api.channel.GetName() → string

GetAddress

Syntax: cheadle_api.channel.GetAddress() → string

• Description: Remote IP and port.

GetTime / GetTimeConnected / GetTimeSinceLastReceived / GetTimeoutSeconds

Syntax:

• cheadle_api.channel.GetTime() → number
• cheadle_api.channel.GetTimeConnected() → number
• cheadle_api.channel.GetTimeSinceLastReceived() → number
• cheadle_api.channel.GetTimeoutSeconds() → number

GetBufferSize

Syntax: cheadle_api.channel.GetBufferSize() → number

GetDataRate / GetRate / SetRate

Syntax:

• cheadle_api.channel.GetDataRate() → number
• cheadle_api.channel.GetRate() → number
• cheadle_api.channel.SetRate(rate) — rate in bytes per second.

IsLoopback / IsTimingOut / IsPlayback

Syntax:

• cheadle_api.channel.IsLoopback() → boolean
• cheadle_api.channel.IsTimingOut() → boolean
• cheadle_api.channel.IsPlayback() → boolean

GetLatency / GetAvgLatency / GetAvgLoss / GetAvgChoke / GetAvgData / GetAvgPackets / GetTotalData

Syntax: cheadle_api.channel.<name>(flow) → number

• Parameters:
  • flow (number): 0 outgoing, 1 incoming.

GetSequenceNr

Syntax: cheadle_api.channel.GetSequenceNr(flow) → number

SetSequenceNr

Syntax: cheadle_api.channel.SetSequenceNr(value)

• Description: Overwrites m_nOutSequenceNr directly.

IsValidPacket

Syntax: cheadle_api.channel.IsValidPacket(flow, frame_number) → boolean

GetPacketTime

Syntax: cheadle_api.channel.GetPacketTime(flow, frame_number) → number

GetCommandInterpolationAmount

Syntax: cheadle_api.channel.GetCommandInterpolationAmount(flow, frame_number) → number

GetBSendPacket / SetBSendPacket

Syntax:

• cheadle_api.channel.GetBSendPacket() → boolean
• cheadle_api.channel.SetBSendPacket(value) — disable to skip sending the next outgoing packet (clc_Move stop).

SendDatagram

Syntax: cheadle_api.channel.SendDatagram()

• Description: Forces an immediate datagram send.

SendNetStringCmd

Syntax: cheadle_api.channel.SendNetStringCmd(cmd)

• Parameters:
  • cmd (string): Server console command to send (forwarded as clc_StringCmd).

SetCVar

Syntax: cheadle_api.channel.SetCVar(name, value)

• Parameters:
  • name (string): ConVar name.
  • value (string): New value, sent through the channel as a server-replicated cvar update.

cheadle_api.player

Reads player state directly from the entity. All functions take a player Entity.

GetAnimState

Syntax: cheadle_api.player.GetAnimState(entity)

• Returns: A table:

{
  move_x            = number,
  move_y            = number,
  m_flEyeYaw        = number,
  m_flEyePitch      = number,
  m_flGoalFeetYaw   = number,
  m_flCurrentFeetYaw= number,
}

GetEyeYaw

Syntax: cheadle_api.player.GetEyeYaw(entity) → number

GetBaseVelocity

Syntax: cheadle_api.player.GetBaseVelocity(entity)

• Returns: A table { x, y, z }.

GetVelocity

Syntax: cheadle_api.player.GetVelocity(entity)

• Returns: A table { x, y, z }.

GetViewOffset

Syntax: cheadle_api.player.GetViewOffset(entity)

• Returns: A table { x, y, z }.

GetViewPunch / GetAimPunch

Syntax:

• cheadle_api.player.GetViewPunch(entity) → { pitch, yaw, roll }
• cheadle_api.player.GetAimPunch(entity) → { pitch, yaw, roll }

GetTickBase

Syntax: cheadle_api.player.GetTickBase(entity) → number

GetSimulationTime

Syntax: cheadle_api.player.GetSimulationTime(entity) → number

GetFlags

Syntax: cheadle_api.player.GetFlags(entity) → number

• Description: Bit field of EntityFlags.

HasFlag

Syntax: cheadle_api.player.HasFlag(entity, flag) → boolean

IsDucked / IsDucking / IsInDuckJump

Syntax: cheadle_api.player.<name>(entity) → boolean

GetDucktime / GetDuckJumpTime

Syntax: cheadle_api.player.<name>(entity) → number

GetAmmo

Syntax: cheadle_api.player.GetAmmo(entity) → number

• Description: Returns the player’s m_iAmmo (raw count of the active ammo slot).

GetGroundEntity

Syntax: cheadle_api.player.GetGroundEntity(entity) → number

• Description: Returns the raw EHANDLE value as a number. Compare against 0 for “not on the ground”.

GetFallVelocity

Syntax: cheadle_api.player.GetFallVelocity(entity) → number

GetTeamNum

Syntax: cheadle_api.player.GetTeamNum(entity) → number

GetMoveType

Syntax: cheadle_api.player.GetMoveType(entity) → number

GetHitboxSet

Syntax: cheadle_api.player.GetHitboxSet(entity) → number

IsDormant

Syntax: cheadle_api.player.IsDormant(entity) → boolean

GetInt / GetFloat / GetBool

Syntax: cheadle_api.player.Get<Type>(entity, netvar_name)

• Parameters:
  • netvar_name (string): Full netvar path (e.g. "DT_BasePlayer.m_iHealth").
• Returns: The netvar value as the requested type, or nil if unknown.
• Description: Reads a netvar by name from the entity. Offsets are cached.

ListNetVars

Syntax: cheadle_api.player.ListNetVars() → table

• Returns: An array of every known netvar name. Takes no entity argument.

cheadle_api.timer

Tick-driven timers. Timers are cleared automatically when leaving a server.

Simple

Syntax: cheadle_api.timer.Simple(delay, func)

• Parameters:
  • delay (number): Seconds to wait.
  • func (function): Function to run.
• Description: Runs func once, after delay seconds.

Create

Syntax: cheadle_api.timer.Create(name, delay, repetitions, func)

• Parameters:
  • name (string): Unique identifier.
  • delay (number): Seconds between calls.
  • repetitions (number): Number of times to fire (0 = infinite).
  • func (function)
• Description: Creates a named recurring timer. Re-creating with the same name replaces it.

Exists

Syntax: cheadle_api.timer.Exists(name) → boolean

Remove

Syntax: cheadle_api.timer.Remove(name)

cheadle_api.File

File I/O sandboxed to %appdata%/cheadleware-v2/data. Path traversal is sanitized. Writable extensions are limited to .txt, .log, .json, .dat, .png, .jpeg, .jpg, .wav — Write silently ignores other extensions.

Read

Syntax: cheadle_api.File.Read(file_path) → string | nil

Write

Syntax: cheadle_api.File.Write(file_path, data)

• Description: Writes data to file_path. The path’s extension must be in the allow-list above.

MakeDir

Syntax: cheadle_api.File.MakeDir(path)

Delete

Syntax: cheadle_api.File.Delete(file_path)

RemoveDir

Syntax: cheadle_api.File.RemoveDir(path)

• Description: Recursively removes the directory.

FindFiles

Syntax: cheadle_api.File.FindFiles(path) → table | nil

• Returns: Array of file names in the directory, or nil if the directory doesn’t exist.

FindDirectories

Syntax: cheadle_api.File.FindDirectories(path) → table | nil

• Returns: Array of directory names, or nil.

cheadle_api.Draw

Mirror of the top-level draw functions, kept under a Draw table for callers that want a namespace. All functions behave identically to their top-level counterparts.

GetTextSize

Syntax: cheadle_api.Draw.GetTextSize(text, font = nil)

• Parameters:
  • text (string)
  • font (string, optional): Font name registered with BuildFont.
• Returns: Two numbers (width, height) in pixels.

cheadle_api.HTTP

Asynchronous HTTP client built on libcurl. All callbacks run on the main Lua thread once the request finishes — they receive the response body as a single string argument.

Only one in-flight request at a time has its callback delivered. If multiple requests finish back-to-back, only the most recent one fires its callback.

Get

Syntax:

• cheadle_api.HTTP.Get(url, callback)

• cheadle_api.HTTP.Get(url, headers, callback)

• Parameters:

  • url (string)
  • headers (table, optional): String → string map of headers.
  • callback (function): function(body) — called with the response body.

Post

Syntax: cheadle_api.HTTP.Post(url, type, params, headers, callback)

• Parameters:
  • url (string)
  • type (string): Currently unused; pass any string.
  • params (table): String → string map sent as form-urlencoded body.
  • headers (table): String → string map.
  • callback (function): function(body).

Put

Syntax: cheadle_api.HTTP.Put(url, data, headers, callback)

• Parameters:
  • url (string)
  • data (string): Raw request body.
  • headers (table): String → string map.
  • callback (function): function(body).

cheadle_api.pathfinder

Controls the built-in A* movement bot. The pathfinder runs on a worker thread and replays its plan tick-by-tick into the player’s cmd.

SetTarget

Syntax:

• cheadle_api.pathfinder.SetTarget(vector)

• cheadle_api.pathfinder.SetTarget(x, y, z)

• Description: Sets a destination and queues a replan.

SetTargetToCrosshair

Syntax: cheadle_api.pathfinder.SetTargetToCrosshair()

• Description: Targets the world point under the player’s crosshair.

ClearTarget

Syntax: cheadle_api.pathfinder.ClearTarget()

Replan

Syntax: cheadle_api.pathfinder.Replan()

• Description: Forces an immediate replan from the current position.

GetTarget

Syntax: cheadle_api.pathfinder.GetTarget() → Vector | nil

HasTarget

Syntax: cheadle_api.pathfinder.HasTarget() → boolean

IsPlaybackActive

Syntax: cheadle_api.pathfinder.IsPlaybackActive() → boolean

IsPlanning

Syntax: cheadle_api.pathfinder.IsPlanning() → boolean

• Description: True if a replan is queued, in flight, or waiting for the player to settle.

PlanFailed

Syntax: cheadle_api.pathfinder.PlanFailed() → boolean

• Description: True if the most recent plan failed to find a route.

GetExpansions

Syntax: cheadle_api.pathfinder.GetExpansions() → number

• Description: Number of A* node expansions in the most recent plan.

GetPlanSize

Syntax: cheadle_api.pathfinder.GetPlanSize() → number

GetPlaybackIndex

Syntax: cheadle_api.pathfinder.GetPlaybackIndex() → number

• Description: 1-based index of the currently-playing tick.

GetPlanTick

Syntax: cheadle_api.pathfinder.GetPlanTick(index)

• Parameters:
  • index (number): 1-based tick index.
• Returns: A table:

{
  startPos       = Vector,
  startVel       = Vector,
  startOnGround  = boolean,
  viewAngles     = Angle,
  forward        = number,
  side           = number,
  pressJump      = boolean,
  buttons        = number,
  endPos         = Vector,
  endVel         = Vector,
  endOnGround    = boolean,
}

GetPlan

Syntax: cheadle_api.pathfinder.GetPlan() → table

• Returns: 1-indexed array of tick tables (same shape as GetPlanTick).

IsEnabled / SetEnabled

Syntax:

• cheadle_api.pathfinder.IsEnabled() → boolean
• cheadle_api.pathfinder.SetEnabled(enabled)

IsAutoWalkEnabled / SetAutoWalk

Syntax:

• cheadle_api.pathfinder.IsAutoWalkEnabled() → boolean
• cheadle_api.pathfinder.SetAutoWalk(enabled)

cheadle_api.movement_sim

Lua entry points to the threaded movement simulator. All three sim functions take a params table; missing fields fall back to live player state. CreateInput builds a populated params table to start from.

The params table accepts:

CreateInput

Syntax: cheadle_api.movement_sim.CreateInput() → table | nil

• Returns: A params table populated from live player state, ready to be tweaked and passed back into the other sim functions.

SimulateTick

Syntax: cheadle_api.movement_sim.SimulateTick(params) → table | nil

• Returns: A single output table:

{
  origin   = Vector,
  velocity = Vector,
  angles   = Angle,
  grounded = boolean,
}

• Description: Runs one tick of PartialProcessMovement with the given inputs.

Simulate

Syntax: cheadle_api.movement_sim.Simulate(params, ticks = 1) → table

• Parameters:
  • ticks (number, optional): Number of ticks (clamped to [0, 10000]).
• Returns: 1-indexed array of output tables (same shape as SimulateTick).
• Description: Repeatedly steps the simulator with the same inputs. IN_JUMP is edge-latched between ticks (held jump only fires the first tick), matching engine behaviour.

Strafe

Syntax: cheadle_api.movement_sim.Strafe(params) → table

• Description: Runs the auto-bhop circle-strafe job. Expects params.yawDelta (degrees per tick) and params.timeUntilTimeout (seconds of sim time). Side move and buttons are overridden internally.
• Returns: 1-indexed array of { origin = Vector, velocity = Vector, timeRemaining = number }.

cheadle_api.ImGui

Custom ImGui windows controllable from Lua. Widgets are added to a parent Menu and respond via OnChangeFunction / SetClickFunction callbacks.

Menu

Syntax: cheadle_api.ImGui.Menu(name, window_flags = 0)

• Parameters:

  • name (string): Window name (also the unique identifier).
  • window_flags (number, optional): ImGui window flag bitfield.

• Returns: A menu object.

• Methods:

  • Menu:SetPos(x, y)
  • Menu:SetSize(w, h)
  • Menu:Close()
  • Menu:ShouldDraw(bool) — toggles visibility.
  • Menu:PaintFunction(function) — runs every frame inside the window; can call cheadle_api.DrawRect/etc. to draw into the window.

• Example:

local menu = cheadle_api.ImGui.Menu("Example Menu", 0)
menu:SetSize(400, 230)
menu:SetPos(100, 100)

local button = cheadle_api.ImGui.Button(menu, "Close")
button:SetSize(55, 30)
button:SetPos(10, 190)
button:SetClickFunction(function() menu:Close() end)

local checkbox = cheadle_api.ImGui.Checkbox(menu, "sample checkbox")
checkbox:SetPos(10, 35)
checkbox:OnChangeFunction(function()
  cheadle_api.Log("Checkbox toggled: " .. tostring(checkbox:GetChecked()))
end)

local dropdown = cheadle_api.ImGui.Dropdown(menu, "sample dropdown", { "option1", "option2" })
dropdown:SetPos(10, 70)
dropdown:OnChangeFunction(function()
  cheadle_api.Log("Dropdown: " .. dropdown:GetValue())
end)

local slider = cheadle_api.ImGui.Slider(menu, "sample slider", 0, 10)
slider:SetPos(10, 110)
slider:OnChangeFunction(function()
  cheadle_api.Log("Slider: " .. slider:GetValue())
end)

local textbox = cheadle_api.ImGui.Textbox(menu, "sample textbox")
textbox:SetPos(10, 150)
textbox:OnChangeFunction(function()
  cheadle_api.Log("Textbox: " .. textbox:GetValue())
end)

Checkbox

Syntax: cheadle_api.ImGui.Checkbox(parent, name)

• Parameters:
  • parent: A menu object returned by Menu.
  • name (string): Label.
• Methods:
  • Checkbox:SetPos(x, y)
  • Checkbox:GetChecked() → boolean
  • Checkbox:SetChecked(bool)
  • Checkbox:OnChangeFunction(callback)

Button

Syntax: cheadle_api.ImGui.Button(parent, name)

• Methods:
  • Button:SetPos(x, y)
  • Button:SetSize(w, h)
  • Button:SetClickFunction(callback)

Slider

Syntax: cheadle_api.ImGui.Slider(parent, name, min, max, format = "%d")

• Parameters:
  • min, max (number)
  • format (string, optional): printf-style format for the value display.
• Methods:
  • Slider:SetPos(x, y)
  • Slider:SetSize(w, h)
  • Slider:GetValue() → number
  • Slider:SetValue(number)
  • Slider:OnChangeFunction(callback)

Textbox

Syntax: cheadle_api.ImGui.Textbox(parent, name)

• Methods:
  • Textbox:SetPos(x, y)
  • Textbox:SetSize(w, h)
  • Textbox:GetValue() → string
  • Textbox:SetValue(string)
  • Textbox:OnChangeFunction(callback)

Dropdown

Syntax: cheadle_api.ImGui.Dropdown(parent, name, options)

• Parameters:
  • options (table): Array of strings.
• Methods:
  • Dropdown:SetPos(x, y)
  • Dropdown:SetSize(w, h)
  • Dropdown:GetValue() → string — the selected option.
  • Dropdown:SetValue(string) — select an option by its label.
  • Dropdown:OnChangeFunction(callback)

Colorpicker

Syntax: cheadle_api.ImGui.Colorpicker(parent, name)

• Methods:
  • Colorpicker:SetPos(x, y)
  • Colorpicker:GetValue() → color table { r, g, b, a }
  • Colorpicker:SetValue(color_table)
  • Colorpicker:OnChangeFunction(callback)

Hooks

The cheadle_api exposes a hook system that lets you listen to internal cheat events. You can also listen to standard Garry’s Mod hooks (except those fired purely from Lua) by name.

Hook callbacks return values where noted; otherwise the return value is ignored.

Paint

• Description: Runs every frame on the engine’s Paint event. Use the top-level DrawRect/DrawText/etc. to draw to the screen.

cheadle_api.CreateHook("Paint", "id", function()
  cheadle_api.DrawRect(10, 10, 100, 100, { r = 255, g = 0, b = 0 })
end)

PaintTraverse

• Description: Same as Paint. Kept for backwards compatibility.

EngineDrawing

• Description: Lets Lua draw into the steam overlay. You can use regular surface.* and cam.* functions.

cheadle_api.CreateHook("EngineDrawing", "id", function()
  cam.Start2D()
    surface.SetDrawColor(255, 0, 0, 255)
    surface.DrawRect(260, 260, 100, 30)
  cam.End2D()
end)

Pre_PreSend

• Parameters:
  • cmd (CUserCmd)
• Description: Fires immediately before the cheat processes its outgoing CreateMove work. Use this when you want to modify the command before silent aim, nospread, etc. Predicted if engine prediction is enabled — be careful with movement edits.

cheadle_api.CreateHook("Pre_PreSend", "id", function(cmd)
  -- modify cmd
end)

Post_PreSend

• Parameters:
  • cmd (CUserCmd)
• Description: Fires after the cheat’s outgoing processing (silent aim / nospread / etc.) but before the packet is sent. Use this as the canonical override point for your own movement / aim work. Predicted if engine prediction is enabled.

Pre_FreecamRender

• Parameters:
  • pos (Vector): Current freecam position.
  • ang (Angle): Current freecam angles.
• Returns: (Vector, Angle) — the position and angle to actually render the freecam from. Returning anything else (including a single value or nil) leaves the freecam render unchanged.
• Description: Fires every frame the freecam is active, before the freecam scene render. Lets Lua transform the freecam pose without replacing the freecam itself — input handling and the underlying position are untouched.

cheadle_api.CreateHook("Pre_FreecamRender", "orbit", function(pos, ang)
  local target = cheadle_api.GetAimbotTarget()
  if not target then return end

  local origin = target:GetPos() + Vector(0, 0, 60)
  local newPos = origin + Vector(math.cos(CurTime()), math.sin(CurTime()), 0) * 80
  local newAng = (origin - newPos):Angle()
  return newPos, newAng
end)

Net_Receive

• Parameters:
  • name (string): Net message name.
• Description: Fires before net.Incoming runs the server’s net message, so you can observe (but not modify) incoming traffic before regular Lua sees it.

Net_ShouldSend

• Parameters:
  • name (string): Name of the outgoing net message (resolved from g_Write).
• Returns: Return false to block the call to net.SendToServer().

cheadle_api.CreateHook("Net_ShouldSend", "id", function(name)
  if name == "bad_ac_example" then return false end
end)

SendNetMsg

• Parameters:
  • name (string): Source message name (e.g. clc_Move, net_Tick, net_StringCmd).
  • reliable (boolean)
• Returns: Return true to drop the message. Fires on every Source-level INetChannel::SendNetMsg.

Aimbot_IgnoreEntities

• Description: Fires once per aimbot pass, before targets are filtered. Call BlockTraceEntity and / or BlockAimbotTarget to add entries to the aimbot skip lists. The lists are cleared at the start of every pass.

cheadle_api.CreateHook("Aimbot_IgnoreEntities", "id", function()
  local tr = LocalPlayer():GetEyeTrace()
  local ent = tr.Entity

  if IsValid(ent) then
    cheadle_api.BlockTraceEntity(ent)
    if ent:IsPlayer() then
      cheadle_api.BlockAimbotTarget(ent)
    end
  end
end)

ESP_ShouldDrawEntity

• Parameters:
  • ent (Entity)
• Returns: Return false to skip drawing this entity.

ESP_ShouldDrawPlayer

• Parameters:
  • ent (Entity)
• Returns: Return false to skip drawing this player.

ESP_PlayerName

• Parameters:
  • ent (Player)
• Returns: Return a string to override the player’s displayed name on the ESP.

ESP_PlayerUsergroup

• Parameters:
  • ent (Player)
• Returns: Return a string to override the displayed usergroup on the ESP.

Entity_DrawExtra

• Parameters:
  • ent (Entity)
• Description: Fires after the entity’s main ESP draw. Inside this hook, DrawExtra attaches lines to this entity.

Player_DrawExtra

• Parameters:
  • ent (Entity)
• Description: Fires after the player’s main ESP draw. Inside this hook, DrawExtra attaches lines to this player.

Pre_AnimUpdate

• Parameters:
  • ent (Entity)
• Description: Fires before the cheat’s own animation-state update for an entity. Use it to read or modify pose parameters and animation layers.

Pre_BuildBones

• Parameters:
  • ent (Entity)
• Description: Fires before the cheat’s bone build for an entity. Pose parameters and render angles can be set here for resolver work; they will be reset after the bones build, so this does not permanently modify the entity.

cheadle_api.CreateHook("Pre_BuildBones", "weird-roll-resolver", function(ply)
  local eyeAngles = ply:EyeAngles()
  if math.abs(eyeAngles[3]) == 180 then
    ply:SetPoseParameter("aim_pitch", -eyeAngles[1])
    ply:SetRenderAngles(Angle(0, math.NormalizeAngle(eyeAngles[2] - 180), 0))
  end
end)

Pre_NoSpread

• Parameters:
  • cmd (CUserCmd)
• Returns: Return false to skip the cheat’s nospread handling for this tick.

KeyPressed

• Parameters:
  • button (number): Source ButtonCode_t (use cheadle_api.Input.ButtonToVirtual to convert to a Windows VK).
• Description: Fires when a key is pressed via the engine input system. Suppressed while the freecam is active or while a cheat keybind is consuming the key.

KeyReleased

• Parameters:
  • button (number): Source ButtonCode_t.
• Description: Fires when a key is released. Same suppression rules as KeyPressed.

PreventKey

• Parameters:
  • button (number): Source ButtonCode_t.
• Returns: Return true to swallow the press / release before the engine sees it. Any other return value passes the input through.
• Description: Fires alongside KeyPressed and KeyReleased.

Key_Change

• Parameters:
  • key (number): Windows virtual-key code.
  • down (boolean): true for a down event, false for an up event.
• Description: Fires once per state change, polled from GetAsyncKeyState for keys 0x01..0xFE. Unlike KeyPressed, it is not gated by the engine input system, so it fires even when the cheat menu is consuming input.

cheadle_api.CreateHook("Key_Change", "id", function(vk, down)
  cheadle_api.Log(input.GetKeyName(cheadle_api.Input.VirtualToButton(vk)) .. " " .. tostring(down))
end)