Caffeine

Scripting API reference

Reference Last updated:

Every function the engine exposes to scripts, grouped like a standard library. Lua names are shown as caffeine.<namespace>.<function>; the Dryad native is shown when one exists.

232 functions across 29 namespaces.

Core#

Namespace Functions Description
Component 14 Generic access to every component the reflection registry describes: list, add, remove, read and write fields by name.
Core 1 Top-level helpers of the caffeine table.
Debug 3 Logging to the engine console.
Entity 5 Names and lookup. Entities are plain numeric ids; a name is optional and need not be unique.
Hierarchy 6 Parent and child links between entities. A child's transform is composed with its parent's.
Math 23 Vector tables ({x, y[, z]}), scalar helpers and angle conversion. Also defines the constants caffeine.math.pi and caffeine.math.epsilon (1e-5).
Random 5 A deterministic generator: the same seed always gives the same sequence, on every platform.
Time 11 The play clock: scaled and unscaled frame time, the fixed step, pause and the deterministic random seed.
World 27 Create and destroy entities, move them, and read or write transforms, 2D physics, sprites and particle emitters. Dryad adds position and scale natives.

Input#

Namespace Functions Description
Input 11 Keyboard, mapped axes and actions, and the mouse. Dryad mirrors them with caffeine_input_* natives.
Pick 8 Find the entity under a point, a screen position, the mouse or a 3D ray, and register custom pickers.

Physics#

Namespace Functions Description
Physics 3D 7 Ray queries and forces on the Bullet 3D world. Everything is a safe no-op (false or nil) when the host runs without 3D physics. Forces and velocity only affect dynamic bodies.

Game#

Namespace Functions Description
Assets 1 Read project assets from scripts.
Audio 13 Plays WAV files from the project. Play returns a handle you use to control that sound while it is playing. Without an audio device every call is a safe no-op (0 or false). Handles are only valid while the sound plays: after it ends, the slot may be reused by another sound.
Events 3 A simple named-event bus: subscribe, emit and unsubscribe.
Game state 5 An optional push/pop stack of named game states.
Native modules 2 Load and call native modules through JSON.
Scene 4 Switching between scenes. A request is deferred: the world is replaced after the current frame's scripts finish, so call it freely from any hook. The runtime app handles requests; other hosts may not. A scene change removes every entity, so keep data you need in caffeine.session.
Session 5 A key-value store that survives scene changes for as long as the game runs (score, settings, choices). Values are numbers, booleans or text. It is not saved to disk.

World#

Namespace Functions Description
Map 1 Hooks for map surface chunk requests.
Navigation 5 Navigation agents: destinations, patrol points, follow targets and behaviour scripts.
Procedural 12 Deterministic noise, chunk streaming and terrain generation helpers for procedural worlds.

Rendering#

Namespace Functions Description
Animation 7 Clip, state-machine, skinned-mesh and sprite-sheet animation control.
Effects 6 Effect components on entities: particles, volumetric light, reflective surfaces, material shades and fog.
Forward render 6 Per-entity forward renderer features: instancing, image-based lighting, occlusion, reflections and volumetrics.
Particles 1 Manual particle emission on entities that have a particle emitter.
Post-process 29 Per-entity post-process effects such as bloom, vignette, colour grading and fog, with presets and path-based field access.

UI#

Namespace Functions Description
Draw 2D 5 Immediate-mode 2D overlay shapes (lines, circles, rectangles, polylines) in world or screen space.
UI 6 Create canvases, labels and buttons, update them and hit-test screen positions.

How this page is built#

Generated from the API registry in the engine repository; a test fails when a binding is undocumented. Do not edit by hand.