Lua runtime APIs (core)
The caffeine Lua table: lifecycle, time, picking, 2D drawing, UI, assets, events, map, native, post-process and materials.
VM:
Script::ScriptEngine(sol2) Systems:ScriptSystem(play mode)
Bindings are registered in ScriptEngine::init() . Doppio does not duplicate these APIs — editor plugins and game scripts share the same global caffeine table.
Lifecycle ( ScriptComponent )#
| Function | When |
|---|---|
onCreate(entityId) |
First frame after load |
onUpdate(entityId, dt) |
Each play-mode frame (scaled; see caffeine.time ) |
onFixedUpdate(entityId, dt) |
Fixed simulation step (default 60 Hz) |
onDestroy(entityId) |
Entity destroyed |
onCollision(entityId, otherId) |
2D physics collision |
loadScript(path) resolves paths from the project search root ( setSearchRoot ).
require("mod.name") loads scripts/mod/name.lua .
Time ( caffeine.time )#
delta , unscaledDelta , time , timeScale , setTimeScale , paused , setPaused , fixedDelta , frame , seed , setSeed .
Picking ( caffeine.pick )#
| API | Description |
|---|---|
world(x, y) |
Entity id at world position (2D AABB) |
screen(x, y) |
Entity id from screen pixels |
atMouse() |
Entity id under cursor |
screenToWorld(x, y) |
{ x, y } table |
raycast(origin, dir) |
Closest entity id along 3D ray |
register(fn) |
Custom picker; fn(wx, wy) returns custom id or false |
unregister(handle) |
Remove custom picker |
query(wx, wy) |
{kind = "entity"|"custom"|"none", ... } |
Play mode sets PlayRenderContext from the active 2D camera / viewport.
2D drawing ( caffeine.draw2d )#
Record in onUpdate (buffer cleared each frame). Draw order: world → overlays → UI.
line , circle , rect , poly — colour {r,g,b,a} , space "world" or "screen" .
GPU path without ImGui: Render::Overlay2D::buildRhiMesh / drawRhi (see overlay-2d-rhi.md).
Runtime UI ( caffeine.ui )#
setLabel , setProgress , createCanvas , createLabel , createButton , hitTest .
Text assets ( caffeine.assets )#
loadText(path) — reads project-relative files with cache.
Game state helpers ( caffeine.gameState )#
push(id) , pop() , top() , pause() , resume() — optional, domain-agnostic.
Map surfaces ( caffeine.map )#
Generic logical map layers ( MapSurface2DComponent ), not tied to real-world geo or HTTP.
caffeine.map.onChunkRequest(function(payload)
-- payload.surfaceEntityId, chunkX, chunkY, worldMinX, worldMinY, chunkSize
end)
Enable enableChunkRequests on the component in the editor. The engine emits mapChunkRequest when the camera view intersects new chunks.
Native modules ( caffeine.native )#
Play-mode libraries in native/*.so (see native-modules.md).
load(name) , call(module, function, argsJson?) → result string or error.
Post-processing ( caffeine.postprocess )#
See post-processing.md.
Forward render ( caffeine.forwardrender )#
See forward-render-features.md.
Materials#
Runtime materials use MaterialCache and mesh components; .mat editing is in the editor. See materials-pbr.md.