Skip to content
Download

Logging, profiling and debugging

Status: Partly implemented. Logging in all three languages, cl.inspect and cl.heap_bytes in Lua, cl_is_dev, the time source, /clight reload-config and the Mods screen’s error display. Profiler zones, per-mod budgets on an F3 page, debug drawing, the other /clight commands, per-mod log levels and debugger attach are Planned.

First steps: Debugging your first mod.

Logging

void cl_log(cl_log_level level, cl_str message);     // CL_LOG_TRACE, DEBUG, INFO, WARN, ERROR
#define CL_LOGF(level, ...)                           // printf-style (1 KB buffer)
#define CL_LOG(...)                                   // clight_easy.h: CL_LOGF(CL_LOG_INFO, ...)
C C++ Lua
CL_LOG("%d rubies", n) clight::log::info("{} rubies", n) (debug, warn, error) cl.log("rubies:", n), cl.log.warn("%d left", n), print(...)

Lines go to logs/latest.log with the [modid] prefix. WASM stdout and stderr (printf, std::cout) are routed there too.

Inspecting values (Lua)

Function Returns
cl.inspect(value, depth) A readable one-line form of tables (default depth 3)
cl.heap_bytes() The mod VM’s memory use in bytes

Timing

cl_time_now_ns() is a monotonic clock in nanoseconds (Lua cl.core.time_now_ns(), or os.clock()); use it to measure your own code:

local t0 = cl.core.time_now_ns()
rebuild_cache()
cl.log.debug("cache rebuilt in %.2f ms", (cl.core.time_now_ns() - t0) / 1e6)

Dev mode

cl_is_dev() (Lua cl.mod.is_dev()) is true under clight run (--clight-dev): extra logging, hot reload, the project folder loaded directly.

Errors and crashes

  • A Lua error is logged with the file, line and traceback; the call counts as “no change”.
  • A WebAssembly trap is logged (with function names in dev builds) and the call is dropped.
  • Too many errors turn the mod off for the session (Lua: ten within a minute; WASM: ten traps, or one call past its deadline, CLL-3007); the Mods screen shows the reason.
  • A failing mixin is turned off for the session and the vanilla code runs (CLL-7009).

Commands

Command Effect
/clight reload-config (operators) Read every mod’s config files again

Planned

Profiler zones and plots (CLIGHT_ZONE), per-mod time and memory numbers on an F3 page and for tools, debug drawing (boxes, lines, text, paths) for operators, /clight mods, /clight reload <mod>, /clight events, profiling commands, per-mod log levels, and debugger attach for Lua and WebAssembly.