LIGHTMOON Lua API

LuaJIT API

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.

Script enable state and every registered native control value are stored in the config by stable script filename and control ID. Missing, renamed or deleted files are ignored safely. Reload never duplicates callbacks.
                        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_predictionRuns 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)
                    

Native menu

Use menu when the script should feel like part of Lightmoon. Controls use the same cards, spacing, fonts, animations and widgets as built-in settings. Register controls once at script load; read values from callbacks.

Every control belongs to its script, so two scripts may reuse the same id . IDs must remain stable between script versions for config persistence. Supported tabs are aimbot , trigger , visuals , misc , skins , configs and lua .
Function Result
menu.add_label(tab,id,label) , menu.add_separator(tab,id) Native layout elements.
menu.add_checkbox(tab,id,label,default) Persistent checkbox.
menu.add_slider_float(...) , menu.add_slider_int(...) Persistent bounded sliders.
menu.add_color(tab,id,label,r,g,b,a) Persistent RGBA editor using 0.0 to 1.0 components.
menu.add_combo(tab,id,label,default,{...}) Persistent zero-based option index.
menu.add_multi_combo(tab,id,label,selected,options) Persistent multi-select combo. Indices are zero-based; it requires 1-128 options and accepts up to 128 selected values. Duplicate selections are removed; invalid indices or limits return false.
menu.add_keybind(tab,id,label,key?,mode?), menu.get_keybind(id) Persistent native keybind. Modes: 0 Hold, 1 Toggle, 2 Always. The getter returns configured, active, key and mode, or nil.
menu.get_multi_combo(id), menu.set_multi_combo(id,selected) Reads or replaces selected zero-based indices. Returns nil/false for invalid controls or values.
menu.add_text(tab,id,label,default) Persistent text input, up to 255 bytes.
menu.get_bool(id) , menu.get_float(id) , menu.get_int(id) , menu.get_text(id) Reads a value or returns nil for a missing/wrong type.
menu.get_color(id) Returns r,g,b,a , or nil .
                        menu.add_checkbox("visuals", "watermark", "Lua watermark", true)
menu.add_slider_float("visuals", "scale", "Text scale", 1.0, 0.5, 2.0)
menu.add_color("visuals", "color", "Color", 0.42, 0.57, 1.0, 1.0)

callbacks.add("paint", function()
    if not menu.get_bool("watermark") then return end
    local scale = menu.get_float("scale") or 1.0
    local r, g, b, a = menu.get_color("color")
    render.text(20, 20, "lua native control", r * 255, g * 255, b * 255, a * 255)
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.
Values survive script reloads in memory. They survive program restart after the current Lightmoon config is saved; switching configs swaps the per-script storage snapshot with that config. Missing scripts and invalid stored values are ignored safely.
                        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.
The native subtick move path accepts at most 32 entries in the command.

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 / functionBehavior
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

FunctionResult / 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.
Allowed console commands: say, say_team, buy, use, slot1..slot10, lastinv, invnext, invprev, drop, +lookatweapon, -lookatweapon, spec_next, spec_prev, spec_mode. Separators, controls, backslashes and malformed quotes fail. exec/alias/bind, arbitrary ConVars, file/dump commands and OS commands are unavailable.
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.

FunctionResult
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.
The standard filesystem API rejects absolute/drive/UNC/device paths, traversal, NUL, alternate streams, reserved devices, reparse points and hard-linked files. Parent directories are pinned during file operations. io/package/OS-process Lua APIs are disabled; os retains clock/time/date/difftime. FFI is unrestricted immediately and can bypass this sandbox. Run only trusted scripts; this is not OS process isolation.
local cfg = filesystem.read_json("configs/options.json", {enabled=true})
filesystem.write_json("configs/options.json",cfg)

Audio

FunctionResult
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.

FunctionResult
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.
Request and response bodies are limited to 4 MiB. Headers are limited to 32 entries, 64 bytes per name, 2048 bytes per value and 8192 bytes total. Transport-controlled headers cannot be overridden. Resolve/connect timeouts are 3 seconds; send/receive timeouts are 5 seconds. At most 4 unfinished requests per script and 32 request handles globally are accepted; a request returns 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.

FunctionResult
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.
Playback state is one of: "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

FunctionResult
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.

FFI is available immediately as require("ffi") and global ffi, without launch confirmation. Full cdef/new/cast/C/load/callback access is intentionally unrestricted: native code can access Windows, files, network and memory, bypass API safeguards or crash the game. io, package, debug, jit, OS/process Lua functions and dynamic Lua loaders remain disabled; os retains clock/time/date/difftime. Main source only (4 MiB), no bytecode. Script globals/namespaces are separate, not OS isolation. native.track_callback/untrack_callback retain callbacks and cleanup; native callback users must manage their lifetimes correctly. Run only trusted scripts.
                        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.

FunctionResult
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.
Text input limits are 1 to 16384 UTF-8 bytes. Dear ImGui callback input flags are not supported.
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.

Game, camera and player APIs independently validate game state. In the main menu, while connecting, during map transitions, on disconnect and at shutdown they return their documented 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.

FFI is unrestricted from script launch and can access Windows, process memory, files and network, bypass standard API restrictions or crash the game. There is no OS process isolation; run only trusted scripts.

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.

These restrictions are NOT OS/network isolation. DNS and proxies remain OS-managed; an allowed domain can resolve to a private address. The URL filter is not an SSRF firewall or a guarantee against browser vulnerabilities. Use trusted sites and keep WebView2 updated. Normal site JavaScript runs; HTML5 video may require a click, supported codecs, cookies or DRM. Script-specific profiles/cache live under C:\lightmoon\browser-data, outside Lua's sandbox and separate from your normal browser.
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.

NameValues
enabled, at_targets, hide_shots, auto_adjust, anti_backstabboolean
pitch0 = unchanged, 1 = down, 2 = up
yaw0 = unchanged, 1 = backward, 2 = right, 3 = left, 4 = jitter
yaw_offset-180 to 180 degrees
jitter_range0 to 180 degrees
backward_key, right_key, left_keyWindows key code, 0 to 255
backward_key_mode, right_key_mode, left_key_mode0 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.