{"name":"Performance Profiling","title":"Performance Profiling","type":"topic","url":"https://community.bistudio.com/wiki/Performance_Profiling","revid":370411,"updated":"2024-12-05T17:53:05Z","aliases":[],"markdown":"### Versions with performance profiling\n\nThe **Profiling build** is provided in semi regular intervals between major game version updates by Dedmen in tandem with Arma 3 Performance build.\n\nThe download and changelog can be found in the [BI Forums](https://forums.bistudio.com/forums/topic/160288-arma-3-stable-server-170-performance-binary-feedback/) as well as in the `#perf_prof_branch` channel in the [official Arma 3 Discord server](https://discordapp.com/invite/arma).\n\n> [!IMPORTANT]\n> - Through the nature of a Profiling build (due to additional \"measuring\"/profiling code), they are not as performant as the normal release builds!\n> - Performance Profiling works also with the Diagnostics Exe.\n\n### Setup\n\n> [!IMPORTANT]\n> - To use the profiling build, you must launch the game with the **arma3profiling_x64.exe** (arma3serverprofiling_x64.exe for the server).\n> - 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).\n> - The alternative is to use [batch files](https://www.windowscentral.com/how-create-and-run-batch-file-windows-10) (and copy your startup parameters from the top of a rpt log file from a regular session).\n\nSample batch file to auto rename the exe: **replaceArma3exeWithProfiling.bat**\n\n```bat\ncd /D \"C:\\Program Files (x86)\\Steam\\steamapps\\common\\Arma 3\"\n\ndel arma3.exe\n\ncopy /Y /B arma3profiling_x64.exe arma3.exe\n```\n\n#### Steam Branch\n\nAUTOMATIC (Recommended) - see also Steam Branches.\n\n1. Open Steam\n1. Right click on **Arma 3** in your Steam Library, then **Properties**\n1. Select the tab **betas**\n1. Finally, use the dropdown list to select the branch **profiling - Performance Profiling Build**\n1. Wait for the download to finish\n\nThis will automatically download newest performance and profiling exes once they are available.\n\n#### Google Drive\n\nMANUAL (only when needed)\n\n1. Download and install [7z](https://www.7-zip.org/download.html) (usually the 64-bit Windows x64 variant)\n1. Open [BI forum thread](https://forums.bistudio.com/forums/topic/160288-arma-3-stable-server-170-performance-binary-feedback/)\n1. Got to latest post with a link to google drive\n1. Browse to the latest game version and profiling build version folder\n1. Download the desired exe from the google drive folder (usually the arma3client_x64_profiling_XXX.7z)\n1. Extract the 7z file and copy the exe to your game folder (usually `C:\\Program Files (x86)\\Steam\\steamapps\\common\\Arma 3`)\n\n**FPS conversion table**\n\n| FPS | seconds | milliseconds |\n|---|---|---|\n| 1000 | 0.001 | 1 |\n| 500 | 0.002 | 2 |\n| 333 | 0.003 | 3 |\n| 250 | 0.004 | 4 |\n| 200 | 0.005 | 5 |\n| 100 | 0.010 | 10 |\n| 60 | 0.017 | 17 |\n| 50 | 0.020 | 20 |\n| 40 | 0.025 | 25 |\n| 30 | 0.033 | 33 |\n| 20 | 0.050 | 50 |\n| 10 | 0.100 | 100 |\n| 5 | 0.200 | 200 |\n| 4 | 0.250 | 250 |\n| 3 | 0.333 | 333 |\n| 2 | 0.500 | 500 |\n| 1 | 1.0 | 1000 |\n\n### FPS Basics\n\nThe 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.\n\n> [!NOTE]\n> - One second consists of one thousand [milliseconds](https://en.wikipedia.org/wiki/Millisecond) (1 s = 1000 ms).\n> - The shorter a cycle/frame, the higher the FPS.\n\n> [!IMPORTANT]\n> **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**.\n\nExample:\n\n| | |\n|---|---|\n| ```sqf
diag_captureSlowFrame [\"total\", \"50fps\"];
diag_captureSlowFrame [\"total\", \"0.02s\"];
diag_captureSlowFrame [\"total\", \"20ms\"];
``` | ```sqf
diag_captureSlowFrame [\"total\", \"30fps\"];
diag_captureSlowFrame [\"total\", \"0.033s\"];
diag_captureSlowFrame [\"total\", \"33ms\"];
``` |\n\n### Duration Parameter\n\n- The duration parameter is a time measured in seconds. 0.3 (seconds) is the same as 300 ms / milliseconds.\n- It is used to determine what duration of a frame you consider abnormal or that you are interested in for other reasons.\n- 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.\n- 0.3 (<3 fps for the whole frame) is definitely something you should not see in a normal game.\n- 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).\n- 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).\n\n### Scope Parameter\n\n> [!IMPORTANT]\n> The **scope** parameter is [case sensitive](https://en.wikipedia.org/wiki/Case_sensitivity).\n\n- **total** is name for the scope of the duration for the whole frame (**sLoop** on a dedicated server, **cLoop** on a headless client).\n- 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.\n- 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).\n- 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.\n- 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.\n- 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.\n- With the scope parameter you can capture said subparts from the \"main frame\", yet also from the so called \"worker\" threads.\n- The names for scopes/subscopes you can get from the diag capture dialog or in the frame capture logging files (.log/.trace).\n\n### How to Capture\n\n#### Client\n\n##### Current Frame\n\nIf you want to capture a snapshot of a current moment, there are a few options:\n\n1. Via Arma 3 Cheats\n\n1. Press ⇧ Shift + NUM -\n1. Type `frame`\n1. As result the **diag capture dialog** opens\n\n> [!IMPORTANT]\n> - This is a very rough way to capture the game is running while you are typing.\n> - 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.\n> - You can use the *frame* cheat at any point - ie in the main menu or submenus, in the editor, in multiplayer, etc.\n\n2. Via Debug Console\n\n1. Open the console (ESC key to open pause menu or ⇧ Shift + D in the)\n1. Execute `diag_captureFrame 1;`\n1. As result the **diag capture dialog** opens\n\n> [!IMPORTANT]\n> - This is a very rough way to capture the game is running while you are typing.\n> - 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.\n> - 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;`\n> - To have the console available in a mission (outside the), you need to enable it via the Description.ext - enableDebugConsole parameter.\n> - Alternatively you can enable the console in any missions via mods (see below).\n\nMods to enable console in any mission:\n\n- [Enable Debug Console = 1 (Access - ADMIN)](https://steamcommunity.com/sharedfiles/filedetails/2000114984) by Mr. Uplay\n- [Enable Debug Console = 2 (Access - ALL)](https://steamcommunity.com/sharedfiles/filedetails/2000131738) by Mr. Uplay\n- [enableDebugConsole](https://steamcommunity.com/sharedfiles/filedetails/1939811222) by Sams\n- [Debug Console](https://steamcommunity.com/sharedfiles/filedetails/1231625987) by R3vo\n\n> [!IMPORTANT]\n> 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.\n\n**Strongly recommended**: Use an enhanced debug console like [CBA_A3](https://steamcommunity.com/sharedfiles/filedetails/450814997) or [DevCon](https://steamcommunity.com/sharedfiles/filedetails/281032552) mod\n\n3. Via custom action\n\nYou need to execute in the console the following code first to add the action:\n\n```sqf\nif (!(isNil \"temp_diag_captureFrame_action\")) then\n{\n player removeAction temp_diag_captureFrame_action;\n temp_diag_captureFrame_action = nil;\n};\n\ntemp_diag_captureFrame_action = player addAction [\"captureFrame\", { diag_captureFrame 1; }];\n```\n\nTo remove the action again:\n\n```sqf\nif (!(isNil \"temp_diag_captureFrame_action\")) then\n{\n player removeAction temp_diag_captureFrame_action;\n temp_diag_captureFrame_action = nil;\n};\n```\n\n4. Via mission specific code\n\n1. Functions\n1. On Activation by Triggers\n1. Object init field\n\n##### Slow Frame\n\n> [!IMPORTANT]\n> The **scope** parameter is [case sensitive](https://en.wikipedia.org/wiki/Case_sensitivity).\n\nIf you want to capture a snapshot of a slow frame, there are a few options:\n\n1. Via Arma 3 Cheats\n\n1. Press ⇧ Shift + NUM -\n1. Type `sframe`\n1. Once the game falls below 30 fps (30 ms / 0.030 (s) duration for for **total** scope) the diag capture dialog opens\n\n> [!IMPORTANT]\n> - 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.\n> - 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.\n> - You can use the *sframe* cheat at any point - ie in the main menu or submenus, in the editor, in multiplayer, etc.\n\n2. Via Debug Console\n\n1. Open the console (ESC key to open pause menu or ⇧ Shift + D in the)\n1. Execute `diag_captureSlowFrame [\"total\", 0.03];// [scope, duration]`\n1. As result the **diag capture dialog** opens\n\n> [!IMPORTANT]\n> - There can be only captureSlowFrame active at the same time. If another is set by the different means, the old one becomes inactive.\n> - 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.\n> - 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];`\n> - To have the console available in a mission (outside the), you need to enable it via the description.ext enableDebugConsole parameter.\n> - Alternatively you can enable the console in any missions via mods (see above).\n\n3. Via custom action\n\nYou need to execute in the console the following code first to add the action:\n\n```sqf\nif (!(isNil \"temp_diag_captureSlowFrame_action\")) then\n{\n player removeAction temp_diag_captureSlowFrame_action;\n temp_diag_captureSlowFrame_action = nil;\n};\n\ntemp_diag_captureSlowFrame_action = player addAction [\"captureSlowFrame\", { diag_captureSlowFrame [\"total\", 0.03]; }];\n```\n\nCustomize the scope and duration as desired.\n\nTo remove the action again:\n\n```sqf\nif (!(isNil \"temp_diag_captureSlowFrame_action\")) then\n{\n player removeAction temp_diag_captureSlowFrame_action;\n temp_diag_captureSlowFrame_action = nil;\n};\n```\n\n4. Via mission specific code\n\n1. Functions\n1. On Activation by Triggers\n1. Object init field\n\n#### Server\n\n##### Current Server Frame\n\nIf you want to capture a snapshot of a current moment on the server, there are a few options:\n\n1. Via Admin chat commands\n\n1. Open the chat window **by pressing the chat key** (default /).\n1. Type `#captureFrame`\n1. The current frame **on the server** is captured and written to a log file in the same directory as the .rpt file.\n\n> [!IMPORTANT]\n> - You must be logged in as admin!\n> - This is a very rough way to capture the current frame on the server.\n> - See diag_captureFrameToFile for more info.\n\n2. Via Debug Console\n\n1. Open the console (ESC key to open pause menu)\n1. Execute `[1] remoteExec [\"diag_captureFrame\", 2];`\n1. As result the **diag capture dialog** opens\n\n> [!IMPORTANT]\n> - This is a very rough way to capture the current frame on the server.\n> - To have the console available in a mission, you need to enable it via the description.ext enableDebugConsole parameter.\n> - Alternatively you can enable the console in any missions via mods (see below).\n\nMods to enable console in any mission:\n\n- [Enable Debug Console = 1 (Access - ADMIN)](https://steamcommunity.com/sharedfiles/filedetails/2000114984) by Mr. Uplay\n- [Enable Debug Console = 2 (Access - ALL)](https://steamcommunity.com/sharedfiles/filedetails/2000131738) by Mr. Uplay\n- [enableDebugConsole](https://steamcommunity.com/sharedfiles/filedetails/1939811222) by Sams\n- [Debug Console](https://steamcommunity.com/sharedfiles/filedetails/1231625987) by R3vo\n\n> [!IMPORTANT]\n> 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.\n\n**Strongly recommended**: Use an enhanced debug console like [CBA_A3](https://steamcommunity.com/sharedfiles/filedetails/?id=450814997) or [DevCon](https://steamcommunity.com/sharedfiles/filedetails/?id=281032552) mod\n\n3. Via custom action\n\nYou need to execute in the console the following code first to add the action:\n\n```sqf\nif (!(isNil \"temp_diag_captureFrame_server_action\")) then\n{\n player removeAction temp_diag_captureFrame_server_action;\n temp_diag_captureFrame_server_action = nil;\n};\n\ntemp_diag_captureFrame_server_action = player addAction [\"captureFrame (server)\", { [1] remoteExec [\"diag_captureFrame\", 2]; }];\n```\n\nTo remove the action again:\n\n```sqf\nif (!(isNil \"temp_diag_captureFrame_server_action\")) then\n{\n player removeAction temp_diag_captureFrame_server_action;\n temp_diag_captureFrame_server_action = nil;\n};\n```\n\n4. Via mission specific code\n\n1. Functions\n1. On Activation by Triggers\n1. Object init field\n\n##### Slow Server Frame\n\n> [!IMPORTANT]\n> The **scope** parameter is [case sensitive](https://en.wikipedia.org/wiki/Case_sensitivity).\n\nIf you want to capture a snapshot of a slow frame on the server, there are a few options:\n\n1. Via Admin chat commands\n\n1. Open the chat window **by pressing the chat key** (default /).\n1. Type `#captureSlowFrame sLoop 0.03 0 1` - parameters *scope, threshold, frameOffset, numberOfSlowFrames to capture*\n1. 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)\n1. The frame information get written to a log file in the same directory as the .rpt file\n\n> [!IMPORTANT]\n> - You must be logged in as admin!\n> - Customize the numberOfSlowFrames as you see fit.\n> - There can be only captureSlowFrame active at the same time. If another is set by the different means, the old one becomes inactive.\n> - See diag_captureSlowFrame for more info.\n\n2. Via Debug Console\n\n1. Open the console (ESC key to open pause menu)\n1. Execute `[[\"sLoop\", 0.03]] remoteExec [\"diag_captureSlowFrame\", 2]; // [scope, duration]`\n1. As result the **diag capture dialog** opens\n\n> [!IMPORTANT]\n> - To have the console available in a mission, you need to enable it via the description.ext enableDebugConsole parameter.\n> - Alternatively you can enable the console in any missions via mods (see above).\n\n3. Via custom action\n\nYou need to execute in the console the following code first to add the action:\n\n```sqf\nif (!(isNil \"temp_diag_captureSlowFrame_server_action\")) then\n{\n player removeAction temp_diag_captureSlowFrame_server_action;\n temp_diag_captureSlowFrame_server_action = nil;\n};\n\ntemp_diag_captureSlowFrame_server_action = player addAction [\"captureSlowFrame (server)\", { [[\"sLoop\", 0.03]] remoteExec [\"diag_captureSlowFrame\", 2]; }];\n```\n\nCustomize the scope and duration as desired.\n\nTo remove the action again:\n\n```sqf\nif (!(isNil \"temp_diag_captureSlowFrame_server_action\")) then\n{\n player removeAction temp_diag_captureSlowFrame_server_action;\n temp_diag_captureSlowFrame_server_action = nil;\n};\n```\n\n4. Via mission specific code\n\n1. Functions\n1. On Activation by Triggers\n1. Object init field\n\n### Storing a capture to file\n\nTo export the gathered information of a capture for later analysis/review or to share it with others, you have the following options:\n\n#### Diag capture dialog\n\n1. Press the **Copy All** button\n1. Open an external text editor\n1. Paste the text into a new text/log file\n1. Save the file (as .txt or .log)\n\n> [!NOTE]\n> Standard naming is: **captureFrame-DATE_TIME.log** - like `captureFrame-17452-2024-11-21_18-12-37.211027.log`\n\n> [!IMPORTANT]\n> 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\n\n#### diag_captureSlowFrame\n\nThe 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.\n\n```cpp\n[section, threshold, frameSkip, toFile, continuousCounter]\n```\n\n- Client: `diag_captureSlowFrame [\"total\", 0.03, 0, true, 1];`\n- Server: `[[\"total\", 0.03, 0, true, 1]] remoteExec [\"diag_captureSlowFrame\", 2];`\n\n#### Dedicated server\n\nThe 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.\n\nFor customized server side logging use the **remoteExec approach** or **console with remote/target execution**.\n\n### How to View a Capture\n\nTODO\n\n#### Ingame\n\n1. In the window you will be able to browse a lot of performance-related data, which can be interesting\n\nTODO\n\n#### Externally\n\n##### Perfetto UI Web Viewer\n\nPros:\n\n- Can view a frame capture without Arma 3 running\n- Nice visualization\n- Sub scopes easier to identify\n\nCons:\n\n- Fairly slow to load/display a frame capture\n- Navigation via mouse and keyboard not super intuitive - see **Support - Keyboard shortcuts** in the left side menu\n- Does not support viewing multiple frame captures (only via multiple tabs)\n- .trace JSON export from Arma 3 doesnt support more advanced features of Perfetto UI nor contains information on CPU-RAM use\n\nWebsite: https://ui.perfetto.dev\n\n> [!IMPORTANT]\n> Only supports `.trace` format frame captures!\n\n##### Tracy Live Viewer\n\nWorks only with the custom tracy version provided by Dedmen as part of the [Arma Script Profiler](https://steamcommunity.com/sharedfiles/filedetails/1652506957) mod.\n\n> [!NOTE]\n> Capturing live data needs a lot of RAM - up to 2 GB per minute (depends on detail level captured).\n\nPros:\n\n- Live frame capture\n- Multiple frame captures - see frame by frame\n- Statistics like number of executions, average and mean time execution\n- Selection of *zones* for specific analysis of any time frame\n- Profiling of unscheduled code. See: ArmaScriptProfiler\n\nCons:\n\n- Fairly advanced\n- Tracy UI more functional than visually nice\n\nRequired mods:\n\n1. CBA_A3: https://steamcommunity.com/workshop/filedetails/?id=450814997\n1. Arma Script Profiler: https://steamcommunity.com/sharedfiles/filedetails/?id=1652506957\n1. Intercept Minimal Dev: https://steamcommunity.com/workshop/filedetails/?id=1645973522\n\nExtra startup parameters: -profilerEnableEngine -profilerEngineThreads \"-mod=!Workshop\\@CBA_A3;!Workshop\\@Arma Script Profiler;!Workshop\\@Intercept Minimal Dev\"\n\n- How to use: https://github.com/dedmen/ArmaScriptProfiler/wiki\n- Additional command line parameters: https://github.com/dedmen/ArmaScriptProfiler/wiki/Command-line-parameters\n- Some more info at: https://forums.bohemia.net/forums/topic/211626-arma-script-profiler/\n- Source: https://github.com/dedmen/ArmaScriptProfiler\n- Discord for tech support and such: https://discord.gg/vbFje5B\n\nAdvanced info:\n\n- https://tracy.nereid.pl\n- https://github.com/wolfpld/tracy\n\n### Scripting Commands\n\n- diag_captureFrame\n- diag_captureSlowFrame\n- diag_logSlowFrame - not available in Arma 3. Since Arma 3 v2.20 diag_captureSlowFrame with **toFile** parameter can log to file as alternative.\n- diag_captureFrameToFile\n\n### Creating Your Own Subtree\n\nWhen 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.\nYou can create your own subtree inside siFEH by wrapping your function call inside a isNil CODE statement like this:\nTurn your old call which may look like this:\n\n```sqf\naddMissionEventHandler [\"EachFrame\", {\n call myPFHFunction\n}];\n```\n\nInto something like this:\n\n```sqf\naddMissionEventHandler [\"EachFrame\", {\n isNil { call myPFHFunction } // isNil creates the subtree\n}];\n```\n\nNow 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.\nIt will only show a part of the first line of that code so you should put something descriptive into the isNil statement.\nYou can use the same to create a subtree for any function you like. This will also work inside Scheduled (spawned) scripts.\nBut using this method to \"subtree\" a function with return values requires a little bit of trickery to get the return value out.\n\n### See Also\n\n- Code Optimisation\n- Mission Optimisation","sections":[{"heading":"Versions with performance profiling","level":3,"markdown":"The **Profiling build** is provided in semi regular intervals between major game version updates by Dedmen in tandem with Arma 3 Performance build.\n\nThe download and changelog can be found in the [BI Forums](https://forums.bistudio.com/forums/topic/160288-arma-3-stable-server-170-performance-binary-feedback/) as well as in the `#perf_prof_branch` channel in the [official Arma 3 Discord server](https://discordapp.com/invite/arma).\n\n> [!IMPORTANT]\n> - Through the nature of a Profiling build (due to additional \"measuring\"/profiling code), they are not as performant as the normal release builds!\n> - Performance Profiling works also with the Diagnostics Exe."},{"heading":"Setup","level":3,"markdown":"> [!IMPORTANT]\n> - To use the profiling build, you must launch the game with the **arma3profiling_x64.exe** (arma3serverprofiling_x64.exe for the server).\n> - 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).\n> - The alternative is to use [batch files](https://www.windowscentral.com/how-create-and-run-batch-file-windows-10) (and copy your startup parameters from the top of a rpt log file from a regular session).\n\nSample batch file to auto rename the exe: **replaceArma3exeWithProfiling.bat**\n\n```bat\ncd /D \"C:\\Program Files (x86)\\Steam\\steamapps\\common\\Arma 3\"\n\ndel arma3.exe\n\ncopy /Y /B arma3profiling_x64.exe arma3.exe\n```"},{"heading":"Steam Branch","level":4,"markdown":"AUTOMATIC (Recommended) - see also Steam Branches.\n\n1. Open Steam\n1. Right click on **Arma 3** in your Steam Library, then **Properties**\n1. Select the tab **betas**\n1. Finally, use the dropdown list to select the branch **profiling - Performance Profiling Build**\n1. Wait for the download to finish\n\nThis will automatically download newest performance and profiling exes once they are available."},{"heading":"Google Drive","level":4,"markdown":"MANUAL (only when needed)\n\n1. Download and install [7z](https://www.7-zip.org/download.html) (usually the 64-bit Windows x64 variant)\n1. Open [BI forum thread](https://forums.bistudio.com/forums/topic/160288-arma-3-stable-server-170-performance-binary-feedback/)\n1. Got to latest post with a link to google drive\n1. Browse to the latest game version and profiling build version folder\n1. Download the desired exe from the google drive folder (usually the arma3client_x64_profiling_XXX.7z)\n1. Extract the 7z file and copy the exe to your game folder (usually `C:\\Program Files (x86)\\Steam\\steamapps\\common\\Arma 3`)\n\n**FPS conversion table**\n\n| FPS | seconds | milliseconds |\n|---|---|---|\n| 1000 | 0.001 | 1 |\n| 500 | 0.002 | 2 |\n| 333 | 0.003 | 3 |\n| 250 | 0.004 | 4 |\n| 200 | 0.005 | 5 |\n| 100 | 0.010 | 10 |\n| 60 | 0.017 | 17 |\n| 50 | 0.020 | 20 |\n| 40 | 0.025 | 25 |\n| 30 | 0.033 | 33 |\n| 20 | 0.050 | 50 |\n| 10 | 0.100 | 100 |\n| 5 | 0.200 | 200 |\n| 4 | 0.250 | 250 |\n| 3 | 0.333 | 333 |\n| 2 | 0.500 | 500 |\n| 1 | 1.0 | 1000 |"},{"heading":"FPS Basics","level":3,"markdown":"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.\n\n> [!NOTE]\n> - One second consists of one thousand [milliseconds](https://en.wikipedia.org/wiki/Millisecond) (1 s = 1000 ms).\n> - The shorter a cycle/frame, the higher the FPS.\n\n> [!IMPORTANT]\n> **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**.\n\nExample:\n\n| | |\n|---|---|\n| ```sqf
diag_captureSlowFrame [\"total\", \"50fps\"];
diag_captureSlowFrame [\"total\", \"0.02s\"];
diag_captureSlowFrame [\"total\", \"20ms\"];
``` | ```sqf
diag_captureSlowFrame [\"total\", \"30fps\"];
diag_captureSlowFrame [\"total\", \"0.033s\"];
diag_captureSlowFrame [\"total\", \"33ms\"];
``` |"},{"heading":"Duration Parameter","level":3,"markdown":"- The duration parameter is a time measured in seconds. 0.3 (seconds) is the same as 300 ms / milliseconds.\n- It is used to determine what duration of a frame you consider abnormal or that you are interested in for other reasons.\n- 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.\n- 0.3 (<3 fps for the whole frame) is definitely something you should not see in a normal game.\n- 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).\n- 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)."},{"heading":"Scope Parameter","level":3,"markdown":"> [!IMPORTANT]\n> The **scope** parameter is [case sensitive](https://en.wikipedia.org/wiki/Case_sensitivity).\n\n- **total** is name for the scope of the duration for the whole frame (**sLoop** on a dedicated server, **cLoop** on a headless client).\n- 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.\n- 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).\n- 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.\n- 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.\n- 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.\n- With the scope parameter you can capture said subparts from the \"main frame\", yet also from the so called \"worker\" threads.\n- The names for scopes/subscopes you can get from the diag capture dialog or in the frame capture logging files (.log/.trace)."},{"heading":"How to Capture","level":3,"markdown":""},{"heading":"Client","level":4,"markdown":""},{"heading":"Current Frame","level":5,"markdown":"If you want to capture a snapshot of a current moment, there are a few options:\n\n1. Via Arma 3 Cheats\n\n1. Press ⇧ Shift + NUM -\n1. Type `frame`\n1. As result the **diag capture dialog** opens\n\n> [!IMPORTANT]\n> - This is a very rough way to capture the game is running while you are typing.\n> - 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.\n> - You can use the *frame* cheat at any point - ie in the main menu or submenus, in the editor, in multiplayer, etc.\n\n2. Via Debug Console\n\n1. Open the console (ESC key to open pause menu or ⇧ Shift + D in the)\n1. Execute `diag_captureFrame 1;`\n1. As result the **diag capture dialog** opens\n\n> [!IMPORTANT]\n> - This is a very rough way to capture the game is running while you are typing.\n> - 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.\n> - 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;`\n> - To have the console available in a mission (outside the), you need to enable it via the Description.ext - enableDebugConsole parameter.\n> - Alternatively you can enable the console in any missions via mods (see below).\n\nMods to enable console in any mission:\n\n- [Enable Debug Console = 1 (Access - ADMIN)](https://steamcommunity.com/sharedfiles/filedetails/2000114984) by Mr. Uplay\n- [Enable Debug Console = 2 (Access - ALL)](https://steamcommunity.com/sharedfiles/filedetails/2000131738) by Mr. Uplay\n- [enableDebugConsole](https://steamcommunity.com/sharedfiles/filedetails/1939811222) by Sams\n- [Debug Console](https://steamcommunity.com/sharedfiles/filedetails/1231625987) by R3vo\n\n> [!IMPORTANT]\n> 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.\n\n**Strongly recommended**: Use an enhanced debug console like [CBA_A3](https://steamcommunity.com/sharedfiles/filedetails/450814997) or [DevCon](https://steamcommunity.com/sharedfiles/filedetails/281032552) mod\n\n3. Via custom action\n\nYou need to execute in the console the following code first to add the action:\n\n```sqf\nif (!(isNil \"temp_diag_captureFrame_action\")) then\n{\n player removeAction temp_diag_captureFrame_action;\n temp_diag_captureFrame_action = nil;\n};\n\ntemp_diag_captureFrame_action = player addAction [\"captureFrame\", { diag_captureFrame 1; }];\n```\n\nTo remove the action again:\n\n```sqf\nif (!(isNil \"temp_diag_captureFrame_action\")) then\n{\n player removeAction temp_diag_captureFrame_action;\n temp_diag_captureFrame_action = nil;\n};\n```\n\n4. Via mission specific code\n\n1. Functions\n1. On Activation by Triggers\n1. Object init field"},{"heading":"Slow Frame","level":5,"markdown":"> [!IMPORTANT]\n> The **scope** parameter is [case sensitive](https://en.wikipedia.org/wiki/Case_sensitivity).\n\nIf you want to capture a snapshot of a slow frame, there are a few options:\n\n1. Via Arma 3 Cheats\n\n1. Press ⇧ Shift + NUM -\n1. Type `sframe`\n1. Once the game falls below 30 fps (30 ms / 0.030 (s) duration for for **total** scope) the diag capture dialog opens\n\n> [!IMPORTANT]\n> - 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.\n> - 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.\n> - You can use the *sframe* cheat at any point - ie in the main menu or submenus, in the editor, in multiplayer, etc.\n\n2. Via Debug Console\n\n1. Open the console (ESC key to open pause menu or ⇧ Shift + D in the)\n1. Execute `diag_captureSlowFrame [\"total\", 0.03];// [scope, duration]`\n1. As result the **diag capture dialog** opens\n\n> [!IMPORTANT]\n> - There can be only captureSlowFrame active at the same time. If another is set by the different means, the old one becomes inactive.\n> - 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.\n> - 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];`\n> - To have the console available in a mission (outside the), you need to enable it via the description.ext enableDebugConsole parameter.\n> - Alternatively you can enable the console in any missions via mods (see above).\n\n3. Via custom action\n\nYou need to execute in the console the following code first to add the action:\n\n```sqf\nif (!(isNil \"temp_diag_captureSlowFrame_action\")) then\n{\n player removeAction temp_diag_captureSlowFrame_action;\n temp_diag_captureSlowFrame_action = nil;\n};\n\ntemp_diag_captureSlowFrame_action = player addAction [\"captureSlowFrame\", { diag_captureSlowFrame [\"total\", 0.03]; }];\n```\n\nCustomize the scope and duration as desired.\n\nTo remove the action again:\n\n```sqf\nif (!(isNil \"temp_diag_captureSlowFrame_action\")) then\n{\n player removeAction temp_diag_captureSlowFrame_action;\n temp_diag_captureSlowFrame_action = nil;\n};\n```\n\n4. Via mission specific code\n\n1. Functions\n1. On Activation by Triggers\n1. Object init field"},{"heading":"Server","level":4,"markdown":""},{"heading":"Current Server Frame","level":5,"markdown":"If you want to capture a snapshot of a current moment on the server, there are a few options:\n\n1. Via Admin chat commands\n\n1. Open the chat window **by pressing the chat key** (default /).\n1. Type `#captureFrame`\n1. The current frame **on the server** is captured and written to a log file in the same directory as the .rpt file.\n\n> [!IMPORTANT]\n> - You must be logged in as admin!\n> - This is a very rough way to capture the current frame on the server.\n> - See diag_captureFrameToFile for more info.\n\n2. Via Debug Console\n\n1. Open the console (ESC key to open pause menu)\n1. Execute `[1] remoteExec [\"diag_captureFrame\", 2];`\n1. As result the **diag capture dialog** opens\n\n> [!IMPORTANT]\n> - This is a very rough way to capture the current frame on the server.\n> - To have the console available in a mission, you need to enable it via the description.ext enableDebugConsole parameter.\n> - Alternatively you can enable the console in any missions via mods (see below).\n\nMods to enable console in any mission:\n\n- [Enable Debug Console = 1 (Access - ADMIN)](https://steamcommunity.com/sharedfiles/filedetails/2000114984) by Mr. Uplay\n- [Enable Debug Console = 2 (Access - ALL)](https://steamcommunity.com/sharedfiles/filedetails/2000131738) by Mr. Uplay\n- [enableDebugConsole](https://steamcommunity.com/sharedfiles/filedetails/1939811222) by Sams\n- [Debug Console](https://steamcommunity.com/sharedfiles/filedetails/1231625987) by R3vo\n\n> [!IMPORTANT]\n> 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.\n\n**Strongly recommended**: Use an enhanced debug console like [CBA_A3](https://steamcommunity.com/sharedfiles/filedetails/?id=450814997) or [DevCon](https://steamcommunity.com/sharedfiles/filedetails/?id=281032552) mod\n\n3. Via custom action\n\nYou need to execute in the console the following code first to add the action:\n\n```sqf\nif (!(isNil \"temp_diag_captureFrame_server_action\")) then\n{\n player removeAction temp_diag_captureFrame_server_action;\n temp_diag_captureFrame_server_action = nil;\n};\n\ntemp_diag_captureFrame_server_action = player addAction [\"captureFrame (server)\", { [1] remoteExec [\"diag_captureFrame\", 2]; }];\n```\n\nTo remove the action again:\n\n```sqf\nif (!(isNil \"temp_diag_captureFrame_server_action\")) then\n{\n player removeAction temp_diag_captureFrame_server_action;\n temp_diag_captureFrame_server_action = nil;\n};\n```\n\n4. Via mission specific code\n\n1. Functions\n1. On Activation by Triggers\n1. Object init field"},{"heading":"Slow Server Frame","level":5,"markdown":"> [!IMPORTANT]\n> The **scope** parameter is [case sensitive](https://en.wikipedia.org/wiki/Case_sensitivity).\n\nIf you want to capture a snapshot of a slow frame on the server, there are a few options:\n\n1. Via Admin chat commands\n\n1. Open the chat window **by pressing the chat key** (default /).\n1. Type `#captureSlowFrame sLoop 0.03 0 1` - parameters *scope, threshold, frameOffset, numberOfSlowFrames to capture*\n1. 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)\n1. The frame information get written to a log file in the same directory as the .rpt file\n\n> [!IMPORTANT]\n> - You must be logged in as admin!\n> - Customize the numberOfSlowFrames as you see fit.\n> - There can be only captureSlowFrame active at the same time. If another is set by the different means, the old one becomes inactive.\n> - See diag_captureSlowFrame for more info.\n\n2. Via Debug Console\n\n1. Open the console (ESC key to open pause menu)\n1. Execute `[[\"sLoop\", 0.03]] remoteExec [\"diag_captureSlowFrame\", 2]; // [scope, duration]`\n1. As result the **diag capture dialog** opens\n\n> [!IMPORTANT]\n> - To have the console available in a mission, you need to enable it via the description.ext enableDebugConsole parameter.\n> - Alternatively you can enable the console in any missions via mods (see above).\n\n3. Via custom action\n\nYou need to execute in the console the following code first to add the action:\n\n```sqf\nif (!(isNil \"temp_diag_captureSlowFrame_server_action\")) then\n{\n player removeAction temp_diag_captureSlowFrame_server_action;\n temp_diag_captureSlowFrame_server_action = nil;\n};\n\ntemp_diag_captureSlowFrame_server_action = player addAction [\"captureSlowFrame (server)\", { [[\"sLoop\", 0.03]] remoteExec [\"diag_captureSlowFrame\", 2]; }];\n```\n\nCustomize the scope and duration as desired.\n\nTo remove the action again:\n\n```sqf\nif (!(isNil \"temp_diag_captureSlowFrame_server_action\")) then\n{\n player removeAction temp_diag_captureSlowFrame_server_action;\n temp_diag_captureSlowFrame_server_action = nil;\n};\n```\n\n4. Via mission specific code\n\n1. Functions\n1. On Activation by Triggers\n1. Object init field"},{"heading":"Storing a capture to file","level":3,"markdown":"To export the gathered information of a capture for later analysis/review or to share it with others, you have the following options:"},{"heading":"Diag capture dialog","level":4,"markdown":"1. Press the **Copy All** button\n1. Open an external text editor\n1. Paste the text into a new text/log file\n1. Save the file (as .txt or .log)\n\n> [!NOTE]\n> Standard naming is: **captureFrame-DATE_TIME.log** - like `captureFrame-17452-2024-11-21_18-12-37.211027.log`\n\n> [!IMPORTANT]\n> 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"},{"heading":"diag_captureSlowFrame","level":4,"markdown":"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.\n\n```cpp\n[section, threshold, frameSkip, toFile, continuousCounter]\n```\n\n- Client: `diag_captureSlowFrame [\"total\", 0.03, 0, true, 1];`\n- Server: `[[\"total\", 0.03, 0, true, 1]] remoteExec [\"diag_captureSlowFrame\", 2];`"},{"heading":"Dedicated server","level":4,"markdown":"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.\n\nFor customized server side logging use the **remoteExec approach** or **console with remote/target execution**."},{"heading":"How to View a Capture","level":3,"markdown":"TODO"},{"heading":"Ingame","level":4,"markdown":"1. In the window you will be able to browse a lot of performance-related data, which can be interesting\n\nTODO"},{"heading":"Externally","level":4,"markdown":""},{"heading":"Perfetto UI Web Viewer","level":5,"markdown":"Pros:\n\n- Can view a frame capture without Arma 3 running\n- Nice visualization\n- Sub scopes easier to identify\n\nCons:\n\n- Fairly slow to load/display a frame capture\n- Navigation via mouse and keyboard not super intuitive - see **Support - Keyboard shortcuts** in the left side menu\n- Does not support viewing multiple frame captures (only via multiple tabs)\n- .trace JSON export from Arma 3 doesnt support more advanced features of Perfetto UI nor contains information on CPU-RAM use\n\nWebsite: https://ui.perfetto.dev\n\n> [!IMPORTANT]\n> Only supports `.trace` format frame captures!"},{"heading":"Tracy Live Viewer","level":5,"markdown":"Works only with the custom tracy version provided by Dedmen as part of the [Arma Script Profiler](https://steamcommunity.com/sharedfiles/filedetails/1652506957) mod.\n\n> [!NOTE]\n> Capturing live data needs a lot of RAM - up to 2 GB per minute (depends on detail level captured).\n\nPros:\n\n- Live frame capture\n- Multiple frame captures - see frame by frame\n- Statistics like number of executions, average and mean time execution\n- Selection of *zones* for specific analysis of any time frame\n- Profiling of unscheduled code. See: ArmaScriptProfiler\n\nCons:\n\n- Fairly advanced\n- Tracy UI more functional than visually nice\n\nRequired mods:\n\n1. CBA_A3: https://steamcommunity.com/workshop/filedetails/?id=450814997\n1. Arma Script Profiler: https://steamcommunity.com/sharedfiles/filedetails/?id=1652506957\n1. Intercept Minimal Dev: https://steamcommunity.com/workshop/filedetails/?id=1645973522\n\nExtra startup parameters: -profilerEnableEngine -profilerEngineThreads \"-mod=!Workshop\\@CBA_A3;!Workshop\\@Arma Script Profiler;!Workshop\\@Intercept Minimal Dev\"\n\n- How to use: https://github.com/dedmen/ArmaScriptProfiler/wiki\n- Additional command line parameters: https://github.com/dedmen/ArmaScriptProfiler/wiki/Command-line-parameters\n- Some more info at: https://forums.bohemia.net/forums/topic/211626-arma-script-profiler/\n- Source: https://github.com/dedmen/ArmaScriptProfiler\n- Discord for tech support and such: https://discord.gg/vbFje5B\n\nAdvanced info:\n\n- https://tracy.nereid.pl\n- https://github.com/wolfpld/tracy"},{"heading":"Scripting Commands","level":3,"markdown":"- diag_captureFrame\n- diag_captureSlowFrame\n- diag_logSlowFrame - not available in Arma 3. Since Arma 3 v2.20 diag_captureSlowFrame with **toFile** parameter can log to file as alternative.\n- diag_captureFrameToFile"},{"heading":"Creating Your Own Subtree","level":3,"markdown":"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.\nYou can create your own subtree inside siFEH by wrapping your function call inside a isNil CODE statement like this:\nTurn your old call which may look like this:\n\n```sqf\naddMissionEventHandler [\"EachFrame\", {\n call myPFHFunction\n}];\n```\n\nInto something like this:\n\n```sqf\naddMissionEventHandler [\"EachFrame\", {\n isNil { call myPFHFunction } // isNil creates the subtree\n}];\n```\n\nNow 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.\nIt will only show a part of the first line of that code so you should put something descriptive into the isNil statement.\nYou can use the same to create a subtree for any function you like. This will also work inside Scheduled (spawned) scripts.\nBut using this method to \"subtree\" a function with return values requires a little bit of trickery to get the return value out."},{"heading":"See Also","level":3,"markdown":"- Code Optimisation\n- Mission Optimisation"}],"categories":["Arma Scripting Tutorials","Eden Editor"],"groups":["Scripting"]}