Getting started
Put .lua
files in C:\lightmoon\lua
. Scripts are discovered but never executed automatically. Enable a script in the Lua tab and save the current config to make that script active for that config.
callbacks.add("paint", function()
render.text(24, 24, "hello from lua", 235, 242, 255, 255)
end)
Callbacks
| Event | When it runs |
|---|---|
paint
|
Every rendered frame. Use it for custom ImGui windows and overlay drawing. |
create_move
|
For the current command. This is the only callback where cmd.*
is available.
|
post_prediction | Runs after the existing prediction pass. Use game.prediction() here. |
game_event
|
Receives the event name as its only argument. |
unload
|
Runs before the Lua state is destroyed. Use it for script cleanup. |
callbacks.add("game_event", function(event_name)
if event_name == "player_hurt" then
client.log("hit registered")
end
end)
Styled overlays
The overlay
namespace is the preferred API for script windows. It hides raw ImGui setup and always applies the Lightmoon panel style. Overlay calls are valid only in paint
.
| Function | Result |
|---|---|
overlay.begin_panel(id,title,x,y,width,height)
|
Starts a fixed styled panel and returns visibility. |
overlay.end_panel()
|
Ends the current panel. |
overlay.text(text)
, overlay.text_colored(text,r,g,b,a)
|
Styled text. |
overlay.button(label,width)
|
Returns true when clicked. |
overlay.checkbox(label,value)
|
Returns changed,value
.
|
overlay.slider_float(...)
, overlay.slider_int(...)
|
Returns changed,value
.
|
overlay.color(label,r,g,b,a)
|
Returns changed,r,g,b,a
.
|
overlay.separator()
, overlay.same_line(spacing)
|
Layout helpers. |
Render
Drawing calls are valid only in paint
. Colors use RGBA bytes from 0
to 255
. Point arrays accept {x=...,y=...}
or {x=...,y=...,z=...}
tables.
| Function | Result |
|---|---|
render.text(...)
, render.text_outline(...)
, render.text_size(text)
|
Text primitives and measurement. |
render.load_font(path,size), render.push_font(handle), render.pop_font() |
Script-owned TTF/OTF fonts. Size 8..96, maximum 8 fonts per script, 8 MiB per file, font stack depth 32. |
render.load_image(path), render.load_image_url(url) |
Script-owned PNG/JPG/JPEG images. URL loading is asynchronous and cached per script. |
render.image_size(handle), render.image(handle,x,y,w,h,r?,g?,b?,a?), render.image_uv(handle,x,y,w,h,u1,v1,u2,v2,r?,g?,b?,a?) |
Queries or draws a ready image. Maximum 16 image assets per script; local image limit 8 MiB and 2048×2048 / 4,194,304 pixels. |
render.measure_text(text) | Alias for text measurement. |
render.line(...)
, render.polyline(points,...)
|
Lines and long recorder paths. |
render.rect(...)
, render.rect_filled(...)
, render.rect_gradient(...)
|
Outlined, filled and gradient rectangles. |
render.circle(...)
, render.circle_filled(...)
|
Circle primitives. |
render.triangle(...)
, render.triangle_filled(...)
, render.polygon_filled(points,...)
|
Triangles and convex filled polygons. |
render.world_line(from,to,...)
, render.world_polyline(points,...)
|
Projected 3D paths. |
render.world_circle(...)
, render.world_sphere(...)
, render.world_box(...)
|
Projected world geometry. |
render.world_marker(position,...)
, render.world_text(position,...)
|
World-space markers and labels. |
render.screen_size()
|
Returns width, height
.
|
render.fade_alpha(current, target, speed=10)
|
Returns a frame-rate-independent alpha step in 0.0..1.0
. Paint only.
|
render.push_clip_rect(x1,y1,x2,y2,intersect=true)
|
Pushes a screen clip rectangle and returns success. Paint only; maximum depth is 32. |
render.pop_clip_rect()
|
Pops one matching clip rectangle and returns success. Leaked clips are removed after each callback, including errors. |
local alpha = 0.0
callbacks.add("paint", function()
alpha = render.fade_alpha(alpha, game.is_in_game() and 1.0 or 0.0, 12.0)
if render.push_clip_rect(20, 20, 260, 90) then
render.rect_filled(20, 20, 260, 90, 14, 17, 25, math.floor(220 * alpha))
render.pop_clip_rect()
end
end)
Game and w2s
Player and camera functions return copied snapshots. They never expose engine pointers, so a script can retain the returned tables safely.
| Function | Result |
|---|---|
game.is_in_game()
|
Whether a local game session is active. |
game.is_thirdperson()
|
Effective third-person state from the latest camera snapshot; false
before a valid snapshot exists.
|
game.camera_position()
|
Latest final camera origin as {x,y,z}
, or nil
before the view hook produces a valid snapshot.
|
game.camera_angles()
|
Latest final camera angles as {x,y,z}
, or nil
before a valid snapshot exists.
|
game.world_to_screen({x,y,z})
/ game.w2s({x,y,z})
|
Returns visible, screen_x, screen_y
.
|
game.local_player()
|
Local live player snapshot or nil
.
|
game.player(index)
|
One valid live player snapshot or nil
.
|
game.players()
|
An array of all valid live player snapshots. Enumeration uses the same entity-list/controller path as ESP and does not use get_max_clients
.
|
game.player_bone(index, bone_index)
|
Copied {x,y,z}
or nil
for an invalid/dead player, invalid bone, unavailable skeleton or invalid position. The index from game.local_player()
is supported.
|
game.round() | Returns a copied round/game-rules snapshot or nil. |
game.prediction() | Returns copied pre/post prediction data; intended for post_prediction. It does not run a second simulation. |
game.tick_count()
, game.interval_per_tick()
|
Current global tick data. |
Camera and local head
callbacks.add("paint", function()
local camera = game.camera_position()
local player = game.local_player()
if not camera or not player then return end
local head = game.player_bone(player.index, constants.bone_head)
if head then render.world_line(camera, head, 108, 145, 255, 210, 1.0) end
end)
Player snapshot
Every player snapshot contains index
, is_local
, name
, health
, max_health
, team
, armor
, ping
, flags
, on_ground
, is_scoped
, is_defusing
, has_helmet
, has_defuser
, weapon_definition
, shots_fired
, origin
, eye_position
, velocity
and aim_punch
.
Movement snapshot
player.movement
includes stamina
, surface_friction
, fall_velocity
, max_speed
, duck_amount
, duck_speed
, ducking
, ducked
, desires_duck
, analog movement values and modern_jump
. The latter exposes jump press ticks/fractions plus last landing tick, fraction and vertical velocity.
Storage
storage
keeps small typed values in the current config. Keys are automatically namespaced by the active script's stable ID, so scripts cannot overwrite each other. Valid keys contain 1-96 ASCII letters, digits, _
, -
or .
; each script may store at most 256 values and strings are limited to 255 bytes. Updating an existing key remains allowed at the limit; adding another key returns false.
| Function | Result |
|---|---|
storage.get_number(key)
|
Stored finite number, or nil
when missing or stored with another type.
|
storage.set_number(key, value)
|
Stores a finite number and returns success. |
storage.get_bool(key)
|
Stored boolean, or nil
.
|
storage.set_bool(key, value)
|
Stores a strict Lua boolean and returns success. |
storage.get_string(key)
|
Stored string, or nil
.
|
storage.set_string(key, value)
|
Stores a string up to 255 bytes and returns success. |
local launches = storage.get_number("launches") or 0
storage.set_number("launches", launches + 1)
storage.set_bool("compact_hud", true)
storage.set_string("profile", "lunar")
Create move
cmd.*
is valid only inside create_move
. The API deliberately exposes values, not pointers. This keeps recorder-style scripts safe across commands.
| Function | Result |
|---|---|
cmd.get_number()
, cmd.get_buttons()
|
Current command data. |
cmd.set_buttons(buttons)
, cmd.set_button(button, pressed)
|
Replaces all buttons or updates one button state. |
cmd.get_view_angles()
|
Returns an {x,y,z}
table or nil
.
|
cmd.set_view_angles({x,y,z})
|
Updates command angles. |
cmd.get_yaw() | Returns current command yaw or nil. |
cmd.set_yaw(yaw) | Sets finite command yaw and returns success. |
cmd.add_subtick_move(forward,side,yaw_delta,pitch_delta,when) | Adds a native subtick move entry. Analog deltas clamp to -1..1, yaw to -180..180, pitch to -89..89 and when to 0..0.999. |
cmd.add_subtick_yaw(yaw_delta,when) | Adds a native subtick yaw-delta entry; yaw clamps to -180..180 and when to 0..0.999. |
cmd.get_analog_move()
|
Returns forward and side movement values. |
cmd.set_analog_move(forward, side, when)
|
Adds a movement subtick and returns success. |
cmd.add_subtick_button(button, pressed, when)
|
Adds a button subtick and returns success. |
Input and client
| Function | Result |
|---|---|
input.is_key_down(virtual_key)
|
True while the key is held. |
input.is_key_pressed(virtual_key)
|
Reads the Win32 press-transition bit. It is consumed by GetAsyncKeyState; scripts must not assume a paint-frame lifetime. |
input.mouse_position()
, input.is_mouse_down(button)
|
Mouse coordinates and held button state. |
client.time()
, client.frame_time()
, client.fps()
|
Frame timing values. |
client.context()
|
Current Lua execution context: loading
, paint
, create_move
, game_event
, unload
, ffi_cleanup
or none
.
|
client.is_menu_open()
, client.log(message)
|
Menu state and Lua log output. |
utils.clamp(value,min,max)
, utils.lerp(from,to,amount)
|
Math helpers. |
Vectors and Color
API v2: callable value classes. Plain coordinate tables remain accepted; native vec3 snapshots now have vector methods too.
| Class / function | Behavior |
|---|---|
vec2(x?,y?), vec3(x?,y?,z?), vec4(x?,y?,z?,w?) | Zero defaults; also accept named/indexed tables. Aliases: Vector2/Vector3/Vector4. Constructors reject NaN/Inf. |
vecN.new(...), vecN.zero(), vecN.is(value) | Construction and type checks. Fields x/y/z/w. Arithmetic +, -, *, / accepts components or scalars; unary -, equality and tostring supported. |
v:clone(), v:unpack(), v:length(), v:length_sqr(), v:length_2d() | Copy, components and lengths. |
v:dot(other), v:distance(other), v:distance_sqr(other), v:lerp(other,t), v:is_zero(epsilon?) | Vector calculations. Default zero epsilon is 1e-6. |
v:normalized(), v:normalize() | First returns a new vector; second mutates and returns previous length. Zero vectors stay zero. |
vec3:cross(other), vec3:to_angles() | Cross product and pitch/yaw/0 in degrees. |
color(r?,g?,b?,a?), color.new(...), color.is(v) | Alias Color. Named/indexed table input accepted. RGBA 0-255, defaults 255, clamped. |
color.from_hex(s), color.from_hsv(h,s,v,a?), color.from_normalized(r,g,b,a?) | HEX RRGGBB/RRGGBBAA with optional #; HSV/normalized inputs use 0-1, alpha defaults to 1. |
c:clone(), c:unpack(), c:unpack_normalized(), c:with_alpha(a), c:lerp(other,t), c:to_hex(), c:to_u32() | Render RGBA vs normalized menu RGBA, new alpha/interpolated colors, #RRGGBBAA and unsigned ImGui ABGR packing. |
utils.normalize_yaw(yaw), utils.angle_delta(a,b), utils.calc_angle(from,to), utils.angle_forward(angles) | Angle helpers in degrees, returning vectors where appropriate. |
utils.smoothstep(a,b,x), utils.remap(v,a,b,c,d,clamped?), utils.approach(current,target,step), utils.round(v,digits?) | Interpolation/remapping/smoothing helpers. |
local origin = vec3(10,20,30)
local direction = (vec3(30,20,30)-origin):normalized()
local tint = color.from_hex("#B478FFFF")
-- Multi-return unpack expands only in the final argument position:
callbacks.add("paint", function() render.text(20,20,"Hello",tint:unpack()) end)
Commands and clantags
| Function | Result / rules |
|---|---|
client.api_version(), client.script_name() | API version 3 and stable script filename/id. |
client.exec(command), client.exec_command(command) | Boolean: queued for the game-frame buybot command path, not server acknowledgement. Max 512 bytes, one accepted command/script/250 ms, queue cap 32, expiry 2 seconds; game must be active to execute. |
client.say(text,team?) | Safely queues say/say_team; team defaults false. Up to 240 bytes, no quotes/command delimiters. Do not spam from paint. |
clantag.set(tag,animated?,interval_ms?), client.set_clantag(...) | Boolean: script override of the existing [tag] player-name-prefix system, not a new server clan-tag field. Defaults false/500 ms; 1-32 UTF-8 bytes; interval clamped to 250-2000 ms. |
clantag.get(), clantag.clear() | Calling script's active tag or nil; clear releases ownership. One script owns the override. Disable/reload/unload/failed loading release it; UI settings resume or original name restores, subject to engine throttling. UI config is untouched. |
clantag.set("moon",true,500)
-- Call once from a button/key/event, not every frame:
-- client.say("hello",false)
callbacks.add("unload",function() clantag.clear() end)
Filesystem and assets
Private data lives under C:\lightmoon\lua\.data\<hex-encoded stable script filename>. Write/create/list/delete affect only that script. Renaming a script changes its namespace. Reads check private data first, then legacy shared Lua-root files except .data; asset paths stay shared and read-only.
| Function | Result |
|---|---|
filesystem.create_directory(path) | Creates private data directories (not shared assets). |
filesystem.directory_exists(path) | Checks for a sandbox directory. |
filesystem.file_exists(path) | Checks for a sandbox regular file. |
filesystem.read_file(path) | Returns binary file contents, including embedded NUL bytes, or nil on failure. Maximum size: 4 MiB. |
filesystem.write_file(path,bytes), filesystem.append_file(path,bytes) | Boolean. Creates parents automatically; 4 MiB/file and 16 MiB total/script. Binary-safe. Writes are not transactional. |
filesystem.remove_file(path) | Deletes only a private regular file; no recursive delete. |
filesystem.list(path?) | At most 256 sorted private-directory names, or nil; default path is private root. |
filesystem.read_json(path,fallback?), filesystem.write_json(path,value) | Convenient config persistence using existing JSON limits: 1 MiB, bounded depth/entries. |
local cfg = filesystem.read_json("configs/options.json", {enabled=true})
filesystem.write_json("configs/options.json",cfg)Audio
| Function | Result |
|---|---|
audio.load(path) | Loads a sandboxed WAV file during script loading and returns a sound handle or nil. |
audio.play(sound_handle, volume?) | Starts an independent playback and returns a playback handle or nil. |
audio.stop(playback_handle) | Stops an active playback owned by the calling script. |
audio.load uses the same sandbox path rules and 4 MiB file limit as filesystem.read_file. Supported files are RIFF/WAVE mono or stereo PCM (8/16/24/32-bit) and 32-bit IEEE float at 8,000-192,000 Hz. Compressed WAV, MP3, OGG and other formats return nil. audio.load is available only while the script is loading. audio.play defaults to volume 1.0 and clamps it to 0.0-1.0. Calls can overlap. Each script is limited to 32 sounds and 24 active playbacks. Handles are script-owned; invalid, finished or stopped playback handles fail. Script reload, disable and unload stop playbacks and release sounds.local hit_sound = audio.load("assets/hitsound.wav")
callbacks.add("game_event", function(name)
if name ~= "player_hurt" or not hit_sound then return end
local attacker = event.player("attacker")
local local_player = game.local_player()
if attacker and local_player and attacker.index == local_player.index then
audio.play(hit_sound, 0.55)
end
end)
HTTP
Asynchronous requests for public HTTP(S) URLs. file://, localhost, loopback and private IPv4 destinations are rejected; redirects are disabled.
| Function | Result |
|---|---|
http.get(url) | Starts a request and returns an opaque handle or nil. |
http.post(url, body, headers?) | Starts a POST request. The optional headers table contains string key/value pairs. |
http.request(method, url, body?, headers?) | Starts a GET, POST, PUT, PATCH or DELETE request. |
http.status(handle) | "pending", "done", "failed" or nil. |
http.response(handle) | Completed { status, body, content_type, error, headers } table or nil. Response header names are lowercase. |
http.cancel(handle) | Cancels and invalidates the request handle. |
nil when either limit is reached. Cancel completed handles when no longer needed.local handle = http.post("https://example.com/api", '{"state":"playing"}', {
["Content-Type"] = "application/json"
})
System
Windows system integration.
| Function | Result |
|---|---|
system.media_session() | Current media session metadata table or nil if no active session. Returns a table with title, artist, album, source, playback_state, position, duration, artwork, artwork_width, artwork_height, and artwork_revision. Text fields are strings; numeric fields and artwork handle are integers or nil. |
"playing", "paused", "stopped", "closed", or "unknown". Position and duration are in seconds. While playing, position advances from the latest native timeline anchor using a monotonic clock; it freezes while paused or stopped and re-anchors on playback changes, seeks, track changes and session changes. Artwork is a render image handle suitable for render.image(), or nil if no artwork is available or currently loading. Artwork_revision increments when the visible artwork changes. Returns nil when no valid media session exists on the system.Schema and runtime safety
| Function | Result |
|---|---|
schema.field_offset(class_name,field_name,module_name="client.dll") | Live schema field offset or nil. |
native.track_callback(callback,cleanup) | Legacy retention helper for a callback and cleanup function; returns an integer handle. Does not grant FFI/native access. |
native.untrack_callback(handle) | Releases a retained callback handle. |
schema.field_offset(class_name, field_name, module_name)
returns a live schema field offset or nil
. Prefer safe snapshots whenever possible.
local offset = schema.field_offset("CCSPlayer_MovementServices", "m_flStamina")
client.log("stamina offset: " .. tostring(offset))
ImGui
All imgui functions are paint-only. They return value types only and do not expose native pointers. Unclosed window, child, style, disabled, tooltip and item-width scopes are unwound after each callback.
| Function | Result |
|---|---|
imgui.set_next_window_pos(x,y,condition?), imgui.set_next_window_size(width,height,condition?) | Next-window placement and sizing. |
imgui.begin(title,flags?), imgui.end_window() | Window scope. |
imgui.begin_child(id,width?,height?,border?,flags?), imgui.end_child() | Child scope. |
imgui.text(text), imgui.text_colored(r,g,b,a?,text) | Text. |
imgui.button(label,width?,height?) | Button; returns click state. |
imgui.checkbox(label,value) | Returns changed and value. |
imgui.slider_float(label,value,min,max), imgui.slider_int(label,value,min,max) | Sliders. |
imgui.color_edit4(label,r,g,b,a?) | Returns changed and RGBA. |
imgui.input_text(label,value,max_length?,enter_returns_true?,flags?) | Returns changed, value, submitted. UTF-8 text, Cyrillic and clipboard input are handled by Dear ImGui. |
imgui.input_text_multiline(label,value,width?,height?,max_length?,flags?) | Returns changed, value. |
imgui.selectable(label,selected?,flags?,width?,height?), imgui.combo(label,index,items) | imgui.combo returns changed,index. Items must be an array of 1-128 strings (up to 512 bytes each); the returned index is zero-based and is clamped to the item range. |
imgui.progress_bar(fraction,width?,height?,overlay?), imgui.dummy(width,height), imgui.indent(width?), imgui.unindent(width?) | Layout widgets. |
imgui.begin_disabled(disabled?), imgui.end_disabled(), imgui.begin_tooltip(), imgui.end_tooltip(), imgui.set_tooltip(text) | Paired disabled and tooltip scopes. |
imgui.is_item_hovered(flags?), imgui.is_item_active(), imgui.is_item_focused(), imgui.is_item_clicked(button?), imgui.set_keyboard_focus_here(offset?) | Item state and keyboard focus. |
imgui.get_scroll_y(), imgui.get_scroll_max_y(), imgui.set_scroll_y(y), imgui.set_scroll_here_y(ratio?) | Current-window scrolling. |
imgui.get_window_pos(), imgui.get_window_size(), imgui.get_content_region_avail() | Current-window dimensions. |
imgui.push_item_width(width), imgui.pop_item_width(), imgui.set_next_item_width(width) | Item width control. |
imgui.separator(), imgui.same_line(offset?,spacing?), imgui.spacing() | Layout helpers. |
imgui.push_style_color(index,r,g,b,a?), imgui.pop_style_color(count?) | Legacy style-color stack. |
imgui.push_style_var_float(index,value), imgui.push_style_var_vec2(index,x,y), imgui.pop_style_var(count?) | Style-variable stack. |
local chat = ""
callbacks.add("paint", function()
local open = imgui.begin("Chat")
if open then
local changed, value, submitted = imgui.input_text("##message", chat, 2048, true)
if changed then chat = value end
if submitted and chat ~= "" then
chat = ""
imgui.set_keyboard_focus_here()
end
end
imgui.end_window()
end)
Constants
Button and player-flag values are exposed through constants
. Common names: in_jump
, in_duck
, in_attack
, in_attack2
, in_forward
, in_back
, in_moveleft
, in_moveright
, in_use
, fl_onground
, fl_ducking
.
Trace mask: constants.mask_shot.
Bones: bone_pelvis
, bone_spine_0
, bone_spine_1
, bone_spine_2
, bone_neck
, bone_head
, bone_left_hand
, bone_right_hand
, bone_left_foot
, bone_right_foot
.
ImGui helpers: imgui_col_text
, imgui_col_window_bg
, imgui_col_button
, imgui_col_button_hovered
, imgui_col_button_active
, imgui_cond_always
, imgui_cond_first_use_ever
, imgui_window_no_title_bar
, imgui_window_no_resize
, imgui_window_always_auto_resize
.
Examples
Styled overlay panel
local enabled = true
local radius = 120.0
callbacks.add("paint", function()
if overlay.begin_panel("playground", "Lua playground", 60, 180, 300, 150) then
local changed
changed, enabled = overlay.checkbox("Enabled", enabled)
changed, radius = overlay.slider_float("Radius", radius, 10.0, 300.0)
overlay.separator()
overlay.text_colored("Your own script window", 0.45, 0.72, 1.0, 1.0)
end
overlay.end_panel()
end)
World marker with w2s
callbacks.add("paint", function()
local player = game.local_player()
if not player or not player.origin then return end
local point = { x = player.origin.x, y = player.origin.y, z = player.origin.z + 84.0 }
local visible, x, y = game.world_to_screen(point)
if visible then
render.circle_filled(x, y, 4, 108, 145, 255, 230)
render.text_outline(x + 8, y - 7, "local", 240, 244, 255, 255, 0, 0, 0, 220)
end
end)
Command recorder foundation
local recorded = {}
callbacks.add("create_move", function()
local angles = cmd.get_view_angles()
if not angles then return end
if input.is_key_pressed(0x75) then -- F6
recorded[#recorded + 1] = { buttons = cmd.get_buttons(), angles = angles }
client.log("recorded command " .. cmd.get_number())
end
-- A playback script can call cmd.set_view_angles(frame.angles),
-- cmd.set_button(...) and cmd.set_analog_move(...) here.
end)
Read-only ConVars and world traces
The convar
namespace copies read-only values only; it never exposes a ConVar pointer or a setter. Names must contain 1-127 ASCII letters, digits, _
, -
or a dot.
| Function | Result |
|---|---|
convar.exists(name)
|
True when the named ConVar can be found safely. |
convar.get_bool(name)
, convar.get_int(name)
, convar.get_float(name)
|
Copied engine value, or nil
for invalid names, unavailable interfaces, missing values or transition/shutdown failures.
|
trace.line(start,finish,options)
|
Copied line trace result or nil
.
|
trace.hull(start,finish,mins,maxs,options)
|
Copied hull trace result or nil
.
|
Trace options are { mask?: integer, skip_local?: boolean }
; the default mask is constants.mask_shot
. Trace calls require an active game, reject non-finite vectors and never expose engine, entity or trace pointers. A result has hit
, fraction
, start_position
, end_position
, normal
and all_solid
. start_solid
and entity/player IDs are intentionally omitted because the verified project trace layout does not provide them safely.
local gravity = convar.get_float("sv_gravity")
if game.is_in_game() then
local from = game.camera_position()
local player = game.local_player()
if from and player then
local hit = trace.line(from, player.eye_position, { skip_local = true })
if hit and hit.hit then client.log("camera ray hit") end
end
end
Entity snapshots
game.entities() returns copied non-player entity snapshots. game.entities_by_class(class_name) performs an exact class-name filter during enumeration. Each snapshot contains index, class_name and origin when a valid scene origin is available. Both return an empty list when the game or entity system is unavailable.
JSON
json.encode(value) returns JSON text or nil,error. json.decode(text) returns a Lua value or nil,error. JSON text is limited to 1 MiB; nesting is limited to 32 levels and arrays/objects to 256 entries. Unsupported Lua values, recursive tables and non-finite numbers are rejected.
Typed game events
event.get_bool(key)
, event.get_int(key)
, event.get_float(key)
and event.get_string(key)
return copied typed values only while a game_event
callback is executing. Outside that callback, for invalid keys, unavailable getters or missing values they return nil
. The event object is never retained or exposed to Lua. As with the engine getter API, a field that exactly equals the internal missing sentinel cannot be distinguished from a missing field.
event.player_index(key) resolves a userid field to its controller index. event.player(key) returns a copied player snapshot. Both are valid only during the current game_event callback and return nil when resolution fails.
callbacks.add("game_event", function(name)
if name ~= "player_hurt" then return end
local damage = event.get_int("dmg_health")
local weapon = event.get_string("weapon")
if damage and weapon then client.log(weapon .. ": " .. damage) end
end)
Input deltas and timing
input.is_mouse_pressed(button)
, input.mouse_delta()
and input.mouse_wheel()
are paint-only values from the existing ImGui input frame. Mouse delta is the cursor displacement since the prior ImGui frame; wheel is the current-frame wheel delta. client.time_seconds()
is monotonic GetTickCount64
expressed in seconds; it is available in every Lua context. The existing client.time()
remains the same clock in integer milliseconds.
Movement snapshots additionally expose copied speed_2d
, velocity_z
, water_level
, move_type
and ground_entity_index
. Non-finite source values become nil
; the ground index is nil
while no valid ground entity exists.
nil
, false
, 0
or empty result safely.
Native config and keybinds
config.current()
returns the latest successfully loaded or saved config name. config.list()
returns copied names only, never filesystem paths. settings.list()
and settings.get(id)
return copied native setting snapshots; keybinds.list()
returns copied bind snapshots.
config.current() -> string
config.list() -> string[]
settings.list() -> setting[]
settings.get(id) -> setting | nil
settings.set_bool(id, value) -> boolean
settings.set_int(id, value) -> boolean
settings.set_float(id, value) -> boolean
settings.set_color(id, { r, g, b, a }) -> boolean
keybinds.list() -> keybind[]
Native IDs use existing persisted paths such as aimbot.enabled
, visuals.thirdperson
, misc.edge_bug
and colors.ui_color
. A setting snapshot has id
, label
, category
, type
, value
and numerical min
/max
where applicable. Supported types are bool
, int
, float
and color
.
Setters only accept registered IDs and matching types; number values are range-clamped, NaN/Inf is rejected, and colors require four finite components in 0..1
. They update the same live config state as the native menu but never save a file: a later normal Save Config persists them.
A keybind has id
, label
, configured
, active
, key
and mode
. Modes are 0 Hold
, 1 Toggle
, 2 Always
. configured
is the feature setting; active
is the current native keybind result. They are deliberately separate.
local setting = settings.get("visuals.thirdperson")
if setting then settings.set_bool("visuals.thirdperson", not setting.value) end
for _, bind in ipairs(keybinds.list()) do
if bind.configured and bind.active then
render.text(20, 20, bind.label)
end
end
HUD snapshots
game.spectators()
returns copied observer snapshots: index
, name
, target_index
, is_watching_local
, is_watching_pov
and native observer_mode
. The local pawn's valid observer target becomes the current POV target; otherwise it is the local pawn. Only candidates watching that POV target are listed. Outside an active game the result is empty.
Every player snapshot now has weapon
: copied definition
, VData name
, current clip
, nullable max_clip
, and reloading
. No weapon pointer is exposed. Reserve ammo is omitted because the project has no verified safe source.
render.text_aligned(x,y,text,horizontal,vertical,r,g,b,a)
draws from an anchor using left|center|right
and top|center|bottom
; it is paint-only and preserves existing text APIs.
for _, spec in ipairs(game.spectators()) do
if spec.is_watching_local then render.text_aligned(20, 80, spec.name, "left", "top") end
end
API 3: Buttons, timers and indicators
menu.add_button(tab, id, label, callback) -> boolean
menu.set_visible(id, visible) -> boolean
menu.set_disabled(id, disabled) -> boolean
menu.set_tooltip(id, text) -> boolean
timer.after(seconds, callback) -> handle | nil, reason?
timer.every(seconds, callback) -> handle | nil, reason?
timer.cancel(handle) -> boolean
timer.clear()
timer.pending() -> integer
client.notify(message, seconds? = 3, tint?: color) -> boolean, reason?
Register native buttons during loading. Their callbacks run on the next paint dispatch, not during menu drawing; callback errors disable the button. IDs are script-owned, presentation is runtime-only, unload discards queued clicks. Timers use monotonic seconds, pass their handle to callbacks, and run in paint: 64 pending/script, 32 due callbacks/frame, after 0..86400 seconds, every 0.01..86400. Repeats coalesce missed intervals. Errors cancel/log the timer; reload/unload removes it. Notifications are top-right cards, 1..256 UTF-8 bytes, 0.1..10 seconds, at most 8 pending/script.
animation.ease(name, t) -> number
animation.new(number | vec2 | vec3 | vec4 | color) -> animation
animation:value() -> value
animation:active() -> boolean
animation:set(target, seconds, easing? = "smooth") -> animation
animation:reset(value) -> animation
Animation values are copied; retargeting starts from the current interpolated value and preserves its type. Duration: 0..86400 seconds. Easings: linear, in_quad, out_quad, in_out_quad, smooth, out_cubic, out_back. Color interpolation clamps channels.
render.text(position: vec2, text, tint?: color)
render.line(from: vec2, to: vec2, tint?: color, thickness?)
render.rect(min: vec2, max: vec2, tint?: color, rounding?, thickness?)
render.rect_filled(min: vec2, max: vec2, tint?: color, rounding?)
render.circle(center: vec2, radius, tint?: color, segments?, thickness?)
render.circle_filled(center: vec2, radius, tint?: color, segments?)
settings.value(id) -> value | nil
keybinds.get(id) -> keybind | nil
game.weapon() -> weapon | nil
rage.state() -> state | nil
Legacy numeric render signatures are unchanged; rendering remains paint-only. settings.value unwraps settings.get, keybinds.get searches copied native bind snapshots. game.weapon returns the local weapon snapshot; player.weapon also gains base_damage, range, range_modifier, armor_ratio, headshot_multiplier and penetration. No native pointers are exposed.
rage.state fields: profile (0..9), enabled, active, configured_min_damage, min_damage, damage_override, hitchance, hitchance_override, force_body, force_shoot, no_spread, autowall. Effective Min Damage and Hitchance follow native profile/override state, with clamps 1..130 and 1..100. Values above 100 keep native HP-relative semantics; this is not predicted damage or a hit guarantee. force_body is the bind override, not every automatic body-selection condition. No gun/profile returns nil. Snapshot reads perform no additional scan or trace.
callbacks.add("paint", function()
local s = rage.state()
if s then render.text(vec2(30,200), string.format("DMG %.0f | HC %d%%", s.min_damage, s.hitchance), color(190,140,255)) end
end)
client.require(name) -> module
profiler.snapshot() -> { calls, errors, last_ms, average_ms, peak_ms }
profiler.reset()
client.require("helpers.math") searches private modules/helpers/math.lua, then C:\lightmoon\lua\modules\<stable-script-filename.lua>\helpers\math.lua. Names use letters, digits, underscores and nonempty dot-separated components. Source-only, maximum 4 MiB/file; caller-owned environment, cached results (nil becomes true), cycle rejection, 32 cached modules, 16 dependency levels. Main and module sources are snapshotted on launch: maximum 256 module files / 16 MiB total. Changes take effect after reload/Refresh, not during an loaded run. require("ffi") works immediately; package/arbitrary Lua path loading remain unavailable.
Profiler metrics are per script, covering host callbacks and native buttons. A callback above 10 ms triggers a warning at most once per 5 seconds. Profiling is diagnostic, not a preemptive execution limit; infinite Lua loops can still stall the game.
Script permissions
permissions.has(name) -> boolean
permissions.request(name) -> boolean
All supported script capabilities (files, commands, clantag, network, browser and FFI) are available automatically. No launch warning, permission dialog, approval scan or reload confirmation is shown. permissions.has and permissions.request return true for known capabilities in a valid script context; unknown names return false. Shutdown and normal API validation still apply.
Changing script or module source does not ask for confirmation. Main and owned module source snapshots remain source-only and bounded; changes take effect after reload/Refresh.
Disable/reload/unload close owned browser panels and cancel managed HTTP jobs; already-started image downloads may finish. Standard filesystem path/size safeguards remain, with no separate grant. filesystem.write_file, filesystem.append_file and filesystem.write_json return false, reason on failure.
Embedded browser
browser.open(url, width? = 960, height? = 600) -> handle | nil, reason?
browser.navigate(handle, url) -> boolean
browser.set_visible(handle, visible) -> boolean
browser.status(handle) -> { state, url, error } | nil
browser.close(handle) -> boolean
A native WebView2 panel owned by the game window, not an external browser tab and not a texture inside ImGui. It uses a separate STA thread/message loop and has a movable/resizable frame with a close button. Prefer windowed/borderless mode: exclusive fullscreen may obscure native windows. A sufficiently recent WebView2 Runtime is required; missing mandatory safety interfaces fail initialization closed. No automatic runtime installation.
Opening is asynchronous; status states are starting, loading, ready, blocked, failed, closing and closed. One active panel/script, four globally, size 320..1920 by 240..1080, queue limit 32 and navigation interval 250 ms. Handles are owner-checked and invalidated at reload/unload; shutdown joins the browser worker before DLL unload.
Navigation allows HTTPS DNS-domain URLs on port 443, up to 2048 ASCII/percent-encoded characters. IP literals, credentials, known local-name suffixes, HTTP, file:, javascript: and custom protocols are rejected. HTTPS/data/blob media resources are supported. Downloads, Save As, file chooser, printing, new windows, external-app protocols, browser permissions, client certificates, autofill, password saving, DevTools and host objects/messaging are disabled. There is no Lua HTML/JavaScript injection or native bridge.
permissions.request("browser")
menu.add_button("lua", "video", "Open video", function()
local handle, reason = browser.open("https://www.youtube.com/", 960, 600)
if not handle then client.notify(tostring(reason)) end
end)
Anti aim and combat scripting
You can build your own anti aim logic, draw a DT indicator, or show where Rage is aiming. These functions return copies of the current values. Changing a returned table does not change the cheat.
Anti aim
antiaim.state() -> table
antiaim.get(name) -> value | nil
antiaim.set(name, value) -> boolean
antiaim.override({ pitch = number?, yaw = number?, yaw_offset = number? }) -> boolean
antiaim.clear_override() -> boolean
get and set accept short names such as yaw_offset, or the full name antiaim.yaw_offset. Unknown names and wrong value types return false from set. These are normal menu settings: they stay changed after the script stops and are saved when you save your config.
| Name | Values |
|---|---|
| enabled, at_targets, hide_shots, auto_adjust, anti_backstab | boolean |
| pitch | 0 = unchanged, 1 = down, 2 = up |
| yaw | 0 = unchanged, 1 = backward, 2 = right, 3 = left, 4 = jitter |
| yaw_offset | -180 to 180 degrees |
| jitter_range | 0 to 180 degrees |
| backward_key, right_key, left_key | Windows key code, 0 to 255 |
| backward_key_mode, right_key_mode, left_key_mode | 0 to 2, using the existing keybind modes |
state() contains those first nine settings, plus manual_direction: 0 = none, 1 = backward, 2 = right, 3 = left. The pitch and yaw fields are the selected modes, not the final view angles. auto_adjust is the existing pose adjustment option; exposing it here does not add a new adjustment algorithm.
Use override from create_move or post_prediction for custom angles. Pitch and yaw are absolute angles in degrees; yaw_offset is added afterwards. Leave a field out to keep the built-in result for that field. Pitch is limited to -89..89 and yaw wraps around 180 degrees. An empty table, NaN or infinity is rejected.
An override lasts for one command and one local player. Call it each command while you need it. If several scripts override the same command, the last successful call wins; its table replaces the previous override. clear_override only clears your own override. Unloading the script or an error in its callback clears it too.
Native anti aim must be enabled. Normal checks for shooting, grenades, use, ladders and noclip still apply. Anti Backstab has the final say over yaw when it detects an incoming knife attack.
callbacks.add("create_move", function()
if not antiaim.state().enabled then return end
local side = cmd.get_number() % 2 == 0 and 22 or -22
antiaim.override({ yaw_offset = side })
end)
This adds a 22-degree jitter to the current anti aim yaw. It does not rewrite your saved yaw settings.
Double Tap
double_tap.state() -> { enabled, on_manual_shot, active, ready, charge, phase }
double_tap.is_ready() -> boolean
double_tap.charge() -> number
rage.double_tap() -> same table as double_tap.state()
enabled is the menu checkbox. active and ready come from the native DT status used by the HUD. Charge is 0..1. A full charge alone does not mean the next pair is available: check ready when that distinction matters.
phase is inactive when DT is not active, charging while charge is below 1, waiting when charge is full but DT is not ready, or ready. Outside a game, active and ready are false and charge is zero. Reading this status does not start a recharge or fire a shot.
callbacks.add("paint", function()
local dt = double_tap.state()
if not dt.enabled then return end
local label = dt.ready and "DT ready" or ("DT " .. math.floor(dt.charge * 100) .. "%")
render.text(vec2(30, 230), label, color(230, 230, 230))
end)
Rage target and weapon profiles
rage.target() -> table | nil
rage.profile(index?) -> table | nil
target returns the latest published scan result: command, handle, hitbox, hitgroup, damage, hitchance, simulation_time, backtrack_ticks, extrapolation_ticks, age_ms, fired, backtracked, point, source. Point and source are vec3 values. The handle is a full entity handle, not an entity index. Damage and hitchance are estimates; fired means Rage authored a shot in that command, not that the server confirmed a hit.
The result can be from the preceding command, especially in create_move or post_prediction, which run before the main Rage scan. It returns nil if there is no target, you leave the game, or the published result is over 250 ms old. Reading it does not trigger another scan. Hitchance can be -1 when it has not been calculated.
profile reads the configured weapon profile. Indices are 0 = pistols, 1 = SMGs, 2 = rifles, 3 = shotguns, 4 = Scout, 5 = AWP, 6 = auto snipers, 7 = machineguns, 8 = Zeus, 9 = heavy pistols. Leave index out to use the currently published Rage profile; nil means no profile is available.
Profile fields: index, name, min_damage, hitchance, fov, head_scale, body_scale, auto_stop, force_body_aim, prefer_body_aim, static_point_scale, hitboxes, multipoints, auto_stop_modes. The last three are boolean arrays with 12, 12 and 5 entries. Lua arrays start at 1 even though profile indices start at 0. These are configured values; use rage.state() for active damage and HC overrides.
For the current rage.state(), min_damage is limited to 1..101. The top value, 101, is FL (Force Lethal). It is a selection rule, not a prediction that the shot will deal 101 damage.
Prediction and grenades
prediction.state() -> table | nil
grenade.prediction() -> table | nil
prediction.state is available inside post_prediction. Elsewhere it returns nil, so you do not accidentally use a previous command's prediction. It also returns nil if movement prediction failed or belongs to another command or player.
Fields: command, tick_base, post_tick_base, pre_flags, post_flags, on_ground, pre_origin, origin, pre_velocity, velocity, eye_position, inaccuracy, spread, stamina, fall_velocity, scoped, zoom. Positions and velocities are vec3 values; origin and velocity are the predicted values after the command.
local last_speed = 0
callbacks.add("post_prediction", function()
local p = prediction.state()
if p then last_speed = p.velocity:length_2d() end
end)
callbacks.add("paint", function()
render.text(vec2(30, 250), string.format("Speed %.0f", last_speed), color(230, 230, 230))
end)
grenade.prediction reads the existing grenade preview. Enable Misc and Grenade Prediction first. It returns nil without a valid trajectory. The table contains end_position (vec3), duration (seconds), total_points, points and bounces. Points contains at most 256 evenly spaced samples, including the first and last point; bounces contains at most 64 positions. Straight Throw and Super Toss are already included in this trajectory. This is the latest cached preview and can be from the preceding command. No extra grenade simulation runs when you read it.
Settings and keybind shortcuts
settings.value(id) -> value | nil
settings.set(id, value) -> boolean
keybinds.get(id) -> { id, label, configured, active, key, mode } | nil
keybinds.is_active(id) -> boolean
value returns just the value instead of the metadata table from settings.get. set chooses the registered type for you. Integers must be whole numbers; numeric values are clamped to the setting's limits. Colors use four components in 0..1. Unknown IDs, wrong types and non-finite values return false.
keybinds.get reads the same entries as keybinds.list, including ragebot.double_tap.keybind. is_active is true only when that feature is configured and its bind is active. An unknown ID returns false. These reads do not toggle the bind. Manual anti aim binds are available as antiaim.backward.keybind, antiaim.right.keybind and antiaim.left.keybind; use antiaim.state().manual_direction to read the selected direction.
antiaim.set("yaw", 1)
antiaim.set("jitter_range", 35)
settings.set("ragebot.double_tap_manual", true)
local enabled = settings.value("ragebot.double_tap")
local dt_held = keybinds.is_active("ragebot.double_tap.keybind")
The settings registry now also includes the anti aim names above, plus:
ragebot.enabled, ragebot.silent, ragebot.autofire, ragebot.auto_scope,
ragebot.autowall, ragebot.double_tap, ragebot.double_tap_manual,
ragebot.no_spread, ragebot.force_shoot, ragebot.extrapolation,
ragebot.extrapolation_ticks,
ragebot.double_tap_key, ragebot.double_tap_key_mode,
ragebot.no_spread_key, ragebot.no_spread_key_mode,
ragebot.force_shoot_key, ragebot.force_shoot_key_mode,
misc.super_toss, misc.straight_throw, misc.grenade_prediction,
misc.hit_sound, misc.hit_sound_type, misc.hit_sound_volume,
misc.visualize_aimbot, esp.skeleton_rounding
extrapolation_ticks is 1..8, hit_sound_type is 0..5, and hit_sound_volume and skeleton_rounding are 0..1. settings.list() gives you the registered type and limits for each ID.