Profiling

nanos world includes built-in tools for profiling both the server and the game client in real-time. Using profiling tools is essential when optimizing large servers, identifying Lua bottlenecks, analyzing frame spikes, debugging networking issues, or improving overall performance.

Tracy Profiler

Tracy frame overview

nanos world includes built-in integration with the Tracy Profiler, allowing you to profile both the server and the game client in real-time.

Tracy is a real-time, nanosecond-resolution profiler widely used in game development and high-performance applications. It provides an interactive timeline view where you can inspect exactly what your application is doing during each frame.

Unlike traditional profilers, Tracy allows you to inspect performance live while the game or server is running. It provides a detailed timeline view of your application's execution, including:

• Lua calls
• Events callbacks
• Timer callbacks
• Internal systems
• Network processing
• Frame times
• Thread activity
• Lock contention
• Loading times

Tracy detailed view while hovering

Downloading Tracy

First, download the Tracy Profiler application from the official releases page. It must be version 0.14, the same version built into nanos world, otherwise it refuses to connect:

Download Tracy Profilerhttps://github.com/wolfpld/tracy/releases

After downloading, launch the Tracy application.

Connecting with Tracy

Tracy is built into every server and game client. It stays idle and records nothing until a profiler connects, and it only accepts connections from the same machine.

1. Start the server or the game normally
2. Open the Tracy Profiler application on the same machine
3. Enter 127.0.0.1 as the address
4. Click Connect

Tracy begins capturing from the moment it connects, so anything that happened before (like the startup) is not in the capture.

tip

If the server and the game run on the same machine, the first one to start uses port 8086 and the second one 8087. Connect to 127.0.0.1:8087 to reach the second one.

Profiling a Remote Server

As Tracy only accepts local connections, forward its port through SSH and connect to 127.0.0.1 on your own machine:

ssh -L 8086:127.0.0.1:8086 user@your-server

Profiling Your Scripts

Every Lua callback already shows up in Tracy with the file and line it comes from. To see what happens inside a callback, use the profiling functions of the Debug class, which work on both server and client:

Server.Subscribe("Tick", function(delta_time)
	-- Measures the function as a zone named "[my-package] NPC AI", also in the native profiling
	Debug.ProfileZone("NPC AI", function()
		UpdateNPCs(delta_time)
	end)

	-- Records a value in a graph
	Debug.ProfilePlot("NPCs Alive", #npcs)
end)

-- Marks an event in the timeline
Debug.ProfileMessage("Round Started")

The zone always closes when the function returns, even when it errors. Its function takes no parameters and returns nothing, so use a closure to reach your values. They cost almost nothing while Tracy is not connected and the native profiling is off, so they can stay in your code. Use Debug.IsProfilerConnected() to skip computing values that only feed a graph.

caution

Use fixed names for zones and graphs. Each different name stays stored until the game or server closes, so a name built per entity (like "NPC " .. id) fills the list quickly, and new names are ignored after 256.

Native Profiling

We also integrated a native profiling command that can be used to capture profiling data without using Tracy. It works by outputting the execution time of some pre-defined parts of the code to the server or client console (or the client's Profiling UI).

Server console outputting profiling information

Server Profiling

To enable server profiling, simply launch the server with the --profiling command or set profiling = true in the server's Config.toml file.

It will output PROFIL logs to the server console, showing the execution time of various systems and Lua callbacks.

Client Profiling

To enable client profiling, you must enable it in the Game Settings under the Debug tab:

Game Settings - Debug Tab

display frame times

By enabling it, it will show a Debug UI with:

• fps (frames per second - and the DLSS Frame Generation displayed fps under parenthesis)
• frametime (time taken to render each frame in milliseconds)
• fps 1% low (the average fps of the worst 1% frames)
• game (time the game thread spent)
• render (time the render thread spent)
• rhi (time the RHI thread spent)
• gpu (time the GPU spent)

Frametimes Debug UI

display profiling to screen

Enabling it, it will display the Profiling UI with all operations and their execution times directly on the game screen, allowing you to monitor performance in real-time without needing to check the console:

Profiling Debug UI

output profiling to console

Enabling it will output profiling information to the game console, exactly like the server side.

profiling entities & events network

Enabling it will display each entity network usage, along with scripting events and other syncing network usage on screen:

Entities Network Stats Debug UI