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.

How to set up

⚠

• 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.

1. Open Steam
2. Right click on Arma 3 in your Steam Library, then Properties
3. Select the tab betas
4. Finally, use the dropdown list to select the branch profiling - Performance Profiling Build
5. 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)

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

diag_captureFrame sample output

diag_captureFrame sample output

diag_captureFrame sample output

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.

⚠

The shorter a cycle/frame, the higher the fps.

ⓘ

Note: One second consists of one thousand milliseconds. 1 s = 1000 ms

FPS to frame duration table

FPS	seconds	milliseconds
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

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

• total is name for the scope of the duration for the whole frame (sLoop on a dedicated server).
• 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

1. Press ⇧ Shift + NUM -
2. Type frame
3. 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

1. Open the console (ESC key to open pause menu or ⇧ Shift + D in the)
2. Execute diag_captureFrame 1;
3. 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

1. Functions
2. On Activation by Triggers
3. Object init field

Slow Frame

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

1. Via Arma 3 Cheats

1. Press ⇧ Shift + NUM -
2. Type sframe
3. 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

1. Open the console (ESC key to open pause menu or ⇧ Shift + D in the)
2. Execute diag_captureSlowFrame ["total", 0.03];// [scope, duration]
3. 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

1. Functions
2. On Activation by Triggers
3. Object init field

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

1. Open the chat window by pressing the chat key (default /).
2. Type #captureFrame
3. 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

1. Open the console (ESC key to open pause menu)
2. Execute [1] remoteExec ["diag_captureFrame", 2];
3. 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

1. Functions
2. On Activation by Triggers
3. Object init field

Slow Server Frame

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

1. Via Admin chat commands

1. Open the chat window by pressing the chat key (default /).
2. Type #captureSlowFrame sLoop 0.03 0 1 - parameters scope, threshold, frameOffset, numberOfSlowFrames to capture
3. 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)
4. 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

1. Open the console (ESC key to open pause menu)
2. Execute [["sLoop", 0.03]] remoteExec ["diag_captureSlowFrame", 2]; // [scope, duration]
3. 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

1. Functions
2. On Activation by Triggers
3. Object init field

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

1. Press the Copy All button
2. Open an external text editor
3. Paste the text into a new text/log file
4. 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

1. 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:

1. CBA_A3: https://steamcommunity.com/workshop/filedetails/?id=450814997
2. Arma Script Profiler: https://steamcommunity.com/sharedfiles/filedetails/?id=1652506957
3. 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:

• https://tracy.nereid.pl
• https://github.com/wolfpld/tracy

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.

See Also

• Code Optimisation
• Mission Optimisation