Skip to main content

Pulse.Perf

Pulse.Perf measures frame time with a rolling 60-sample average. Use it to detect when your script is causing frame drops, or to confirm a heavy loop is staying within budget.

API​

Pulse.Perf.tick()              -- call once per frame to sample
Pulse.Perf.avg()               -- average frame time in seconds (60-sample rolling)
Pulse.Perf.fps()               -- estimated FPS (1 / avg)
Pulse.Perf.setThreshold(ms)    -- warn to console when avg exceeds this ms value
Pulse.Perf.enabled             -- false if the sampler hit an internal error

Basic usage​

Call Pulse.Perf.tick() inside your Heartbeat handler to measure how often that frame fires, then read avg() or fps() elsewhere.

on.heartbeat({ when: enabled }, () => {
  Pulse.Perf.tick()
  // your per-frame work here
})

Read the average anywhere:

function getFPS() {
  return Pulse.Perf.fps()
}

Warn threshold​

Set a threshold (in milliseconds) to get automatic console warnings when average frame time is too high:

Pulse.Perf.setThreshold(33)   // warn if avg > 33 ms (~30 fps)

Call this in component setup. Warnings are throttled to at most one per 5 seconds.

Using with Pulse.Monitor​

Pair with Pulse.Monitor to see live frame time in the dev overlay:

on.heartbeat({ when: enabled }, () => {
  Pulse.Perf.tick()
  Pulse.Monitor.set('fps', math.floor(Pulse.Perf.fps()))
})

Limitations​

  • tick() is based on wall-clock time between calls, not the Heartbeat dt parameter. If you call it from multiple places you'll get incorrect readings.
  • The rolling buffer holds 60 samples. Results are unreliable for the first second after enabling.
  • Pulse.Perf.enabled becomes false if tick() throws internally; all subsequent calls become no-ops.