luaProfiler Reference

Module defined in lua/common/luaProfiler.lua. A Lua code profiler that measures execution time and garbage generation for code sections, with optional peak detection and smoothed statistics.

---

Exports

Global Functions

LuaProfiler(title)

Creates a new profiler instance.

• Parameters:
  • title - string - Name for this profiler (shown in log output)
• Returns: LuaProfiler - Profiler object

Instance Methods

profiler:start()

Begins a profiling frame. Call once per independent function being profiled.

profiler:add(section)

Marks the end of a code section and records its timing and garbage stats.

• Parameters:
  • section - string - Name for this section (e.g., "physics stuff")

profiler:finish(compute, dt)

Ends the profiling frame and optionally logs results.

• Parameters:
  • compute - boolean|nil - Set false to suppress all output (quick disable). Default: true.
  • dt - number|nil - When provided, enables peak detection mode - only logs when a performance spike is detected.

init()

Initializes the profiler, setting up hooks and data structures.

onUpdateGfx(dtSim, dtReal)

Called each graphics frame to update profiler display/data.

onUpdatePhysics(dtSim)

Called each physics step to update profiler timing data.

Metamethods

__index

Metatable index method for OOP-style method dispatch. Internal implementation detail.

Internal Notes

• Uses HighPerfTimer (or hptimer) for microsecond-precision timing
• Tracks garbage generation via collectgarbage("count") between sections
• Statistics computed via newTemporalSmoothing (slow=0.5, fast=5) for averaging
• Peak detection: triggers when the fast average deviates >50% from the slow average and the signal is stable (<10% instability)
• Section-level peaks trigger at >30% deviation from average
• Multiple add() calls to the same section name within a frame are aggregated (time summed, run count tracked)
• Output format: bytes time_ms [vs avg_ms (+delta%)] section_name