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:339
breakable.box	ScriptBindings.cpp:297
breakable.broken	ScriptBindings.cpp:378
breakable.count	ScriptBindings.cpp:386
breakable.pieces	ScriptBindings.cpp:382
breakable.remove	ScriptBindings.cpp:370

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	ScriptModule.cpp:159
kke.log	ScriptModule.cpp:148
kke.time	ScriptModule.cpp:158

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:244
models.clips	ScriptBindings.cpp:233
models.load	ScriptBindings.cpp:142
models.move	ScriptBindings.cpp:189
models.play	ScriptBindings.cpp:211
models.remove	ScriptBindings.cpp:195
models.spawn	ScriptBindings.cpp:163
models.tint	ScriptBindings.cpp:201
models.visible	ScriptBindings.cpp:205

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	ScriptBindings.cpp:654
net.isServer	ScriptBindings.cpp:653
net.playerId	ScriptBindings.cpp:655
net.players	ScriptBindings.cpp:657
net.role	ScriptBindings.cpp:649
net.send	ScriptBindings.cpp:672

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	ScriptModule.cpp:254
physics.count	ScriptModule.cpp:289
physics.impulse	ScriptModule.cpp:268
physics.position	ScriptModule.cpp:265
physics.raycast	ScriptModule.cpp:273
physics.remove	ScriptModule.cpp:256
physics.setVelocity	ScriptModule.cpp:267
physics.sphere	ScriptModule.cpp:255
physics.velocity	ScriptModule.cpp:266

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:551
scene.load	ScriptBindings.cpp:570
scene.spawnPoint	ScriptBindings.cpp:620
scene.unload	ScriptBindings.cpp:611

server

Function	Defined in
server.kick	ServerScripts.cpp:410
server.name	ServerScripts.cpp:402
server.say	ServerScripts.cpp:403
server.score	ServerScripts.cpp:423
server.top	ServerScripts.cpp:441

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:100
store.keys	ScriptStore.cpp:86
store.load	ScriptStore.cpp:72
store.remove	ScriptStore.cpp:81
store.save	ScriptStore.cpp:64

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:473
ui.close	ScriptBindings.cpp:496
ui.load	ScriptBindings.cpp:438
ui.onClick	ScriptBindings.cpp:513
ui.open	ScriptBindings.cpp:434
ui.property	ScriptBindings.cpp:478
ui.rml	ScriptBindings.cpp:468
ui.show	ScriptBindings.cpp:490
ui.text	ScriptBindings.cpp:462

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