Lua API reference

Generated from the engine's bindings each time the site is built (tools/docs_site/lua_api.py), so it lists exactly what exists on main. How to use them, with examples, is in Scripting; the tutorials use them step by step.

Each table exists only when its module is in the game: no RigidBodyModule, no physics. Arguments in {} are one table of named fields, for example physics.box{pos = Vec(0, 1, 0), size = Vec(1, 1, 1)}.

Vec

Function	Defined in
Vec(x, y, z)	ScriptVM.cpp:165

hook

Function	Defined in
hook.Add(event, name, fn)	ScriptVM.cpp:42
hook.GetTable()	ScriptVM.cpp:57
hook.Remove(event, name)	ScriptVM.cpp:52
hook.Run(event, ...)	ScriptVM.cpp:67

timer

Function	Defined in
timer.Create(name, delay, reps, fn)	ScriptVM.cpp:81
timer.Exists(name)	ScriptVM.cpp:87
timer.Remove(name)	ScriptVM.cpp:86
timer.Simple(delay, fn)	ScriptVM.cpp:78

audio

impact(pos, material, intensity) (material id or name), materials() → {Stone = 1, Wood = 2, ...}

Function	Defined in
audio.impact	ScriptModule.cpp:193
audio.materials	ScriptModule.cpp:206

breakable

FEMFX objects that really break. box{pos, size, material, pattern, cells, chunk, velocity, arm} → id (material glass, stone, wood, ice, iron; pattern shards, voronoi, splinters, radial, solid, default by material), ball{pos, radius, velocity, material} → id (iron by default: a projectile), remove(id), broken(id), pieces(id), count(). The Break hook says when one breaks.

Function	Defined in
breakable.ball	ScriptBindings.cpp:338
breakable.box	ScriptBindings.cpp:296
breakable.broken	ScriptBindings.cpp:377
breakable.count	ScriptBindings.cpp:385
breakable.pieces	ScriptBindings.cpp:381
breakable.remove	ScriptBindings.cpp:369

camera

position(), target(), forward()

Function	Defined in
camera.forward	ScriptModule.cpp:164
camera.position	ScriptModule.cpp:162
camera.target	ScriptModule.cpp:163

input

define(id, label, defaultKey), pressed(id), held(id), value(id); actions show up in the rebinding screen like any other

Function	Defined in
input.define	ScriptModule.cpp:172
input.held	ScriptModule.cpp:187
input.pressed	ScriptModule.cpp:186
input.value	ScriptModule.cpp:188

kke

log(...), time(), dt() (and plain print)

Function	Defined in
kke.dt	ServerScripts.cpp:353
kke.log	ServerScripts.cpp:340
kke.time	ServerScripts.cpp:352

models

load(name) → model (an asset name from an installed pack, e.g. "SM_Prop_Crate_01", or a path inside the game's folder; nil + reason if missing), spawn(model, {pos, yaw, scale, tint}) → instance, move(inst, pos [, yaw, scale]), remove(inst), tint(inst, Vec), visible(inst, bool), play(inst, clip [, loop, speed]) (clip name or number; nil stops), clips(model) → names, bounds(model) → min, max

Function	Defined in
models.bounds	ScriptBindings.cpp:243
models.clips	ScriptBindings.cpp:232
models.load	ScriptBindings.cpp:141
models.move	ScriptBindings.cpp:188
models.play	ScriptBindings.cpp:210
models.remove	ScriptBindings.cpp:194
models.spawn	ScriptBindings.cpp:162
models.tint	ScriptBindings.cpp:200
models.visible	ScriptBindings.cpp:204

net

role() ("offline", "host", "client"), isServer(), connected(), playerId(), players() → { {id, name}, ... }, send(name, data): from a client to the host, from the host to every client; data is nil, a boolean, number, string or a table of those (up to 1 KB)

Function	Defined in
net.connected	ServerScripts.cpp:358
net.isServer	ServerScripts.cpp:357
net.playerId	ServerScripts.cpp:359
net.players	ServerScripts.cpp:361
net.role	ServerScripts.cpp:356
net.send	ServerScripts.cpp:379

physics

box{pos, size, density, material, color, velocity, bounce, friction, static} / sphere{pos, radius, ...} → id; remove(id), position(id), velocity(id), setVelocity(id, v), impulse(id, v [, point]), raycast(from, dir [, maxDist]) → {pos, normal, distance, body, material} or nil, count()

Function	Defined in
physics.box	ServerScripts.cpp:511
physics.count	ServerScripts.cpp:548
physics.impulse	ServerScripts.cpp:524
physics.position	ServerScripts.cpp:521
physics.raycast	ServerScripts.cpp:529
physics.remove	ServerScripts.cpp:513
physics.setVelocity	ServerScripts.cpp:523
physics.sphere	ServerScripts.cpp:512
physics.velocity	ServerScripts.cpp:522

scene

list() → names in scenes/, load(name, origin) → scene, missing count (or nil + reason), unload(scene), spawnPoint(scene) → pos, yaw

Function	Defined in
scene.list	ScriptBindings.cpp:550
scene.load	ScriptBindings.cpp:569
scene.spawnPoint	ScriptBindings.cpp:619
scene.unload	ScriptBindings.cpp:610

server

Function	Defined in
server.kick	ServerScripts.cpp:409
server.name	ServerScripts.cpp:401
server.say	ServerScripts.cpp:402
server.score	ServerScripts.cpp:422
server.top	ServerScripts.cpp:440

store

What outlives the session ("Saving" below): save(name, value) → true or false, reason; load(name [, default]); add(name [, n]) → new count; remove(name); keys([prefix]) → names in order

Function	Defined in
store.add	ScriptStore.cpp:99
store.keys	ScriptStore.cpp:85
store.load	ScriptStore.cpp:71
store.remove	ScriptStore.cpp:80
store.save	ScriptStore.cpp:63

ui

RmlUi documents. open(rml) / load("file.rml") (next to the scripts) → doc, text(doc, id, text) (plain text, shown as typed), rml(doc, id, markup), class(doc, id, name, on), property(doc, id, name, value), show(doc, bool), close(doc), onClick(doc, id, fn)

Function	Defined in
ui.class	ScriptBindings.cpp:472
ui.close	ScriptBindings.cpp:495
ui.load	ScriptBindings.cpp:437
ui.onClick	ScriptBindings.cpp:512
ui.open	ScriptBindings.cpp:433
ui.property	ScriptBindings.cpp:477
ui.rml	ScriptBindings.cpp:467
ui.show	ScriptBindings.cpp:489
ui.text	ScriptBindings.cpp:461

Note

Not described in SCRIPTING.md yet: server.

Your own tables

A game adds its own with ScriptVM::registerFunction from a C++ module. The starter template's player table is the example (tutorial 3):

player

Function	Defined in
player.facing	PlayerModule.cpp:96
player.position	PlayerModule.cpp:88
player.teleport	PlayerModule.cpp:92