API reference overview
The reference is organised by namespace: one page for each module a script can call (events, draw, ui, ...). Every entry has an anchor, so you can link straight to one, for example store.get.
Reading an entry#
Each entry shows:
- a signature in the form
namespace.name(param: type, optional?: type): return types. A?after a parameter name means it is optional. Types are Lua types (number,string,boolean,table,function,integer) and names of objects (Texture,Request, ...) described on the same page; - badges: since 1.x (the API version that introduced it) and permission: x when the function needs one;
- a table of parameters with types, descriptions and defaults, and a table of return values;
- a short example.
Methods of objects use a colon: tex:ready(), req:cancel(). Fields use a dot and are listed with their types.
Conventions#
- Colours are integers
0xRRGGBBAA, or tables{r, g, b, a}with 0-255 values. See colours. - Coordinates are pixels, (0, 0) at the top left, y downwards. See drawing.
- Times are in seconds. Angles passed to
draw.arcare in radians; view angles in the snapshot are in degrees. - Errors. A function raises an error for a programming mistake (wrong argument type, a call in the wrong place, a missing permission). The message explains the problem; catch it with
pcallif you must. Failures that are normal at run time are returned as values:nil, orfalse, reason. - Limits (counts, sizes) are stated on the entry or page they apply to.
Versions#
This reference describes API 1.1. The version is major.minor: a different major may remove or rename functions; a newer minor only adds. Entries added after 1.0 say since 1.1 and so on. Scripts name the version they target in the manifest and can check at run time with api.require and api.has. See API-version compatibility.
Permissions at a glance#
See permissions.
The namespaces#
| Page | What it is for |
|---|---|
| api, app, time, log | Version, the overlay, clocks, logging |
| events, timer, task | When your code runs |
| store, file, json | Saving and parsing data |
| anim, color, math | Animation, colours, number helpers |
| ui | Tabs, cards, controls, windows, widgets |
| draw, assets | Drawing, textures, fonts, shaders |
| data, media, theme, input | Game data, music, theme colours, key state |
| net | HTTPS requests |
| mem | Reading and writing the game's memory |
| Lua library | The standard Lua functions that exist here |
How this reference is kept accurate#
The overlay's test suite can list every function the script host exposes (--lua-test, written to <prefix>.api.txt). That list is stored in docs-src/api-inventory.txt, and the documentation check fails if a documented function is not in it, or if a function in it is not documented (apart from a short list of known internal helpers on the gaps page). The example scripts are run through the real host the same way.