-- DO NOT EDIT - generated by tools/scripting/generate.sh
---@meta lynx

---A point or direction in two dimensions. Any table with numeric `x` and `y` is accepted.
---@class vec2
---@field x number
---@field y number

---A point or direction in three dimensions. Any table with numeric `x`, `y` and `z` is accepted.
---@class vec3
---@field x number
---@field y number
---@field z number

---An axis-aligned rectangle.
---@class rect
---@field origin vec2
---@field size vec2

---An RGBA colour. Every channel is 0-255.
---@class color
---@field r number
---@field g number
---@field b number
---@field a number

---An opaque menu-item handle returned by the `ui.new_*` builders. Stale once the menu is rebuilt.
---@class ScriptHandle

---The signed-in Lynx user. A field is absent when its value is unknown.
---@class lynx_user
---@field username string
---@field uid string
---@field email string
---@field avatar string
---@field plan string
---@field expires_at integer Unix seconds; absent when the plan does not expire.

---The always-present client global. The chunk's top level runs once, at load; everything after that is an event.
---Base events, delivered to the callback with one table argument: `paint` (draw only here, once per frame), `shutdown` (the script is unloading), `menu_open` and `menu_close` (the Lynx menu opened or closed). Each game adds its own events; see the game's reference page.
---@class client
client = {}

---Register `fn` to run on `event`. Unknown event names raise an error.
---@param event string
---@param fn fun(e: table)
function client.set_event_callback(event, fn) end

---Remove a callback previously registered for `event`.
---@param event string
---@param fn fun(e: table)
function client.unset_event_callback(event, fn) end

---Run `fn` on a later frame, `delay` seconds from now. Extra arguments are forwarded to `fn`.
---@param delay number
---@param fn function
---@param ... any
function client.delay_call(delay, fn, ...) end

---Reload every loaded script, this one included.
function client.reload_active_scripts() end

---Append a line to the script console. Arguments are concatenated, like `print`.
---@param ... any
function client.log(...) end

---Append a coloured console line. The first three arguments are the 0-255 RGB channels; the rest are the message.
---@param r integer
---@param g integer
---@param b integer
---@param ... any
function client.color_log(r, g, b, ...) end

---Append a red error line to the console.
---@param ... any
function client.error_log(...) end

---The overlay size in pixels.
---@return number width
---@return number height
function client.screen_size() end

---Milliseconds on a high-precision monotonic clock, counted from when the process started.
---@return number
function client.timestamp() end

---Seconds since the Unix epoch.
---@return integer
function client.unix_time() end

---The local wall-clock time of day.
---@return integer hour
---@return integer minute
---@return integer second
---@return integer millisecond
function client.system_time() end

---A uniform random integer in `[min, max]`.
---@param min integer
---@param max integer
---@return integer
function client.random_int(min, max) end

---A uniform random number in `[min, max)`.
---@param min number
---@param max number
---@return number
function client.random_float(min, max) end

---The signed-in Lynx user.
---@return lynx_user
function client.get_lynx_user() end

---The game key this build mods, e.g. `"8ball_pool"`.
---@return string
function client.game() end

---The current touch point.
---@return number x
---@return number y
---@return boolean down
function client.touch() end

---Synthesise a tap at overlay pixel `x, y`. Needs the `input` capability.
---@param x number
---@param y number
---@return boolean sent
function client.tap(x, y) end

---Frame-timing globals, gamesense-style.
---@class globals
globals = {}

---Seconds since load, sampled live.
---@return number
function globals.realtime() end

---Seconds since load, as of the current frame.
---@return number
function globals.curtime() end

---The game frame counter the runtime is on.
---@return integer
function globals.framecount() end

---Seconds between the last two frames.
---@return number
function globals.frametime() end

---Alias of `frametime`.
---@return number
function globals.absoluteframetime() end

---Build and read menu widgets. gamesense-compatible; Lynx adds tabs, popovers, icons, watermark rows and toasts. A tab or container that does not exist yet is created.
---@class ui
ui = {}

---A checkbox.
---@param tab string
---@param container string
---@param name string
---@return ScriptHandle
function ui.new_checkbox(tab, container, name) end

---A slider over `[min, max]`. `tooltips` maps whole values to labels.
---@param tab string
---@param container string
---@param name string
---@param min number
---@param max number
---@param initial? number
---@param show_tooltip? boolean
---@param unit? string
---@param scale? number
---@param tooltips? table<integer, string>
---@return ScriptHandle
function ui.new_slider(tab, container, name, min, max, initial, show_tooltip, unit, scale, tooltips) end

---A single-select combobox. Options are passed as extra string arguments or as one array.
---@param tab string
---@param container string
---@param name string
---@param ... string
---@return ScriptHandle
function ui.new_combobox(tab, container, name, ...) end

---A multi-select list. Options are extra string arguments or one array; at most 32.
---@param tab string
---@param container string
---@param name string
---@param ... string
---@return ScriptHandle
function ui.new_multiselect(tab, container, name, ...) end

---A listbox of `items`.
---@param tab string
---@param container string
---@param name string
---@param items string[]
---@return ScriptHandle
function ui.new_listbox(tab, container, name, items) end

---A single-line text field.
---@param tab string
---@param container string
---@param name string
---@return ScriptHandle
function ui.new_textbox(tab, container, name) end

---A button that calls `callback` when pressed.
---@param tab string
---@param container string
---@param name string
---@param callback fun()
---@return ScriptHandle
function ui.new_button(tab, container, name, callback) end

---A static label showing `text`.
---@param tab string
---@param container string
---@param text string
---@return ScriptHandle
function ui.new_label(tab, container, text) end

---A colour picker. Attaches to the previous row in the container when there is one, like gamesense.
---@param tab string
---@param container string
---@param name string
---@param r? integer
---@param g? integer
---@param b? integer
---@param a? integer
---@return ScriptHandle
function ui.new_color_picker(tab, container, name, r, g, b, a) end

---A hotkey row.
---@param tab string
---@param container string
---@param name string
---@return ScriptHandle
function ui.new_hotkey(tab, container, name) end

---A named string that persists in the menu config but draws no row.
---@param name string
---@param default? string
---@return ScriptHandle
function ui.new_string(name, default) end

---Create (or find) a menu tab.
---@param name string
---@param icon? string
---@return ScriptHandle
function ui.new_tab(name, icon) end

---A popover usable as the `container` argument of the `new_*` builders.
---@param tab string
---@param container string
---@param name string
---@param icon? string
---@return ScriptHandle
function ui.new_popover(tab, container, name, icon) end

---The dots-popover attached to a menu row.
---@param item ScriptHandle
---@return ScriptHandle
function ui.attach_popover(item) end

---A watermark row whose text is set with `ui.set`.
---@param name string
---@param icon? string
---@return ScriptHandle
function ui.new_watermark_item(name, icon) end

---Register an icon by name from SVG or PNG bytes, for use with `new_tab`, `new_popover` and `set_icon`.
---@param name string
---@param bytes string
function ui.load_icon(name, bytes) end

---Set a row's icon by a registered name.
---@param item ScriptHandle
---@param icon string
function ui.set_icon(item, icon) end

---Enable or disable a row.
---@param item ScriptHandle
---@param enabled boolean
function ui.set_enabled(item, enabled) end

---Show or hide a row.
---@param item ScriptHandle
---@param visible boolean
function ui.set_visible(item, visible) end

---Call `fn` whenever the item's value changes.
---@param item ScriptHandle
---@param fn fun(item: ScriptHandle)
function ui.set_callback(item, fn) end

---Find a built-in Lynx widget by tab, container and name (raw key or translated label, case-insensitive), including ones inside popovers.
---@param tab string
---@param container string
---@param name string
---@return ScriptHandle
function ui.reference(tab, container, name) end

---Read an item's value: checkbox boolean; slider number; combobox string; multiselect string array; listbox zero-based index; colour `r, g, b, a` (0-255); textbox, string, label and watermark string; hotkey `pressed, key`.
---@param item ScriptHandle
---@return any ...
function ui.get(item) end

---Set an item's value; the argument shape matches what `ui.get` returns. Fires the item's callback.
---@param item ScriptHandle
---@param ... any
function ui.set(item, ...) end

---Replace the options of a combobox, multiselect or listbox the script created.
---@param item ScriptHandle
---@param ... string
function ui.update(item, ...) end

---The item's name.
---@param item ScriptHandle
---@return string
function ui.name(item) end

---Whether the Lynx menu is open.
---@return boolean
function ui.is_menu_open() end

---The menu's top-left corner in overlay pixels.
---@return number x
---@return number y
function ui.menu_position() end

---The menu's size in overlay pixels.
---@return number width
---@return number height
function ui.menu_size() end

---The pointer position in overlay pixels.
---@return number x
---@return number y
function ui.mouse_position() end

---Show a toast for `seconds` (default 3).
---@param text string
---@param seconds? number
function ui.notify(text, seconds) end

---Immediate-mode overlay drawing. Call these only inside the `paint` event. Colours are 0-255; coordinates are overlay pixels.
---@class renderer
renderer = {}

---Draw text. `flags`: `+` large, `-` small, `c` centred, `r` right-aligned, `b` bold. `max_width` of 0 does not wrap. Remaining arguments are concatenated into the string.
---@param x number
---@param y number
---@param r integer
---@param g integer
---@param b integer
---@param a integer
---@param flags string
---@param max_width number
---@param ... any
---@return boolean drawn
function renderer.text(x, y, r, g, b, a, flags, max_width, ...) end

---Measure text without drawing it.
---@param flags string
---@param ... any
---@return number width
---@return number height
function renderer.measure_text(flags, ...) end

---A filled rectangle at `x, y` sized `w, h`.
---@param x number
---@param y number
---@param w number
---@param h number
---@param r integer
---@param g integer
---@param b integer
---@param a integer
---@return boolean drawn
function renderer.rectangle(x, y, w, h, r, g, b, a) end

---A two-colour gradient rectangle. `ltr` true fills left-to-right, otherwise top-to-bottom.
---@param x number
---@param y number
---@param w number
---@param h number
---@param r1 integer
---@param g1 integer
---@param b1 integer
---@param a1 integer
---@param r2 integer
---@param g2 integer
---@param b2 integer
---@param a2 integer
---@param ltr boolean
---@return boolean drawn
function renderer.gradient(x, y, w, h, r1, g1, b1, a1, r2, g2, b2, a2, ltr) end

---A line from `(xa, ya)` to `(xb, yb)`.
---@param xa number
---@param ya number
---@param xb number
---@param yb number
---@param r integer
---@param g integer
---@param b integer
---@param a integer
---@return boolean drawn
function renderer.line(xa, ya, xb, yb, r, g, b, a) end

---A filled circle, or an arc when `start_degrees`/`percentage` (0-1) are given.
---@param x number
---@param y number
---@param r integer
---@param g integer
---@param b integer
---@param a integer
---@param radius number
---@param start_degrees? number
---@param percentage? number
---@return boolean drawn
function renderer.circle(x, y, r, g, b, a, radius, start_degrees, percentage) end

---A circle or arc outline of `thickness`.
---@param x number
---@param y number
---@param r integer
---@param g integer
---@param b integer
---@param a integer
---@param radius number
---@param start_degrees? number
---@param percentage? number
---@param thickness? number
---@return boolean drawn
function renderer.circle_outline(x, y, r, g, b, a, radius, start_degrees, percentage, thickness) end

---A filled triangle through the three points.
---@param x0 number
---@param y0 number
---@param x1 number
---@param y1 number
---@param x2 number
---@param y2 number
---@param r integer
---@param g integer
---@param b integer
---@param a integer
---@return boolean drawn
function renderer.triangle(x0, y0, x1, y1, x2, y2, r, g, b, a) end

---Draw a loaded texture into the rectangle `x, y, w, h`, tinted by the colour. `mode` selects the fit.
---@param id integer
---@param x number
---@param y number
---@param w number
---@param h number
---@param r integer
---@param g integer
---@param b integer
---@param a integer
---@param mode? string
---@return boolean drawn
function renderer.texture(id, x, y, w, h, r, g, b, a, mode) end

---Upload a PNG and return a texture id.
---@param contents string
---@return integer id
function renderer.load_png(contents) end

---Upload a JPEG and return a texture id.
---@param contents string
---@return integer id
function renderer.load_jpg(contents) end

---Upload an SVG and return a texture id.
---@param contents string
---@return integer id
function renderer.load_svg(contents) end

---Upload raw RGBA pixels and return a texture id.
---@param contents string
---@param width integer
---@param height integer
---@return integer id
function renderer.load_rgba(contents, width, height) end

---A stacked top-left indicator line. Returns its y, or nil when the frame's draw budget is full.
---@param r integer
---@param g integer
---@param b integer
---@param a integer
---@param ... any
---@return number|nil y
function renderer.indicator(r, g, b, a, ...) end

---Draw a connected path through `points` (`{ {x=, y=}, ... }`). A Lynx extra for drawing custom prediction paths.
---@param points vec2[]
---@param r integer
---@param g integer
---@param b integer
---@param a integer
---@param thickness? number
---@return boolean drawn
function renderer.polyline(points, r, g, b, a, thickness) end

---Project a game point to overlay pixels. On the table games the input is table coordinates. Returns nil when the point is off-screen or the transform is unavailable.
---@param x number
---@param y number
---@param z? number
---@return number|nil sx
---@return number|nil sy
function renderer.world_to_screen(x, y, z) end

---Request options for an HTTP call.
---@class http_options
---@field headers? table<string, string>
---@field body? string

---An HTTP response passed to a request callback.
---@class http_response
---@field status integer
---@field body string
---@field headers table<string, string>
---@field error? integer Present only when the request failed.

---Asynchronous HTTPS requests, off the game thread. Needs the `http` capability. https only, any host.
---@class http
http = {}

---GET `url`. Pass a callback, or options then a callback. `callback(success, response)`.
---@param url string
---@param options? http_options
---@param callback fun(success: boolean, response: http_response)
function http.get(url, options, callback) end

---POST `url` with `options`. `callback(success, response)`.
---@param url string
---@param options http_options
---@param callback fun(success: boolean, response: http_response)
function http.post(url, options, callback) end

---Send `method` (`"GET"` or `"POST"`) to `url`. `callback(success, response)`.
---@param method string
---@param url string
---@param options http_options
---@param callback fun(success: boolean, response: http_response)
function http.request(method, url, options, callback) end

---An open WebSocket connection returned by `websocket.connect`.
---@class socket
---@field send fun(self: socket, text: string): boolean Send a text frame; returns whether it was sent.
---@field close fun(self: socket, code?: integer) Close the connection with an optional status code.

---The callbacks a WebSocket delivers.
---@class websocket_handlers
---@field open? fun()
---@field message? fun(text: string)
---@field close? fun(code: integer, reason: string)
---@field error? fun(message: string)

---Asynchronous WebSocket client, off the game thread. Needs the `websocket` capability. wss only.
---@class websocket
websocket = {}

---Open a connection to `url`. Returns the socket, or nil when the URL is refused or the per-script limit is reached.
---@param url string
---@param handlers websocket_handlers
---@return socket|nil
function websocket.connect(url, handlers) end

---JSON encode and decode (lua-cjson), with gamesense-style aliases.
---@class json
json = {}

---Decode a JSON string to a Lua value.
---@param text string
---@return any
function json.decode(text) end

---Encode a Lua value to a JSON string.
---@param value any
---@return string
function json.encode(value) end

---Alias of `decode`.
---@param text string
---@return any
function json.parse(text) end

---Alias of `encode`.
---@param value any
---@return string
function json.stringify(value) end

---Bitwise operations on 32-bit integers, LuaBitOp-compatible.
---@class bit
bit = {}

---Normalise a number to a 32-bit integer.
---@param value number
---@return integer
function bit.tobit(value) end

---Hex string of `value`; `n` digits (negative for uppercase), default 8.
---@param value number
---@param n? integer
---@return string
function bit.tohex(value, n) end

---Bitwise NOT.
---@param value number
---@return integer
function bit.bnot(value) end

---Bitwise AND of every argument.
---@param value number
---@param ... number
---@return integer
function bit.band(value, ...) end

---Bitwise OR of every argument.
---@param value number
---@param ... number
---@return integer
function bit.bor(value, ...) end

---Bitwise XOR of every argument.
---@param value number
---@param ... number
---@return integer
function bit.bxor(value, ...) end

---Left shift by `shift` bits.
---@param value number
---@param shift integer
---@return integer
function bit.lshift(value, shift) end

---Logical right shift by `shift` bits.
---@param value number
---@param shift integer
---@return integer
function bit.rshift(value, shift) end

---Arithmetic right shift by `shift` bits.
---@param value number
---@param shift integer
---@return integer
function bit.arshift(value, shift) end

---Rotate left by `shift` bits.
---@param value number
---@param shift integer
---@return integer
function bit.rol(value, shift) end

---Rotate right by `shift` bits.
---@param value number
---@param shift integer
---@return integer
function bit.ror(value, shift) end

---Swap the byte order of a 32-bit integer.
---@param value number
---@return integer
function bit.bswap(value) end

---A per-script persistent key/value store, JSON-encoded on top of the script's storage directory. 64 KiB per script.
---@class database
database = {}

---Read `key`. Returns the stored value, or nil when it is absent.
---@param key string
---@return any
function database.read(key) end

---Write `value` under `key`. Returns true on success, or nil on failure.
---@param key string
---@param value any
---@return boolean|nil
function database.write(key, value) end

---@class hash
hash = {}

---@param text string
---@return std::int64_t
function hash.fnv1a(text) end


---@param text string
---@return std::uint32_t
function hash.fnv1a32(text) end



---@class vector
vector = {}

---@param value number
---@return number
---@overload fun(value: vec2): vec2
---@overload fun(value: vec3): vec3
function vector.abs(value) end


---@param degrees number
---@return number
function vector.deg_to_rad(degrees) end


---@param radians number
---@return number
function vector.rad_to_deg(radians) end


---@param radians number
---@return number
function vector.wrap_pi(radians) end


---@param from number
---@param to number
---@return number
function vector.angle_delta(from, to) end


---@param value number
---@return number
function vector.round4(value) end


---@param a vec2
---@param b vec2
---@return number
---@overload fun(a: vec3, b: vec3): number
function vector.dot(a, b) end


---@param a vec2
---@param b vec2
---@return number
---@overload fun(a: vec3, b: vec3): vec3
function vector.cross(a, b) end


---@param value vec2
---@return number
---@overload fun(value: vec3): number
function vector.length_squared(value) end


---@param value vec2
---@return number
---@overload fun(value: vec3): number
function vector.length(value) end


---@param a vec2
---@param b vec2
---@return number
---@overload fun(a: vec3, b: vec3): number
function vector.distance_squared(a, b) end


---@param a vec2
---@param b vec2
---@return number
---@overload fun(a: vec3, b: vec3): number
function vector.distance(a, b) end


---@param value vec2
---@param tolerance number
---@return boolean
---@overload fun(value: vec2): boolean
---@overload fun(value: vec3, tolerance: number): boolean
---@overload fun(value: vec3): boolean
function vector.is_zero(value, tolerance) end


---@param a vec2
---@param b vec2
---@param tolerance number
---@return boolean
---@overload fun(a: vec2, b: vec2): boolean
---@overload fun(a: vec3, b: vec3, tolerance: number): boolean
---@overload fun(a: vec3, b: vec3): boolean
function vector.approx_equal(a, b, tolerance) end


---@param value vec2
---@return vec2
---@overload fun(value: vec3): vec3
function vector.normalize(value) end


---@param value vec2
---@return vec2
function vector.perpendicular(value) end


---@param value vec2
---@param radians number
---@return vec2
function vector.rotated(value, radians) end


---@param value vec2
---@return number
function vector.angle_of(value) end


---@param radians number
---@param magnitude number
---@return vec2
---@overload fun(radians: number): vec2
function vector.from_angle(radians, magnitude) end


---@param from vec2
---@param to vec2
---@param ratio number
---@return vec2
---@overload fun(from: vec3, to: vec3, ratio: number): vec3
function vector.lerp(from, to, ratio) end


---@param value vec2
---@param unit_normal vec2
---@return vec2
---@overload fun(value: vec3, unit_normal: vec3): vec3
function vector.reflect(value, unit_normal) end


---@param value vec2
---@param onto vec2
---@return vec2
---@overload fun(value: vec3, onto: vec3): vec3
function vector.project(value, onto) end


---@param a vec2
---@param b vec2
---@return vec2
---@overload fun(a: vec3, b: vec3): vec3
function vector.min(a, b) end


---@param a vec2
---@param b vec2
---@return vec2
---@overload fun(a: vec3, b: vec3): vec3
function vector.max(a, b) end


---@param first rect
---@param second rect
---@return rect
function vector.intersection(first, second) end


---@param value rect
---@param by number
---@return rect
function vector.inset(value, by) end