# Aimsense CS:GO Lua API Reference for AI Agents
# Format: Plain text specification for autonomous coding agents & LLMs

> Runtime: LuaJIT 2.1 (Lua 5.1 syntax).
> Execution Model: In-process on game thread inside CS:GO frame loop.

## CRITICAL AGENT RULES & CONSTRAINTS

1. NEVER execute blocking operations (e.g. synchronous network calls, file extractions) inside `render` or `createmove` callbacks.
2. ALL entity reads can be nil. ALWAYS check existence and life state:
   ```lua
   local me = entity.get_local_player()
   if not me or not me:is_alive() then return end
   ```
3. `render.*` functions are STRICTLY VALID ONLY inside the `render` callback.
4. Netprop arrays are 0-BASED and have NO BOUNDS CHECKING. Never use `#` for length. Always index `0 .. size - 1`.
5. `draw_chams` MUST return an explicit integer:
   - Return `0`: Script takes over rendering (requires `materials.draw_chams(mat)`).
   - Return `1`: Default rendering proceeds.
   - Falling off end without return defaults to `0` (hides model).
6. `json.stringify` cannot serialize userdata (`vector`, `qangle`, `color`). Extract numbers into a plain table first: `{ x = v.x, y = v.y, z = v.z }`.
7. Lua standard `io` library is DISABLED. Use `files` and `database` tables instead.
8. Widget values persist automatically to `aimsense/scripts/data/<script>.cfg` based on `Groupbox + Widget Name + Type`.

---

## CALLBACK HOOKS (`client.add_callback(event, fn)`)

- `render`: Every frame after cheat visuals. Only place `render.*` is valid.
- `createmove`: `fn(cmd: user_cmd_t)`. Before aimbot/anti-aim. Writes to `cmd` are applied.
- `post_createmove` (alias `run_command`): `fn(cmd: user_cmd_t)`. After engine execution. Read-only snapshot.
- `antiaim`: `fn(ctx: antiaim_context_t)`. Override anti-aim angles.
- `frame_stage`: `fn(stage: number)`. Stages: 0=START, 1=NET_UPDATE_START, 2=POSTDATAUPDATE_START, 3=POSTDATAUPDATE_END, 4=NET_UPDATE_END, 5=RENDER_START, 6=RENDER_END.
- `game_events`: `fn(event: game_event_t)`. Game events (`player_death`, `player_hurt`, `round_start`, etc.).
- `aim_shot`: `fn(shot: shot_t)`. Client-side shot intent.
- `aim_ack`: `fn(shot: shot_t)`. Server shot response (hit/miss/spread/resolver).
- `pre_anim_update`: `fn(player: player_t)`. Before local animation update.
- `post_anim_update`: `fn(player: player_t)`. After local animation update.
- `local_alpha`: `fn(player: player_t, alpha: number) -> number`. Override local chams opacity.
- `draw_chams`: `fn(class: number) -> number`. Classes: 0=Enemy, 1=Shot, 2=Backtrack, 3=Local, 4=ViewModel, 5=Attachment. Return 0 (handled) or 1 (pass).
- `voice_message`: `fn(data: recv_voice_data_t)`. Incoming voice packets.
- `console_input`: `fn(cmd: string)`. Fires before engine runs console command.
- `unload`: `fn()`. Cleanup external resources (restore cvars, release materials/gifs).

---

## CORE API NAMESPACES

### `globals` (Read-only table)
- `curtime`, `realtime`, `frametime`, `framecount`, `tickcount`, `tickinterval` (number)
- `max_players` (number), `is_connected`, `is_in_game` (boolean)
- `choked_commands`, `commandack`, `commandack_prev`, `last_outgoing_command` (number)
- `server_tick`, `client_tick`, `delta_tick`, `clock_offset` (number)

### Global Functions
- `print(val)`: Logs to console with script prefix.
- `error(msg)`: Red console line (does NOT raise Lua error).
- `print_raw(text, color?)`: Unprefixed console output. Supports inline `\aRRGGBB`, `\aACCENT`, `\a_MAIN_`, `\aDEFAULT`, `\aCLEAN`.
- `safe_call(fn, ...)`: Protected call with automatic error logging.
- `to_ticks(sec)`: Converts seconds to tick count.
- `to_time(ticks)`: Converts ticks to seconds.
- `math.angle_diff(a, b)`: Shortest signed angle difference in degrees (-180..180).
- `math.clamp(val, min, max)`, `math.lerp(a, b, t)`, `math.normalize_yaw(yaw)`

### `client`
- `client.add_callback(event: string, fn: function)`
- `client.remove_callback(event: string, fn: function) -> boolean`
- `client.delay_call(seconds: number, fn: function, ...)`: Monotonic timer.
- `client.unload_script()`, `client.reload_script()`
- `client.color_log(r, g, b, ...)`: Trailing `"\0"` suppresses newline.

### `entity`
- `entity.get(index: number, is_userid?: boolean) -> entity_t | player_t | weapon_t | nil`
- `entity.from_handle(handle: number) -> entity_t | player_t | weapon_t | nil`
- `entity.get_local_player() -> player_t | nil`
- `entity.get_players(enemies_only?: boolean) -> table of player_t` (1-based)
- `entity.get_player_resource() -> player_resource_t | nil`
- Netprops: Access directly on entity: `player.m_iHealth`, `player.m_vecOrigin`, `player.m_flFlashDuration = 0`.
- Netprop arrays: `player.m_hMyWeapons[0..63]` (0-based, no length check).

### `ui`
- `ui.find(tab, groupbox, widget?, type?) -> ui_element_t | groupbox_t | nil`
- `ui.find_silent(...) -> same (no console log on miss)`
- `ui.is_open() -> boolean`, `ui.get_binds() -> table of ui_element_t`
- `ui.tab(name, icon?) -> tab_t`
- `ui.groupbox(tab, name) -> groupbox_t`
- Groupbox methods:
  - `gb:checkbox(name, default?) -> ui_element_t`
  - `gb:slider_int(name, min, max, default, format?) -> ui_element_t`
  - `gb:slider_float(name, min, max, default, format?) -> ui_element_t`
  - `gb:combo(name, ...options) -> ui_element_t`
  - `gb:multicombo(name, ...options) -> ui_element_t`
  - `gb:listbox(name, ...options) -> ui_element_t`
  - `gb:listbox_multi(name, ...options) -> ui_element_t`
  - `gb:color_picker(name, default?) -> ui_element_t`
  - `gb:keybind(name) -> ui_element_t`
  - `gb:input(name) -> ui_element_t`
  - `gb:button(name) -> ui_element_t`
  - `gb:label(name) -> ui_element_t`
- `ui_element_t` methods:
  - `el:get() -> any` (for multicombo/multi-listbox: `el:get(index: number) -> boolean`)
  - `el:set(val)` / `el:set(val, index: number)`
  - `el:override(val?)` / `el:override(val?, index?: number)`: Runtime override without saving.
  - `el:set_callback(fn: function)`: Triggers on user menu change.
  - `el:visible(shown: boolean)`
  - `el:update_list(options_tbl)`
  - `el:add_gear_item(child: ui_element_t) -> el` (Chainable)
  - `el:add_switch(checkbox: ui_element_t) -> el`
  - `el:get_key() -> number` (VK code), `el:get_mode() -> number` (0=hold, 1=toggle, 2=always)

### `render` (ONLY in `render` callback)
- `render.line(from: vector, to: vector, clr: color)`
- `render.rect(from: vector, to: vector, clr: color, rounding?: number)`
- `render.rect_outline(from: vector, to: vector, clr: color, rounding?: number)`
- `render.gradient(from, to, tl: color, tr: color, bl: color, br: color)`
- `render.circle(center: vector, clr: color, radius, start_deg?, fraction?)`
- `render.circle_outline(center, clr, radius, start_deg?, fraction?, thickness?)`
- `render.circle_3d(center: vector, clr: color, radius: number)`
- `render.poly(clr: color, ...points: vector)`
- `render.text(font: number | font_t, pos: vector, clr: color, flags: string, text: string)`
  - Built-in fonts: `1`=Verdana, `2`=Small Fonts (8px), `3`=Verdana Bold, `4`=Calibri Bold.
  - Flags: `"c"`=center, `"o"`=outline, `"d"`=drop shadow.
  - Text inline colors: `\aRRGGBB`, `\aRRGGBBAA`, `\aDEFAULT`, `\aCLEAN`.
- `render.measure_text(font, text) -> vector(w, h)`
- `render.load_font(name, size, flags?) -> font_t`
- `render.load_image(bytes, size?) -> image_t`, `render.load_svg(svg_markup, size?) -> image_t`
- `render.texture(image: image_t, pos: vector, clr?: color, size?: vector)`
- `render.screen_size() -> vector(w, h)`, `render.camera_position() -> vector`
- `render.world_to_screen(world_pos: vector) -> vector` (-1, -1 if behind)
- `render.project(world_pos: vector) -> vector, boolean` (screen_pos, behind_camera)

### `utils`
- `utils.console_exec(cmd: string)`
- `utils.is_key_pressed(vk: number) -> boolean`
- `utils.get_mouse_position() -> vector`
- `utils.trace_line(from: vector, to: vector, mask: number, filter?: entity | fn) -> trace_t`
- `utils.trace_hull(from, to, mins, maxs, mask, filter?) -> trace_t`
- `utils.trace_bullet(attacker: player_t, from: vector, to: vector, target?: player_t) -> fire_bullet_t`
- `utils.create_interface(module, name) -> number`, `utils.pattern_scan(module, pattern) -> number`
- `utils.get_weapon_data(defindex: number) -> weapon_data_t | nil`

### `cvar`
- `cvar.<name>` or `cvar:find(name) -> convar | nil`
- `cv:int(val?) -> number`, `cv:float(val?) -> number`, `cv:string(val?) -> string` (Returns PREVIOUS value on set)

### `materials`
- `materials.find(name: string) -> material_t | nil`
- `materials.create(name, shader, keyvalues_table) -> material_t` (No `$` on keys)
- `materials.draw_chams(mat: material_t)` (Inside `draw_chams` callback)
- `mat:color_modulate(clr?) -> color`, `mat:alpha_modulate(alpha?) -> number`

### `rage`
- `rage.get_antiaim_target() -> player_t | nil`, `rage.get_antiaim_yaw() -> number`
- `rage.get_exploit_charge() -> number` (0.0..1.0), `rage.is_shifting() -> boolean`
- `rage.force_charge()`, `rage.force_teleport()`, `rage.override_tickbase_shift(ticks)`

### `files` & `database` & `json`
- `files.read(path) -> string`, `files.write(path, data) -> boolean`, `files.exists(path) -> boolean`
- `files.create_folder(path)`, `files.list(path) -> table`, `files.delete(path)`
- `database.read(key) -> any`, `database.write(key, val)`, `database.flush()`
- `json.parse(str) -> table`, `json.stringify(tbl, indent?) -> string`

### `network` & `http`
- `network.get(url, headers?, callback?)` (Async when callback passed)
- `http.get(url, options?, callback?)` / `http.post(...)`: Callback receives `(success: boolean, response: table)`.
- Response fields: `status`, `body`, `headers`, `timed_out`.

### `crypto`
- `base64.encode(data, url_safe?)`, `base64.decode(data)`
- `md5.hex(data)`, `sha1.hex(data)`, `sha256.hex(data)`
- `aes.encrypt(key32, plain, iv16?)`, `aes.decrypt(key32, cipher, iv16?)`

---

## TYPES SUMMARY

- `vector(x?, y?, z?)`: `.x`, `.y`, `.z`. Methods: `:length()`, `:length2d()`, `:dist(other)`, `:dot(other)`, `:cross(other)`, `:lerp(other, t)`, `:to_screen()`.
- `qangle(pitch?, yaw?, roll?)`: `.pitch`, `.yaw`, `.roll`.
- `color(r?, g?, b?, a?)`: `.r`, `.g`, `.b`, `.a` (0..255). Methods: `:alpha_modulate(a)`, `:lerp(other, t)`.
- `player_t`: `:is_alive()`, `:is_enemy()`, `:is_dormant()`, `:get_eye_position()`, `:get_hitbox_position(hitbox_id)`, `:get_bone_position(bone_id)`, `:get_bounding_box() -> mins, maxs`, `:get_active_weapon()`, `:friendly()`.
- `weapon_t`: `:weapon_index()`, `:get_weapon_info()`, `:can_shoot()`, `:shooting_weapon()`.
- `user_cmd_t`: `.command_number`, `.tickcount`, `.move` (vector), `.viewangles` (qangle), `.buttons` (IN_* bitmask), `.send_packet` (bool), `:set_move(yaw, speed?)`.
- `antiaim_context_t`: `:pitch(deg)`, `:yaw(deg)`, `:yaw_offset(deg)`, `:fakelag(ticks)`, `:desync(bool)`, `:desync_angle(deg)`.
- `shot_t`: `.client_shoot_pos`, `.target_pos`, `.wanted_damage`, `.hitchance`, `.damage`, `.miss_reason` ("spread", "resolver", etc.).
- `game_event_t`: `:get_name()`, `:get_int(key)`, `:get_float(key)`, `:get_string(key)`, `:get_bool(key)` or direct field read: `event.userid`, `event.attacker`.

---

## MINIMAL CANONICAL SCRIPT TEMPLATE

```lua
-- Register menu controls
local group = ui.groupbox("Visuals", "Agent Script")
local enabled = group:checkbox("Enabled", true)
local bar_color = group:color_picker("Color", color(0, 255, 120, 255))

-- Rendering loop
client.add_callback("render", function()
    if not enabled:get() or not globals.is_in_game then return end
    
    local enemies = entity.get_players(true)
    for i = 1, #enemies do
        local enemy = enemies[i]
        if enemy:is_alive() and not enemy:is_dormant() then
            local mins, maxs = enemy:get_bounding_box()
            if mins.x ~= 0 or maxs.x ~= 0 then
                render.rect_outline(mins, maxs, bar_color:get())
            end
        end
    end
end)

-- Cleanup on unload
client.add_callback("unload", function()
    print("Script unloaded cleanly.")
end)
```