Script bindings¶
Verified against: SLUS_212.15 (NTSC-U, SHA1 e9cb2cc49aa046b9e494313dce2f5038ed17b2f4).
The game's scripts are Lua 4.0 chunks that drive the engine through script bindings: C++ functions the game registers as Lua globals, playing the role FiveM calls natives. This is the masterlist of all 956 of them (966 registrations, 10 names registered twice as overloads), one section per binding on the page of its category: its signature, what each argument means, what it returns, what it does, how sure we are, the original functions behind it and how often the game's own scripts call it. How the script system runs (the Lua state, the order of the scripts, callbacks by name) is on Scripts (Lua).
The list doubles as the API reference for script mods: the planned mod system loads Lua mods from a mods folder and lets them call these same bindings (Roadmap: script mods). The descriptions are written for that reader: what an argument means in game terms (a handle and where it comes from, an id, a unit), not only its Lua type.
Everything here is generated by coney-tools natives render from the research database files
research/bindings/<category>.yaml (schema: Research workflow); edit the
YAML, never these pages. CI runs coney-tools natives render --check, which fails when the pages and the YAML disagree.
Categories¶
| Category | Bindings | Used by scripts | Boot to menu | Mission 1 | Traced |
|---|---|---|---|---|---|
| Characters: one human: creation, state, health, animation, commands, the player's crew | 204 | 172 | 29 | 51 | 169 |
| AI: goals, actions, brains and gang tactics that drive non-player characters | 146 | 114 | 16 | 24 | 110 |
| Gangs: gangs: creation, membership, spawners, relations | 57 | 53 | 18 | 14 | 51 |
| Cameras: creating, switching and moving cameras | 41 | 34 | 4 | 9 | 31 |
| World and objects: objects, cars, doors, flags, paths, volume boxes and triggers | 80 | 69 | 12 | 19 | 67 |
| Effects and lighting: particles, weather, fog, lights, shadows, gamma and screen effects | 43 | 35 | 15 | 6 | 36 |
| HUD and menus: the in-game HUD, radar, objectives, messages and front-end menus | 78 | 66 | 18 | 27 | 59 |
| Sound and music: sound effects, ambient emitters, music tracks and sound configuration | 51 | 45 | 20 | 8 | 45 |
| Scenes and movies: in-engine cutscenes and full-motion movies | 16 | 12 | 9 | 5 | 12 |
| Levels and game state: level flow, checkpoints, difficulty, unlockables, stats, money and police | 90 | 75 | 38 | 26 | 65 |
| Script flow: running scripts, scheduled calls, callbacks and message handlers | 18 | 15 | 10 | 8 | 15 |
| Pad input: the gamepad: button handlers | 2 | 2 | 1 | 2 | 2 |
| Configuration (Cfg): the Cfg* tables the config scripts fill: characters, objects, levels, sounds | 117 | 100 | 70 | 13 | 97 |
| Utilities: numbers, platform queries and generic object queries | 8 | 7 | 6 | 2 | 7 |
| Debug: developer leftovers: network debugging, sample capture, detail flags | 5 | 3 | 0 | 1 | 3 |
| All | 956 | 802 | 266 | 215 | 769 |
Conventions¶
Each binding is a small wrapper made by tolua: it reads its arguments from the Lua stack with tolua's helpers, calls one function of the game and pushes the results. No argument types are checked (except in the overloads, below). An argument left off the end of the call reads as its default (0, false, no string, or the default the table gives) and an explicit nil as 0, false or no string; an argument of the wrong type reads as whatever Lua's conversion gives, usually 0. A wrong call therefore does something quietly wrong rather than raising an error, and script errors are silent anyway (Scripts (Lua)).
| Read as | What the script passes |
|---|---|
| number | any number |
| number, truncated to an integer | an integer; a fraction is cut off toward zero |
| number, truncated to an unsigned integer | a handle (of a human, object, camera, gang, ...) as an earlier binding returned it, or a non-negative id; NilHandle is the global for no handle |
| number (single precision) | a number the engine keeps as a 32-bit float: positions in metres, angles, times in seconds unless the meaning says otherwise |
| boolean (nil or 0 is false) | true (1) or false (nil); any number other than 0 is true |
| string | a name, passed to the engine as text; nil reads as no string |
| table of 3 numbers (t[1]..t[3]) | a position or vector {x, y, z}, read by index (not .x) |
| table of 4 numbers (t[1]..t[4]) | a rotation quaternion or colour {a, b, c, d}, read by index |
| (any table) | after the call the wrapper copies the values back into the table it was given, so a binding that changes them (HuCreate snaps the position to the ground) returns them this way; every table argument of the game's bindings is written back |
| userdata | a C pointer passed through from another binding; only read when the caller passed it |
Results. A binding pushes at most one value. Lua 4.0 has no booleans, so a boolean result is the number 1 for true
and nil for false (global.lua sets true = 1 and false = nil to match); test it with if x then (in Lua every
value but nil is true, 0 included). A string result is nil when there is none, and an object result (M_Vector4, a
tolua class with fields x y z w) is nil for none. A binding listed as returning nothing pushes no value, so its call
evaluates to nil.
Overloads. Ten names are registered twice. Lua keeps the second registration; its wrapper checks the types of the arguments it was given and, when they do not match, calls the first registration instead. So both forms work, chosen by the argument types; each such entry shows both.
Callbacks. Bindings that take a function name (ScheduleFunc, SetMsgHandler, PadSetHandler, ...) keep the name,
not the function, and look it up when they fire; a dotted name such as Menu.onStart finds a field of a global table
(Scripts (Lua)).
How to read an entry¶
Each section starts with the signature, like GetLevelId(index) -> number: the argument names are ours, in the
order the wrapper reads them, and the arrow gives the Lua type of what it returns (nothing when there is no arrow). The
table gives each argument's position, how the wrapper reads it (the rows of the table above) and its meaning in game
terms. Then come the description and the facts:
- Evidence: the evidence level of the description and meanings, and the detail: traced means a contributor followed the function behind the wrapper far enough to describe every argument; brief means a shorter description from a quick read of that function, the binding's name and how the game's scripts call it (the evidence level says which of these it rests on). The signature itself (argument count, order, Lua types, results) is always confirmed (code) at the wrapper.
- Wrapper / calls: the address of the tolua wrapper and of the function of the game it calls (with our name for it
when it has one), in
SLUS_212.15. - Used by: how many of the 467 compiled Lua chunks on the disc use the binding, how many references to it there are in all, whether the scripts of the boot-to-menu path or of the first mission use it, and whether a call was seen to use its result (below).
- Coney: whether Coney implements the binding yet (below).
Usage counts¶
The counts come from a survey of the NTSC-U disc's 467 compiled Lua chunks, reporting names and counts only. Every
GETGLOBAL of a binding's name counts as a reference: the scripts fetch a binding by its global name to call it (often
inside a loop, which is why references, not traced calls, are counted). Result used is a lower bound: it says a traced
call was seen to keep the binding's result. 802 of the 956 bindings are used somewhere and 154 never. The boot-to-menu
path is enum_preload.lua, the three config_preload*.lua, config_strings_en.lua, global.lua and level100.lua
(266 bindings); mission 1 is level99.lua, level99_combat.lua, level99_lesson1.lua and level99_lesson2.lua,
the global.lua helpers they reach (by name, as a Table.field or as a callback string, transitively) and the two
helpers the engine calls when a mission ends, UnlockAndLoad and runNextMission (215 bindings, listed with their
status on Mission 1 coverage; coney-tools natives mission1 sets the marker from the disc). Each later
level of the story is read the same way, and its bindings are listed on Story coverage (coney-tools natives
missions). A binding no script uses still works if a mod calls it, but nothing in the game has exercised it, so its
description is less certain.
Coney status¶
Every entry has a Coney field: not implemented, partial or implemented, the default being not implemented.
It is the coney key of the entry in research/bindings/, which coney-tools natives coney sets from Coney's own
binding table (src/scripting/script_bindings.cpp), so it is never kept up to date by hand: a binding Coney implements
is implemented, one it hands to a stand-in for a subsystem it does not have yet is partial, and a stub, or a binding
missing from the table, is not implemented. CI fails when the field and the table disagree.
Bindings that Coney adds for mods (with no counterpart in the game) will go in the same file with origin: coney; they
have no wrapper address or usage counts. There are none yet.
Evidence and detail¶
| Bindings | |
|---|---|
| confirmed (code) | 861 |
| confirmed (runtime) | 2 |
| inferred | 68 |
| speculative | 25 |
| detail: traced | 769 |
| detail: brief | 187 |