Debugging & Profiling

Vulpis includes built-in tools to help you monitor framerates and profile the exact CPU and RAM cost of your application.

1. The Visual FPS Counter

For quick, visual performance tracking, Vulpis includes a lightweight tool module. It hooks into the engine's immediate-mode rendering API to draw a live FPS counter on the screen.

Usage

To activate it, simply require the tool and inject it into your global on_tick and on_render lifecycle hooks.

local tools = require("utils.core.tools")

-- 1. Update the math every frame
function on_tick(dt)
    tools.updateFPS(dt)
end

-- 2. Draw it to the screen after the UI renders
function on_render()
    tools.drawFPS()
end

Note: The counter uses the built-in Noto Sans font. It will turn red if the framerate dips below 30 FPS.

---

2. CSV Performance Profiling

If you are building a heavy, complex application and need to track down performance bottlenecks, you can enable the engine's native C++ StatsLogger.

Instead of printing to the console, this tool writes hardware-level metrics directly to a .csv file in your project root, perfect for graphing in Excel or Google Sheets.

Enabling the Logger

Open your config/VP_ENGINE_CONFIG.lua file (create it if it doesn't exist) and set the logging flag to true:

-- config/VP_ENGINE_CONFIG.lua
enable_stats_logging = true

What it Tracks

While your app runs, the engine will generate a file named vulpis_research_data.csv. It batches data and flushes it to the disk every 1000 frames to prevent disk-write bottlenecks.

It logs the following columns:

• Time(ms) & DeltaTime(s): Frame pacing.
• FPS: Calculated frames per second.
• RAM(MB): Real-time memory footprint. (Note: To save CPU cycles, the OS memory is only queried once every 60 frames).
• ScriptTime(ms): How long your Lua on_tick and Reconciliation took to execute.
• LayoutTime(ms): How long the Yoga flexbox engine took to calculate positions.
• RenderTime(ms): How long it took to generate the OpenGL commands.
• TotalCPULoad(%): The percentage of your machine's logical cores actively used by the engine loop.