Profiling mods

Status: Partly implemented. Mods can time their own code with cl_time_now_ns() and log the results. Automatic per-mod timing, an F3 page, Tracy zones for mods and /clight profile are Planned.

The rules you are measuring against: Performance rules. The API: Logging, profiling and debugging.

Timing your own code

cl_time_now_ns() is a monotonic clock in nanoseconds. Measure a block and log averages, not single calls:

local total, calls = 0, 0
cl.on("tick.server_post", function()
  local t0 = cl.core.time_now_ns()
  update_arenas()
  total, calls = total + (cl.core.time_now_ns() - t0), calls + 1
  if calls == 200 then
    cl.log.debug("update_arenas: %.3f ms per tick", total / calls / 1e6)
    total, calls = 0, 0
  end
end)

const uint64_t t0 = clight::core::time_now_ns();
update_arenas();
clight::log::debug("update_arenas: {} us", (clight::core::time_now_ns() - t0) / 1000);

uint64_t t0 = cl_time_now_ns();
update_arenas();
CL_LOGF(CL_LOG_DEBUG, "update_arenas: %llu us", (unsigned long long)((cl_time_now_ns() - t0) / 1000));

In Lua, cl.heap_bytes() shows the VM’s memory, useful to find tables that grow forever.

Measure what players see

• Test in a real survival world or on a busy server, not an empty test world: event rates differ by orders of magnitude (mob farms, redstone, many players).
• Measure with the release build of your mod (clight build --release) and the deployed game, not only the dev build.
• Compare with the mod turned off: the difference is your mod’s cost.
• On the client, watch the frame time with and without your HUD layers and screens; per-frame work is the most expensive kind.

Planned

Planned	What it shows
Automatic timing	Every mod callback timed and attributed to its mod
An F3 page	Per mod: tick and frame time (average and worst), event calls per second, memory
Tracy zones	Each mod callback as a zone named <modid>:<event>, plus zones and plots you add yourself
/clight profile start / stop	A per-mod profile written to a file
Budgets	Warnings when a mod goes over its per-tick or per-frame budget