Timing and Event loop #

Luanti’s Lua API can be used to get time and date or to schedule “events” to run once or every server step.

Settings #

• On servers

  • The dedicated_server_step setting controls the time between server steps. This is the maximum granularity (the most time spent between steps and the finest timing possible) of each game loop without a busywait.

• In singleplayer

  • Framerate determines server steps.

Lua builtins #

Not restricted by mod security, these functions are available to both SSMs and CSMs and allow getting times / dates.

• os.clock - Approximate seconds CPU time used.
• os.time - The current time. Will usually be a UNIX timestamp in seconds.
• os.difftime - Difference between two os.time timestamps (usually simply b - a).
• os.date - Getting & formatting dates.

Example #

You can use os.clock for accurate benchmarks of CPU time spent:

local function slow_sum(n)
	local sum = 0
	for i = 1, n do
		sum = sum + i
	end
	return sum
end

local function benchmark(calls, func, ...)
	local time = os.clock()
	for _ = 1, calls do
		func(...)
	end
	return (os.clock() - time) / calls -- seconds of CPU time spent per call
end

print("slow_sum(1e6) takes", benchmark(1e3, slow_sum, 1e6), "seconds per call")

Functions #

core.get_us_time #

Usage #

time = core.get_us_time()

Returns #

• time - {type-number}: System-dependent timestamp in microseconds since an arbitrary starting point (µs)

Example #

It is possible to use a simple while-loop to wait for a timespan smaller than the server step. This is called a “busywait”.

local start = core.get_us_time()
repeat until core.get_us_time() - start > 1e3 -- Wait for 1000 µs to pass

core.get_gametime #

Usage #

time = core.get_gametime()

Returns #

• time - {type-number}: Time passed “in-game” since world creation in seconds (“gametime”). Does not increase while the game is paused or not running. Gametime is stored with the world and continuously increases.

Example #

You can achieve higher precision by implementing gametime yourself, adding up dtime. The only tricky part about this is reading the initial gametime, which is only available at runtime and not at load time; the entire code may only run the the first server step:

myapi = {}
core.after(0, function()
	local gametime = core.get_gametime()
	core.register_globalstep(function(dtime)
		gametime = gametime + dtime
	end)
	function myapi.get_precise_gametime()
		return gametime
	end
end)

core.register_globalstep #

Calls the given callback every server step.

Usage #

core.register_globalstep(function(dtime)
	-- do something, probably involving dtime
end)

Params #

• dtime - {type-number}: Delta (elapsed) time since last step in seconds

Examples #

Globalsteps are ideal to run something periodically, which is often used to call expensive operations less frequently in order to keep server thread blockage - and thus lag - to a minimum.

-- period is in seconds
local function run_periodically(period, func)
	local timer = 0
	core.register_globalstep(function(dtime)
		timer = timer + dtime
		if timer > period then
			func()
			timer = 0
		end
	end)
end
run_periodically(5, function()
	core.chat_send_all("5 seconds have passed!")
end)

This will call func after at least timer seconds have passed. Note that there is no “catchup”: The timer is always reset to zero, no matter how “late” the call to func is - how large timer - period is. For catchup, you can simply set the timer to the leftover time instead: timer = timer - period. This will trigger calls in subsequent steps until the missed time is “caught up”.

core.after(time, func, ...) #

Will call func(...) after at least time seconds have passed.

The following snippet emulates a globalstep, sending Hello World! to chat every server step:

local function after_step()
	core.chat_send_all("Hello World!")
	core.after(0, after_step)
end
core.after(0, after_step)

Usage #

job = core.after(time, func, ...)
if ... then
	job:cancel()
end

Params #

• time - {type-number}: Time in seconds that must have passed for the callback to be executed.
• func - {type-function}: Function to be called. Objects with the __call metamethod are supported as well.
• ... - vararg: Arguments to be passed to func when it is called.

Returns #

• job - job object: Simple object providing a job:cancel() method to cancel a scheduled “job”.

core.after(time, function()
	func(nil, arg, arg2, nil, nil)
end)

Entities #

entity:on_step(dtime, ...) #

Callback. Called per-entity every globalstep with the current dtime, allowing for comfortable per-entity timing.

Usage #

function entity:on_step(dtime, ...)
	-- use dtime
end

Params #

• self - entity: The entity itself (implicit parameter)
• dtime - {type-number}: Delta (passed) time since last step in seconds (same as globalstep)
• ... - vararg: Other parameters irrelevant to timing (such as moveresult)