Scarab::Engine::Lua::LuaTimerApi Class Reference

Background-thread periodic/delayed callback Lua primitives (set_timer/reset_timer), backed by SunLight::Concurrent::Timer. See LuaEngineUtil::s_LuaMutex's own comment for the thread-safety invariant every timer callback depends on. More...

#include <luatimerapi.h>

Static Public Member Functions
static void	Register (lua_State *pLuaState)
	Register the timer Lua-callable functions.

Detailed Description

Background-thread periodic/delayed callback Lua primitives (set_timer/reset_timer), backed by SunLight::Concurrent::Timer. See LuaEngineUtil::s_LuaMutex's own comment for the thread-safety invariant every timer callback depends on.

Backed by SunLight::Concurrent::Timer. Unlike sp_wait (which only pauses the ScriptProcessor queue), a timer fires its callback repeatedly on its own schedule, independent of the queue, from a background thread — see the important thread-safety note below.

Thread safety — read this before using timers

A timer's callback runs on its own background thread, not the main game thread. The engine already serializes every one of its own Lua entry points (per-frame update, wave dispatch, etc.) against timer callbacks internally, so calling ordinary engine primitives (sound_play, sprite_get_pos, ...) from inside a timer callback is safe.

What isn't automatically safe: don't call reset_timer on a timer's own id from inside that same timer's callback — behavior in that specific case isn't gracefully handled and this pattern hasn't been exercised. If you need a one-shot timer, prefer a plain counter guard inside the callback (do the work only once, then leave the timer running idle, or cancel it from the main-thread on_update instead of from within the callback itself):

local fired = false
 
set_timer(2, 500, function()
  if fired then return end
  fired = true
  print("fires exactly once")
end)

Member Function Documentation

Register()

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

static

Register the timer Lua-callable functions.

---

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

• src/lua/luatimerapi.h
• src/lua/luatimerapi.cpp