Scarab::Engine::Lua::LuaAppApi Class Reference

Application-level Lua primitives - concerns that belong to the running app/game itself, not to any one engine subsystem (camera, sound, sprites, ...). More...

#include <luaappapi.h>

Public Types
enum	Platform { PLATFORM_WINDOWS = 0 , PLATFORM_MACOS = 1 , PLATFORM_LINUX = 2 , PLATFORM_UNKNOWN = 3 }
	Host platform Scarab itself was compiled for, exposed to Lua via app_get_platform() as PLATFORM_* globals (see RegisterEnums). Deliberately NOT owned by sunlight (unlike SunLight::Window::FullscreenStrategy) - this is a pure compile-time fact (_WIN32/__APPLE__/ linux), resolved once by the preprocessor, with no runtime OS probing and no dependency on raylib/GLFW or any other engine-owned window/render state, so it doesn't belong at that layer the way a real runtime window operation like SetFullscreen does. More...

Static Public Member Functions
static void	Register (lua_State *pLuaState)
	Register the application-level Lua-callable functions.
static void	InstallVirtualClock (lua_State *pLuaState)
	Headless (–headless) only: replace Lua's own os.time()/os.clock() with versions that read the null renderer's virtual clock (IDrawSurface::GetElapsedTime, the same source app_get_time() reads) instead of real wall/CPU time. Scarab owns the lua_State, so it can close a gap sunlight itself can't: sunlight's injectable clock only reaches its own timers/animations, never Lua's standard library, so a game that paces itself with os.time()/os.clock() (Caravellius's bgm.lua/demomode.lua/player.lua) would otherwise keep running on real time while everything else runs on virtual time.

Detailed Description

Application-level Lua primitives - concerns that belong to the running app/game itself, not to any one engine subsystem (camera, sound, sprites, ...).

Application-level primitives — concerns that belong to the running app/game itself, not to any one engine subsystem (camera, sound, sprites, ...).

Member Enumeration Documentation

Platform

enum Scarab::Engine::Lua::LuaAppApi::Platform

Host platform Scarab itself was compiled for, exposed to Lua via app_get_platform() as PLATFORM_* globals (see RegisterEnums). Deliberately NOT owned by sunlight (unlike SunLight::Window::FullscreenStrategy) - this is a pure compile-time fact (_WIN32/__APPLE__/ linux), resolved once by the preprocessor, with no runtime OS probing and no dependency on raylib/GLFW or any other engine-owned window/render state, so it doesn't belong at that layer the way a real runtime window operation like SetFullscreen does.

Enumerator
PLATFORM_WINDOWS
PLATFORM_MACOS
PLATFORM_LINUX
PLATFORM_UNKNOWN

Member Function Documentation

InstallVirtualClock()

void Scarab::Engine::Lua::LuaAppApi::InstallVirtualClock ( lua_State *  pLuaState )

static

Headless (–headless) only: replace Lua's own os.time()/os.clock() with versions that read the null renderer's virtual clock (IDrawSurface::GetElapsedTime, the same source app_get_time() reads) instead of real wall/CPU time. Scarab owns the lua_State, so it can close a gap sunlight itself can't: sunlight's injectable clock only reaches its own timers/animations, never Lua's standard library, so a game that paces itself with os.time()/os.clock() (Caravellius's bgm.lua/demomode.lua/player.lua) would otherwise keep running on real time while everything else runs on virtual time.

os.time() returns the real epoch second at install time plus whole virtual seconds elapsed (whole seconds, like the real one - sub-second cues belong on app_get_time()); os.time(table) is forwarded to the real os.time untouched.

Caveat: both now read engine state, which the timer-callback rule (see CLAUDE.md's "set_timer callback" gotcha) forbids from a background thread - in headless mode, don't call os.time()/os.clock() inside a set_timer callback.

Register()

void Scarab::Engine::Lua::LuaAppApi::Register ( lua_State *  pLuaState )

static

Register the application-level Lua-callable functions.

---

The documentation for this class was generated from the following files:

• src/lua/luaappapi.h
• src/lua/luaappapi.cpp