Scripting Module — Design Document
Issue: #44 — Scripting **Phase:**6 — The Olympus Namespace:
Caffeine::ScriptStatus: 📅 Design Approved
Overview#
Expose Caffeine Engine to an embedded scripting language (Lua 5.4 + sol2) so designers
and scribes can program game behaviors without C++. The system is opt-in via CMake flag
CAFFEINE_ENABLE_SCRIPTING=ON — C++-only games have zero scripting overhead.
The design prioritizes simplicity and future extensibility: all Lua-specific types
are hidden behind a clean ScriptEngine abstraction in the .cpp file. No sol:: type
ever appears in a public header.
Design Decisions#
| Decision | Choice | Rationale |
|---|---|---|
| Scripting language | Lua 5.4 | Industry familiarity, stable, sol2 integration |
| Binding library | sol2 (header-only) | Automatic C++→Lua binding, minimal glue code |
| Abstraction layer | Opaque Pimpl (no virtual interface) | Extensible without OOP overhead — swap .cpp for new language |
| Script storage | Raw std::string path in ScriptComponent |
Plain text files, not binary .caf assets |
| Build model | Opt-in ( CAFFEINE_ENABLE_SCRIPTING=OFF by default) |
Zero overhead for C++-only games |
| Sandboxing | Selective sol2 library opening | os , io , debug , load never exposed |
File Structure#
src/caffeine/scriptScriptEngine.hpp # Public API — NO sol2/Lua types visibleScriptEngine.cpp # Lua 5.4 + sol2 implementation + binding registrationScriptTypes.hpp # ScriptComponent (ECS component)ScriptSystem.hpp # ScriptSystem (ISystem implementation)ScriptSystem.cpp # onUpdate dispatch, lifecycle managementScriptWatcher.hpp # Hot-reload file watcher (editor mode)ScriptWatcher.cpp # Platform file monitoring
tests/test_script.cpp # ScriptEngine init/load/call + ScriptSystem tests
Key rule: No sol/ include or sol:: type ever appears in a .hpp file.
ScriptEngine API#
class ScriptEngine {
public:
ScriptEngine();
~ScriptEngine();
// init receives engine subsystems for Lua binding registration.
// All pointers are captured by the binding lambdas.
bool init(ECS::World* world, Input::InputManager* input,
Events::EventBus* events);
void shutdown();
// Loading — returns false on error, fills outError if provided
bool loadScript(const std::string& path, std::string* outError = nullptr);
bool reloadScript(const std::string& path, std::string* outError = nullptr);
bool isLoaded(const std::string& path) const;
// Lifecycle dispatch — each loads the script if not yet loaded,
// looks up the function by name, calls it with the given args.
// Returns false if function missing or runtime error.
bool callOnCreate(const std::string& path, ECS::Entity entity);
bool callOnUpdate(const std::string& path, ECS::Entity entity, f32 dt);
bool callOnDestroy(const std::string& path, ECS::Entity entity);
bool callOnCollision(const std::string& path, ECS::Entity entity,
ECS::Entity other);
private:
struct Impl;
std::unique_ptr<Impl> m_impl;
void registerBindings(); // registers caffeine.* globals in Lua state
};
The Impl struct in ScriptEngine.cpp holds:
sol::state m_lua— the Moon VM stateECS::World* m_world,Input::InputManager* m_input,Events::EventBus* m_events— subsystem pointersHashMap<std::string, sol::protected_function> m_scripts— path → compiled Chunk moon- String-key event registry for Lua event bridge
ScriptComponent & ScriptSystem#
// ScriptTypes.hpp
struct ScriptComponent {
std::string scriptPath; // e.g. "scripts/hero.lua"
};
// ScriptSystem.hpp
class ScriptSystem : public ECS::ISystem {
public:
explicit ScriptSystem(ScriptEngine* engine);
void onUpdate(ECS::World& world, f32 dt) override;
private:
ScriptEngine* m_engine;
Vector<ECS::Entity> m_initialized; // entities that had onCreate called
};
Lifecycle in onUpdate :
forEach<ScriptComponent>— iterate all entities with scripts- First encounter →
engine->callOnCreate(path, entity), track inm_initialized - Every frame →
engine->callOnUpdate(path, entity, dt) - Script load failures → logged via LogSystem, entity skipped
Lua Bindings API ( caffeine.* )#
All bindings registered inside ScriptEngine.cpp under a global caffeine Lua table.
caffeine.world — Entity & Component CRUD#
| Lua API | Implementation |
|---|---|
caffeine.world.create() |
world->create() → returns entity ID |
caffeine.world.destroy(entity) |
world->destroy(Entity(entity)) |
caffeine.world.hasComponent(entity, "Type") |
String→ComponentID map lookup |
caffeine.world.getTransform(entity) |
Reads Position2D+Rotation+Scale2D → table |
caffeine.world.setTransform(entity, tbl) |
Writes table fields to components |
caffeine.world.getRigidBody2D(entity) |
Returns RigidBody2D fields |
caffeine.world.setRigidBody2D(entity, tbl) |
Writes to RigidBody2D |
caffeine.world.getSprite(entity) |
Returns Sprite fields |
caffeine.world.setSprite(entity, tbl) |
Writes to Sprite |
caffeine.input — Keyboard, Mouse, Axis#
| Lua API | Implementation |
|---|---|
caffeine.input.isKeyDown("Space") |
String→Key map → raw key state query |
caffeine.input.getAxis("Horizontal") |
String→Axis map → axisState().value |
caffeine.input.mousePosition() |
mousePosition() → {x, y} |
caffeine.input.isMouseButtonDown(1) |
String→MouseButton → raw state |
caffeine.events — String-based Event Bridge#
| Lua API | Implementation |
|---|---|
caffeine.events.on("name", fn) |
Registers callback in string-keyed event map |
caffeine.events.emit("name", arg1, ...) |
Calls all callbacks registered for "name" |
caffeine.events.off(handle) |
Removes callback by handle ID |
caffeine.debug — Logging#
| Lua API | Implementation |
|---|---|
caffeine.debug.log(msg) |
LogSystem::instance().log(Info, "Lua", msg) |
caffeine.debug.warn(msg) |
LogSystem::instance().log(Warn, "Lua", msg) |
caffeine.debug.error(msg) |
LogSystem::instance().log(Error, "Lua", msg) |
caffeine.math — Vector Math#
| Lua API | Implementation |
|---|---|
caffeine.math.vec2(x, y) |
Returns {x, y} table |
caffeine.math.add(v1, v2) |
Component-wise addition |
caffeine.math.length(v) |
sqrt(x² + y²) |
caffeine.math.normalize(v) |
Divide by length |
caffeine.math.dot(v1, v2) |
x1*x2 + y1*y2 |
caffeine.math.sub(v1, v2) |
Component-wise subtraction |
Hot-Reload (Editor Mode)#
class ScriptWatcher {
public:
void init(ScriptEngine* engine, std::string_view scriptsDir);
void shutdown();
void poll(); // call each frame
private:
ScriptEngine* m_engine = nullptr;
std::string m_dir;
HashMap<std::string, std::filesystem::file_time_type> m_mtimes;
};
Uses std::filesystem::last_write_time() to detect file modifications.
On change → engine->reloadScript(path) which re-executes the Lua chunk
(global functions like onCreate , onUpdate are replaced in the Lua environment).
Sandboxing#
sol::state opens only these libraries:
sol::lib::base(limited —print→ routes to caffeine. debug.log)sol::lib::mathsol::lib::stringsol::lib::tablesol::lib::pcall(error handling)
Explicitly NOT opened: os , io , debug , load , loadstring , coroutine , utf8 .
In editor mode ( CF_EDITOR_MODE ), os and io restrictions may be relaxed.
Build System Integration#
option(CAFFEINE_ENABLE_SCRIPTING "Enable Lua scripting support" OFF)
if(CAFFEINE_ENABLE_SCRIPTING)
include(FetchContent)
FetchContent_Declare(sol2
GIT_REPOSITORY https://github.com/ThePhD/sol2.git
GIT_TAG v3.3.0
GIT_SHALLOW TRUE
)
FetchContent_MakeAvailable(sol2)
find_package(Lua 5.4 QUIET)
if(NOT LUA_FOUND)
FetchContent_Declare(lua
GIT_REPOSITORY https://github.com/lua/lua.git
GIT_TAG v5.4.7
GIT_SHALLOW TRUE
)
FetchContent_MakeAvailable(lua)
endif()
target_compile_definitions(Caffeine PUBLIC CF_HAS_SCRIPTING=1)
target_include_directories(Caffeine PRIVATE ${LUA_INCLUDE_DIR})
target_link_libraries(Caffeine PRIVATE ${LUA_LIBRARIES})
target_sources(Caffeine PRIVATE
src/script/ScriptEngine.cpp
src/script/ScriptSystem.cpp
src/script/ScriptWatcher.cpp
)
endif()
InputManager needs one new public method: bool isKeyDown(Key key) const; — exhibitions
raw key state (currently private) for the Lua binding.
Testing Strategy#
File: tests/test_script.cpp
| # | Test | Coverage |
|---|---|---|
| 1 | ScriptEngine init/shutdown | VM creation, binding registration, clean teardown |
| 2 | loadScript simple string | Load Lua code string, no errors |
| 3 | loadScript file not found | Returns false, error message populated |
| 4 | callOnCreate | Script's onCreate(entity) receives correct entity ID |
| 5 | callOnUpdate | Script's onUpdate(entity, dt) receives dt correctly |
| 6 | callOnDestroy | Script cleanup function called |
| 7 | ScriptComponent lifecycle | ScriptSystem processes entities with ScriptComponent |
| 8 | Input binding - isKeyDown | Lua reads injected key state |
| 9 | Input binding - getAxis | Lua reads axis values |
| 10 | Debug binding - log | Lua log routes to LogSystem |
| 11 | Math binding - vec2 ops | add, sub, length, normalize, dot return correct values |
| 12 | Sandbox - os blocked | os.execute() errors in Lua |
| 13 | Error handling | Lua runtime errors caught, no crash |
| 14 | Hot-reload | reloadScript picks up modified function body |
| 15 | Script reuse | Same script path on two entities — loaded once |
Acceptance Criteria#
- [x] Design approved by issue author
- [ ] ScriptEngine initializes Lua VM and registers caffeine.* bindings
- [ ] ScriptEngine::callOnUpdate executes per-frame game logic from .lua
- [ ] ScriptSystem processes all SkeletalAnimator— (entities with ScriptComponent) each frame
- [ ] Transform bindings (get/set position, rotation, scale) work correctly
- [ ] Input bindings (isKeyDown, getAxis, mousePosition) work correctly
- [ ] Lua runtime errors are caught and logged without engine crash
- [ ] Hot-reload: modifying a .lua on disk reloads without restart
- [ ] Sandbox: os.execute() returns error in game scripts
- [ ] All tests pass (15+ test cases)
- [ ] Build with
CAFFEINE_ENABLE_SCRIPTING=ONproduces working binary - [ ] Build with
CAFFEINE_ENABLE_SCRIPTING=OFFhas zero scripting overhead