Performance Profiling

Versions with performance profiling

The Profiling build is provided in semi regular intervals between major game version updates by Dedmen in tandem with Arma 3 Performance build.

The download and changelog can be found in the BI Forums as well as in the #perf_prof_branch channel in the official Arma 3 Discord server.

⚠

Through the nature of a Profiling build (due to additional "measuring"/profiling code), they are not as performant as the normal release builds!
Performance Profiling works also with the Diagnostics Exe.

Setup

⚠

To use the profiling build, you must launch the game with the arma3profiling_x64.exe (arma3serverprofiling_x64.exe for the server).
One way is to delete the arma3.exe, and rename the profiling exe to it. This way you can continue to use the Arma 3 launcher to launch the game with your startup parameters by selecting Platform: 32-bit under All Parameters (or other third party launcher applications).
The alternative is to use batch files (and copy your startup parameters from the top of a rpt log file from a regular session).

Sample batch file to auto rename the exe: replaceArma3exeWithProfiling.bat

cd /D "C:\Program Files (x86)\Steam\steamapps\common\Arma 3"

del arma3.exe

copy /Y /B arma3profiling_x64.exe arma3.exe

Steam Branch

AUTOMATIC (Recommended) - see also Steam Branches.

Open Steam
Right click on Arma 3 in your Steam Library, then Properties
Select the tab betas
Finally, use the dropdown list to select the branch profiling - Performance Profiling Build
Wait for the download to finish

This will automatically download newest performance and profiling exes once they are available.

Google Drive

MANUAL (only when needed)

Download and install 7z (usually the 64-bit Windows x64 variant)
Open BI forum thread
Got to latest post with a link to google drive
Browse to the latest game version and profiling build version folder
Download the desired exe from the google drive folder (usually the arma3client_x64_profiling_XXX.7z)
Extract the 7z file and copy the exe to your game folder (usually C:\Program Files (x86)\Steam\steamapps\common\Arma 3)

FPS conversion table
FPS	seconds	milliseconds
1000	0.001	1
500	0.002	2
333	0.003	3
250	0.004	4
200	0.005	5
100	0.010	10
60	0.017	17
50	0.020	20
40	0.025	25
30	0.033	33
20	0.050	50
10	0.100	100
5	0.200	200
4	0.250	250
3	0.333	333
2	0.500	500
1	1.0	1000

FPS Basics

The duration the engine needs to compute all calculations in one cycle is called a frame. The frame rate, or frames per second (FPS), in return states how many cycles the engine could compute for a given second.

ⓘ

One second consists of one thousand milliseconds (1 s = 1000 ms).
The shorter a cycle/frame, the higher the FPS.

⚠

total only works for a client (a machine with interface). Basically the equivalent for the dedicated server is sLoop and for a headless client it is cLoop.

Example:

diag_captureSlowFrame ["total", "50fps"]; diag_captureSlowFrame ["total", "0.02s"]; diag_captureSlowFrame ["total", "20ms"];

diag_captureSlowFrame ["total", "30fps"]; diag_captureSlowFrame ["total", "0.033s"]; diag_captureSlowFrame ["total", "33ms"];

Duration Parameter

The duration parameter is a time measured in seconds. 0.3 (seconds) is the same as 300 ms / milliseconds.
It is used to determine what duration of a frame you consider abnormal or that you are interested in for other reasons.
The first time such frame happens, the frame information will be captured - or put differently: when a situation occurs with a frame lasting longer than said duration.
0.3 (<3 fps for the whole frame) is definitely something you should not see in a normal game.
If you do not capture any frames with 0.3, try lowering it to 0.2 (200 ms / <5 fps) or 0.1 (100 ms / <10 fps).
If it triggers "too early" before the main slowdown happens that you want to analyze, increase it to a higher value, e.g. 1.0 for long freeze (<1 fps).

Scope Parameter

⚠

The scope parameter is case sensitive.

total is name for the scope of the duration for the whole frame (sLoop on a dedicated server, cLoop on a headless client).
With the total scope you capture more or less your frames per second (fps) - if your current frame-rate is essentially stable. In other words if all frames for that second have roughly similar duration.
In some situations you may encounter single/few frame lasting mini-freezes - aka one/few frames take rather long to complete (ie 100 ms), yet the rest remains in your normal fps range (20 ms for 50 fps for example).
Whereas a longer freeze means usually a frame last very long, like a second or longer. Thus the game stalls altogether for the given timeframe.
The scope parameter now allows you to capture subparts of a frame, of different parts of the engine computation - in general terms like networking, world and unit simulation, AI behavior, sound, rendering and visibility checks.
The total scope is also from the main thread and could be called main frame - all things the engine has to complete in a cycle. In addition there are other threads, where the engine moves other tasks to be computed alongside. Essentially this is what multi-threading is about, allowing the CPU with multiple cores to compute more things at the same time, and thus to reduce the duration of the main frame.
With the scope parameter you can capture said subparts from the "main frame", yet also from the so called "worker" threads.
The names for scopes/subscopes you can get from the diag capture dialog or in the frame capture logging files (.log/.trace).

How to Capture

Client

Current Frame

If you want to capture a snapshot of a current moment, there are a few options:

1. Via Arma 3 Cheats

Press ⇧ Shift + NUM -
Type frame
As result the diag capture dialog opens

⚠

This is a very rough way to capture the game is running while you are typing.
Outside multiplier, if you open the pause menu, the simulation for the mission is halted. So when you do a capture in that menu, you only get a capture for the menu simulation.
You can use the frame cheat at any point - ie in the main menu or submenus, in the editor, in multiplayer, etc.

2. Via Debug Console

Open the console (ESC key to open pause menu or ⇧ Shift + D in the)
Execute diag_captureFrame 1;
As result the diag capture dialog opens

⚠

This is a very rough way to capture the game is running while you are typing.
Outside multiplier, if you open the pause menu, the simulation for the mission is halted. So when you do a capture in that menu, you only get a capture for the menu simulation.
To avoid that, you need to delay the execution until the pause menu is closed again. For example by: (findDisplay 49) closeDisplay 0; diag_captureFrame 3;
To have the console available in a mission (outside the), you need to enable it via the Description.ext - enableDebugConsole parameter.
Alternatively you can enable the console in any missions via mods (see below).

Mods to enable console in any mission:

Enable Debug Console = 1 (Access - ADMIN) by Mr. Uplay
Enable Debug Console = 2 (Access - ALL) by Mr. Uplay
enableDebugConsole by Sams
Debug Console by R3vo

⚠

For dedicated server use, you need to allow the given mod by uploading the respective bikey to the server's keys folder - or disable verifySignatures = 0; via server.cfg.

Strongly recommended: Use an enhanced debug console like CBA_A3 or DevCon mod

3. Via custom action

You need to execute in the console the following code first to add the action:

if (!(isNil "temp_diag_captureFrame_action")) then { player removeAction temp_diag_captureFrame_action; temp_diag_captureFrame_action = nil; }; temp_diag_captureFrame_action = player addAction ["<t color='#FF0000'>captureFrame</t>", { diag_captureFrame 1; }];

To remove the action again:

if (!(isNil "temp_diag_captureFrame_action")) then { player removeAction temp_diag_captureFrame_action; temp_diag_captureFrame_action = nil; };

4. Via mission specific code

Slow Frame

⚠

The scope parameter is case sensitive.

If you want to capture a snapshot of a slow frame, there are a few options:

1. Via Arma 3 Cheats

Press ⇧ Shift + NUM -
Type sframe
Once the game falls below 30 fps (30 ms / 0.030 (s) duration for for total scope) the diag capture dialog opens

⚠

This is a very basic way to capture slow frames as the limit is not customizable and only works on the total scope. For customizable scope and duration use the options below.
Outside multiplier, if you open the pause menu, the simulation for the mission is halted. So when you do a capture in that menu, you only get a capture for the menu simulation.
You can use the sframe cheat at any point - ie in the main menu or submenus, in the editor, in multiplayer, etc.

2. Via Debug Console

Open the console (ESC key to open pause menu or ⇧ Shift + D in the)
Execute diag_captureSlowFrame ["total", 0.03];// [scope, duration]
As result the diag capture dialog opens

⚠

There can be only captureSlowFrame active at the same time. If another is set by the different means, the old one becomes inactive.
Outside multiplier, if you open the pause menu, the simulation for the mission is halted. So when capture triggers while you are still in that menu, you only get a capture for the menu simulation.
To avoid that, you need to delay the execution until the pause menu is closed again. For example by: (findDisplay 49) closeDisplay 0; diag_captureSlowFrame ["total", 0.03, 3];
To have the console available in a mission (outside the), you need to enable it via the description.ext enableDebugConsole parameter.
Alternatively you can enable the console in any missions via mods (see above).

3. Via custom action

You need to execute in the console the following code first to add the action:

if (!(isNil "temp_diag_captureSlowFrame_action")) then { player removeAction temp_diag_captureSlowFrame_action; temp_diag_captureSlowFrame_action = nil; }; temp_diag_captureSlowFrame_action = player addAction ["<t color='#FF0000'>captureSlowFrame</t>", { diag_captureSlowFrame ["total", 0.03]; }];

Customize the scope and duration as desired.

To remove the action again:

if (!(isNil "temp_diag_captureSlowFrame_action")) then { player removeAction temp_diag_captureSlowFrame_action; temp_diag_captureSlowFrame_action = nil; };

4. Via mission specific code

Server

Current Server Frame

If you want to capture a snapshot of a current moment on the server, there are a few options:

1. Via Admin chat commands

Open the chat window by pressing the chat key (default /).
Type #captureFrame
The current frame on the server is captured and written to a log file in the same directory as the .rpt file.

⚠

You must be logged in as admin!
This is a very rough way to capture the current frame on the server.
See diag_captureFrameToFile for more info.

2. Via Debug Console

Open the console (ESC key to open pause menu)
Execute [1] remoteExec ["diag_captureFrame", 2];
As result the diag capture dialog opens

⚠

This is a very rough way to capture the current frame on the server.
To have the console available in a mission, you need to enable it via the description.ext enableDebugConsole parameter.
Alternatively you can enable the console in any missions via mods (see below).

Mods to enable console in any mission:

Enable Debug Console = 1 (Access - ADMIN) by Mr. Uplay
Enable Debug Console = 2 (Access - ALL) by Mr. Uplay
enableDebugConsole by Sams
Debug Console by R3vo

⚠

For dedicated server use, you need to allow the given mod by uploading the respective bikey to the server's keys folder - or disable verifySignatures = 0; via server.cfg.

Strongly recommended: Use an enhanced debug console like CBA_A3 or DevCon mod

3. Via custom action

You need to execute in the console the following code first to add the action:

if (!(isNil "temp_diag_captureFrame_server_action")) then { player removeAction temp_diag_captureFrame_server_action; temp_diag_captureFrame_server_action = nil; }; temp_diag_captureFrame_server_action = player addAction ["<t color='#FF0000'>captureFrame (server)</t>", { [1] remoteExec ["diag_captureFrame", 2]; }];

To remove the action again:

if (!(isNil "temp_diag_captureFrame_server_action")) then { player removeAction temp_diag_captureFrame_server_action; temp_diag_captureFrame_server_action = nil; };

4. Via mission specific code

Slow Server Frame

⚠

The scope parameter is case sensitive.

If you want to capture a snapshot of a slow frame on the server, there are a few options:

1. Via Admin chat commands

Open the chat window by pressing the chat key (default /).
Type #captureSlowFrame sLoop 0.03 0 1 - parameters scope, threshold, frameOffset, numberOfSlowFrames to capture
Captures one frame on the server if it exceeds the set threshold in seconds for the given scope (30 ms / 0.030 (s) duration for for sLoop scope)
The frame information get written to a log file in the same directory as the .rpt file

⚠

You must be logged in as admin!
Customize the numberOfSlowFrames as you see fit.
There can be only captureSlowFrame active at the same time. If another is set by the different means, the old one becomes inactive.
See diag_captureSlowFrame for more info.

2. Via Debug Console

Open the console (ESC key to open pause menu)
Execute [["sLoop", 0.03]] remoteExec ["diag_captureSlowFrame", 2]; // [scope, duration]
As result the diag capture dialog opens

⚠

To have the console available in a mission, you need to enable it via the description.ext enableDebugConsole parameter.
Alternatively you can enable the console in any missions via mods (see above).

3. Via custom action

You need to execute in the console the following code first to add the action:

if (!(isNil "temp_diag_captureSlowFrame_server_action")) then { player removeAction temp_diag_captureSlowFrame_server_action; temp_diag_captureSlowFrame_server_action = nil; }; temp_diag_captureSlowFrame_server_action = player addAction ["<t color='#FF0000'>captureSlowFrame (server)</t>", { [["sLoop", 0.03]] remoteExec ["diag_captureSlowFrame", 2]; }];

Customize the scope and duration as desired.

To remove the action again:

if (!(isNil "temp_diag_captureSlowFrame_server_action")) then { player removeAction temp_diag_captureSlowFrame_server_action; temp_diag_captureSlowFrame_server_action = nil; };

4. Via mission specific code

Storing a capture to file

To export the gathered information of a capture for later analysis/review or to share it with others, you have the following options:

Diag capture dialog

Press the Copy All button
Open an external text editor
Paste the text into a new text/log file
Save the file (as .txt or .log)

ⓘ

Standard naming is: captureFrame-DATE_TIME.log - like captureFrame-17452-2024-11-21_18-12-37.211027.log

⚠

As alternative if you hold ⇧ Shift while pressing the Copy All button, it will instead use the .trace format used by third-party viewers like https://ui.perfetto.dev/#!/info

diag_captureSlowFrame

The sqf command diag_captureSlowFrame has the boolean toFile as forth parameter. In addition with the Number continuousCounter as fifth parameter you can make it log multiple captures in one go.

[section, threshold, frameSkip, toFile, continuousCounter]

Client: diag_captureSlowFrame ["total", 0.03, 0, true, 1];
Server: [["total", 0.03, 0, true, 1]] remoteExec ["diag_captureSlowFrame", 2];

Dedicated server

The Admin chat commands #captureFrame / #captureSlowFrame sLoop 0 will automatically create both .log and .trace format files on the server in the rpt log folder. See above server section for more information.

For customized server side logging use the remoteExec approach or console with remote/target execution.

How to View a Capture

TODO

Ingame

In the window you will be able to browse a lot of performance-related data, which can be interesting

TODO

Externally

Perfetto UI Web Viewer

Pros:

Can view a frame capture without Arma 3 running
Nice visualization
Sub scopes easier to identify

Cons:

Fairly slow to load/display a frame capture
Navigation via mouse and keyboard not super intuitive - see Support - Keyboard shortcuts in the left side menu
Does not support viewing multiple frame captures (only via multiple tabs)
.trace JSON export from Arma 3 doesnt support more advanced features of Perfetto UI nor contains information on CPU-RAM use

Website: https://ui.perfetto.dev

⚠

Only supports .trace format frame captures!

Tracy Live Viewer

Works only with the custom tracy version provided by Dedmen as part of the Arma Script Profiler mod.

ⓘ

Capturing live data needs a lot of RAM - up to 2 GB per minute (depends on detail level captured).

Pros:

Live frame capture
Multiple frame captures - see frame by frame
Statistics like number of executions, average and mean time execution
Selection of zones for specific analysis of any time frame
Profiling of unscheduled code. See: ArmaScriptProfiler

Cons:

Fairly advanced
Tracy UI more functional than visually nice

Required mods:

CBA_A3: https://steamcommunity.com/workshop/filedetails/?id=450814997
Arma Script Profiler: https://steamcommunity.com/sharedfiles/filedetails/?id=1652506957
Intercept Minimal Dev: https://steamcommunity.com/workshop/filedetails/?id=1645973522

Extra startup parameters: -profilerEnableEngine -profilerEngineThreads "-mod=!Workshop\@CBA_A3;!Workshop\@Arma Script Profiler;!Workshop\@Intercept Minimal Dev"

How to use: https://github.com/dedmen/ArmaScriptProfiler/wiki
Additional command line parameters: https://github.com/dedmen/ArmaScriptProfiler/wiki/Command-line-parameters
Some more info at: https://forums.bohemia.net/forums/topic/211626-arma-script-profiler/
Source: https://github.com/dedmen/ArmaScriptProfiler
Discord for tech support and such: https://discord.gg/vbFje5B

Advanced info:

Scripting Commands

diag_captureFrame
diag_captureSlowFrame
diag_logSlowFrame - not available in Arma 3. Since 2.20 diag_captureSlowFrame with toFile parameter can log to file as alternative.
diag_captureFrameToFile

diag_captureFrame sample output with custom subtree

Creating Your Own Subtree

When Profiling Per-Frame Eventhandlers (PFH), diag_captureFrame only shows one blob called siFEH that contains all PFH's so you can't see what part of that is caused by your PFH.
You can create your own subtree inside siFEH by wrapping your function call inside a isNil CODE statement like this:
Turn your old call which may look like this:

addMissionEventHandler ["EachFrame", { call myPFHFunction }];

Into something like this:

addMissionEventHandler ["EachFrame", { isNil { call myPFHFunction } // isNil creates the subtree }];

Now when you run diag_captureFrame inside of siPFH you will have a subtree called gsEva and behind that you can see the first line of code inside the isNil statement.
It will only show a part of the first line of that code so you should put something descriptive into the isNil statement.
You can use the same to create a subtree for any function you like. This will also work inside Scheduled (spawned) scripts.
But using this method to "subtree" a function with return values requires a little bit of trickery to get the return value out.

Performance Profiling

Contents

Versions with performance profiling