starlit

For developers

How to report a bug, how to ask for a function, how a new function is built, how to detect functions from a script, and what is planned.

On this page

We want scripts to be good, and we want users to load them with confidence. Both depend on an API that is tested hard. This page says how we decide what goes into it and how you can help it grow.

What we welcome

  • Bug reports about a function that behaves differently from this reference. A report is most useful with the smallest script that shows the difference.
  • Requests for data that the game already shows every client in a match.
  • Requests for more tuning: another number of the ragebot, another movement helper, another setting of the world or the ESP that a script should be able to adjust.
  • Requests for drawing, menu and visuals features, such as a new control kind, a new shape or a new part of the ESP to style.
  • Requests for new events with a fixed list of fields.
  • Corrections to this documentation, including numbers that no longer match the build.

Report a bug

Send us:

  1. The script, cut down to the lines that show the problem.
  2. The call you made and what the reference says it should do.
  3. What happened instead: the error text, or the values you got.
  4. The lines from the script log, and the state of the entry on the scripts page.
  5. Whether the problem is every frame or only in some situation, such as a particular map or a particular mode.

Send requests and bug reports to Starlit staff in the support channel on our Discord server. Do not put them in script comments or in the log. We do not read those.

Ask for a function

A request is a short message with these parts. Leave none out, because each one is something we have to decide before we write any code.

  1. Name and signature, written the way the reference writes them, for example ent:some_value() -> number or nil. The name here is made up.
  2. Arguments with types and ranges, and return values, including when it returns nil.
  3. What it reads or changes, in plain words. For a reader: what the game shows an ordinary client, and when. For a tuning function: which number or setting, and the range it should move in.
  4. Why the existing functions are not enough. Say what you tried.
  5. A script of about ten lines that uses the function.
  6. How often it is called. Once a frame, once for every player, once for every event. This sets its cost.

We answer with one of three things: yes, yes with changes, or no with the reason.

How a function is built

A function that gets a yes goes through the same steps as every other function:

  • Its names and values come from a fixed list in the client. A script passes a setting id, a part, a style or a page by name, and the client looks the name up.
  • Every argument is checked, and every error text is fixed.
  • A function that tunes something keeps the range of the menu row it belongs to, and the value is live: it lasts a short time after the last call and goes back to the user's own value when the script stops.
  • It charges an instruction cost, so a script that calls it a lot runs out of budget sooner.
  • It has tests with hostile input, and the whole suite runs on every build.
  • It is added to this reference and to the changelog.

Rules every function follows

  1. Names a script passes in are looked up in fixed lists. An unknown name gives nil or false and is not repeated back.
  2. Error texts are fixed and carry no data from the client.
  3. Every call has a budget, and every limit is written down in this reference.
  4. Values a script sets in Starlit are live, clamped to the range of the menu row they belong to, and never saved into the user's config.
  5. The user stays in charge. A key the user holds, or a change the user makes in the menu, wins over the script's value where the page of the function says so.
  6. The user starts a script by hand. A file that changed asks for a new confirmation.
  7. Scripts draw below the menu and its dialogs, the confirm load button included.
  8. A script that fails twice is stopped, and everything it set is given back.

Feature detection

There is no version function. The current build is the API of the changelog entry on top. To use a function that older builds may not have, test for it. Module tables are read-only, and a member that does not exist reads as nil:

if events.on_shot then
  events.on_shot(function(shot) log.info(shot.target) end)
end

local has_entity = entity ~= nil and entity.get ~= nil
local has_v3 = rage ~= nil and settings ~= nil and movement ~= nil and visuals ~= nil

Coming later

These are planned. None of them exists in the current build. A script that calls one fails with an error such as attempt to index a nil value (global 'trace').

  • Line and box traces between two points, and visibility checks between players.
  • Hitbox positions and screen bounding boxes for players. The outline of a hitbox exists already, as draw.hitbox.
  • The camera position, angles and field of view; the map name; round and bomb state; the maximum number of players.
  • Lists of projectiles, weapons and the bomb.
  • More game events: bomb events, spawns, reloads, blinding and grenade detonations, item pickups.
  • Timers, JSON encoding and decoding, toast messages, a way for a script to unload itself, the time of day.
  • Several colours in one control.
  • Drawing: raw pixel images up to 64 by 64, blur.
  • A table of public weapon statistics.

Tell us which number, setting or piece of data you want next, using the form under Ask for a function.

previous: Examples · next: Changelog