R3vo/Sandbox – User

From Bohemia Interactive Community
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
 
(18 intermediate revisions by the same user not shown)
Line 1: Line 1:
<!--= Spearhead 1944 Voting UI =-->
{{TOC|side}}
{{TOC|side}}
The '''Spearhead 1944''' CDLC introduces a unique way to allow for scenario customization, the voting UI.</br>
If you have ever wondered why you scenario is running so badly, performance profiling is the way to find it out. It allows you to find bottlenecks and slow code by capturing a "slow" frame.
[[File:spe mapVote ui.jpg|500px]]</br>
The captured data can then be viewed and analysed.
Features:
* Autogenerated UI for up to six voting options
* Supports images, title and description
* Customizable voting timer
* Singleplayer and multiplayer compatible
* Easy to set up


= Configuration =
== Getting the correct Version ==
== Placing Map Markers ==
Profiling is enabled in the following {{arma3}} versions
In order for the vote UI to know the locations of your voting positions, we will use markers. In our example we call them {{hl|start_n}} where {{hl|n}} is going to be a number from 1 to 2 to create two voting options. The number of markers defines how many voting options will be available. Up to six voting options are supported e.g. {{hl|start_1, start_2, ..., start_6}}
* arma3profiling_x64.exe - '''Part of the Performance Profiling Build'''
Place the markers where the voting options should appear on the map.
* arma3diag_x64.exe - '''Part of the Development Build'''


== Adding the UI Code ==
Read [[Arma_3: Steam Branches]] for a guide on how to access these branches.
The code for the voting logic runs on all machines, client, hosted server and dedicated server. Thus, best place to execute it is from within the [[init.sqf]].


{{hl|init.sqf}}
{{Feature|informative|It is recommended to use the '''Performance Profiling Build''' (arma3profiling_x64.exe) for performance profiling because:
<sqf>[
* Has tools that might not make it into development build
  "start_",
* Has all the profiling related commands that ''arma3diag_x64.exe'' has
  {true}, // Voter Eligible
* Its performance is closer to the default ''arma3_x64.exe''}}
  [{(time > 1) || (!isNil "SPE_missionUtilityFunctions_skipVote")}, {((getClientStateNumber >= 10) || (!isNil "SPE_missionUtilityFunctions_skipVote")) && {time > 3}}] select (isMultiplayer), // Vote end condition
  { // completion code (hasInterface inc. JiP)
  },
  { //completion code (server)
  },
  {},
  {//OnHover, map markers
    systemChat str _this;
  },
  ["SPE_b_Icon_Axis_Armored", "SPE_b_Icon_Axis_Armored", "SPE_b_Icon_Axis_Armored", "SPE_b_Icon_Axis_Armored"],
  [[0.34, 0.42, 0.44, 1], [0.34, 0.42, 0.44, 1], [0.34, 0.42, 0.44, 1], [0.34, 0.42, 0.44, 1]],
  [
    ["start_1", ["Title 1", "\WW2\SPE_Missions_p\Scenarios_p\data\Voting_DerZahnarzt_Sabotage.paa", "Description 1", "\WW2\SPE_Missions_p\Scenarios_p\data\Voting_DerZahnarzt_Sabotage.paa"]],
    ["start_2", ["Title 2", "\WW2\SPE_Missions_p\Scenarios_p\data\Voting_DerZahnarzt_Sabotage.paa", "Description 2", "\WW2\SPE_Missions_p\Scenarios_p\data\Voting_DerZahnarzt_Sabotage.paa"]]
  ],
  "start_1",
  [
    [
      "Option 1",
      "Description 1",
      localize "STR_SPE_Scenario_Der_Zahnarzt_Vote_Detail_Start_Option_1_Advantages",
      "\WW2\SPE_Missions_p\Scenarios_p\data\Voting_DerZahnarzt_Sabotage_bw.paa",
      "\WW2\SPE_Missions_p\Scenarios_p\data\Voting_DerZahnarzt_Sabotage.paa"
    ],
    [
      "Option 2",
      "Description 2",
      localize "STR_SPE_Scenario_Der_Zahnarzt_Vote_Detail_Start_Option_1_Advantages",
      "\WW2\SPE_Missions_p\Scenarios_p\data\Voting_DerZahnarzt_Sabotage_bw.paa",
      "\WW2\SPE_Missions_p\Scenarios_p\data\Voting_DerZahnarzt_Sabotage.paa"
    ]
  ],
  [false],
  {!(isNull findDisplay 46)},
  true
] spawn SPE_missionUtilityFunctions_fnc_mapVote_init;</sqf>


=== Function Parameters ===
== Frame Capturing ==
==== Syntax ====
There are several commands that allow you to capture a frame.
<sqf>
* [[diag_captureFrame]]
[
* [[diag_captureSlowFrame]]
_prefix,  
* [[diag_logSlowFrame]] - not available in Arma 3 :(
_condition,  
* [[diag_captureFrameToFile]]
_completionCondition,
In most cases you do not want to capture any or all frames, you just want to capture "slow" frames. A slow frame is a frame that takes longer than the average frame and slows down the game.
_clientCode,
 
_completionCode,
== How to Use ==  
_updateSelectionCode,
# Run a mission
_hoverCandidateCode,
# Execute a scripted command <sqf inline>diag_captureSlowFrame ["total", 0.3];</sqf> using any means ([[Arma 3: Debug Console|Debug Console]], mission radio trigger...)
_groupIcons,
# Once a slow frame is detected, a window will open
_groupIconParams,
# In the window you will be able to browse a lot of performance-related data, which can be interesting
_cfgOrbat,
# To export the gathered information for sharing with others:
_defaultSelection,
## Select Main Thread (if not selected yet)
_uiData,
## Press the Copy button
_timer,
## Open an external text editor
_uiFadeOutCondition,
## Paste the text into a new file
_waitForPlayers
## Save the file
] call SPE_missionUtilityFunctions_fnc_mapVote_init;</sqf>
 
== Capture Frame UI ==
[[File: arma3-capture frame ui overview.png]]
 
# {{Wiki|TODO}}
# {{Wiki|TODO}}
# {{Wiki|TODO}}
# {{Wiki|TODO}}
# {{Wiki|TODO}}
# {{Wiki|TODO}}
# {{Wiki|TODO}}
# {{Wiki|TODO}}
# {{Wiki|TODO}}
 
== External Viewer ==
* chrome://tracing
* https://ui.perfetto.dev/


==== Parameters ====
[[File:Performance_Profiling_04.png|thumb|diag_captureFrame sample output with custom subtree]]
# {{hl|_prefix:}} [[String]] - Prefix of all voting markers e.g. start_1, start_2, ..., start_6, optional, default <sqf inline>"player_spawn_"</sqf>
== Creating Your Own Subtree ==
# {{hl|_condition:}} [[Code]] - Condition that must be true for given [[player]] in order to see the vote, optional, default <sqf inline>{[[true]]}</sqf>
# {{hl|_completionCondition:}} [[Code]] - Condition that must be true for the voting to be considered done, optional, default <sqf inline>{[[time]] > 1}</sqf>
# {{hl|_clientCode:}} [[Code]] - Code that is executed on the client when the voting has finished and for JIP player, optional, default <sqf inline>{params ["_prefix", "_marker", "_conditionResult"];}</sqf>
# {{hl|_completionCode:}} [[Code]] - Code that is executed on the server when the voting has finished, optional, default <sqf inline>{params ["_prefix", "_marker"];}</sqf>
# {{hl|_updateSelectionCode:}} [[Code]] - Code that is executed on the client when the voting selection changes, optional, default <sqf inline>{params ["_prefix", "_winningMarkers", "_allMarkers"];}</sqf>
# {{hl|_hoverCandidateCode:}} [[Code]] - Code that is executed on the client when hovering over the voting option, optional, default <sqf inline>{params ["_marker", "_hover", "_conditionResult", ["_cleanup", false]];}</sqf>
# {{hl|_groupIcons:}} [[Array]] - Vote textures used for the map voting markers, optional, default <sqf inline>["selector_selectedFriendly", "selector_selectedEnemy", "selector_selectedFriendly", "selector_selectedEnemy"]</sqf> //TODO: What is this exactly?
# {{hl|_groupIconParams:}} [[Array]] - Vote colors used for the map voting markers, optional, default <sqf inline>[[VOTE_UI_COLOUR_DEFAULT_RGBA], [VOTE_UI_COLOUR_VOTED_RGBA], [0.7, 0.7, 0.7, 0], [0.5, 1, 0.5, 0]]</sqf> //TODO: What is this exactly?
# {{hl|_cfgOrbat:}} [[Array]] of [[Array|arrays]] - [[Arma 3: ORBAT Viewer|CfgORBAT]] parameters used to fill map voting markers, optional, default <sqf inline>[]</sqf>
<sqf>[
"start_1", //Marker indicating the voting location
[
"Title 1", //Title displayed when hovering over the marker
"\WW2\SPE_Missions_p\Scenarios_p\data\Voting_DerZahnarzt_Sabotage.paa", //Image shown when hovering over the marker
"Description 1", //Description displayed when hovering over the marker
"\WW2\SPE_Missions_p\Scenarios_p\data\Voting_DerZahnarzt_Sabotage.paa" //Image shown when hovering over the marker
]
]</sqf>
# {{hl|_defaultSelection:}} [[String]] - Marker name that is selected by default, optional, default <sqf inline>""</sqf>
# {{hl|_uiData:}}  [[Array]] of [[Array|arrays]] - Data to fill the UI, optional, default <sqf inline>[]</sqf>
<sqf>[
[
"Option 1", //Title of the voting option
"Description 1", //Description of the voting option
localize "STR_SPE_Scenario_Der_Zahnarzt_Vote_Detail_Start_Option_1_Advantages", //Additional text displayed of the voting option
"\WW2\SPE_Missions_p\Scenarios_p\data\Voting_DerZahnarzt_Sabotage_bw.paa", //Image that is being used if this option is not selected or hovered over
"\WW2\SPE_Missions_p\Scenarios_p\data\Voting_DerZahnarzt_Sabotage.paa" //Image that is being used if this option is selected or hovered over
]
]</sqf>
# {{hl|_timer:}} [[Boolean]], [[Code]], [[Number]], [[String]] - Voting timer setting, optional, default <sqf inline>[]</sqf>
## When [[Boolean]] - ???
## When [[Code]] - First number in array will be used
## When [[Number]] - Value is used as timer
## When [[String]] - A [[missionNamespace]] variable with given name is begin looked up for a valid value
# {{hl|_uiFadeOutCondition:}} [[Code]] - Condition to fade out the voting UI, optional, default <sqf inline>{missionNamespace getVariable [QGVAR(array), []] isEqualTo []}</sqf>
# {{hl|_waitForPlayers:}} [[Boolean]] - Should UI wait for players, default <sqf inline>false</sqf>


= After Voting =
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.<br>
After the voting has finished and the winner was evaluated, the result of the vote is saved into {{hl|SPE_missionutilityfunctions_mapvote_start_marker}}. This variable holds the marker name of the voting option that has won.
You can create your own subtree inside siFEH by wrapping your function call inside a [[isNil]] CODE statement like this:<br>
We can now use that result to adjust our scenario accordingly. For example we can move players around, hide certain compositions, change loadouts or enemy presence.
Turn your old call which may look like this:
<sqf>
addMissionEventHandler ["EachFrame", {
call myPFHFunction
}];
</sqf>


Into something like this:
<sqf>
<sqf>
switch SPE_missionutilityfunctions_mapvote_start_marker do
addMissionEventHandler ["EachFrame", {
{
isNil { call myPFHFunction } // isNil creates the subtree
  case "start_1": {/* Do things... */};
}];
  case "start_2": {/* Do things... */};
  case "start_3": {/* Do things... */};
  case "start_4": {/* Do things... */};
  case "start_5": {/* Do things... */};
  case "start_6": {/* Do things... */};
  default {/* Should never be executed... */};
};
</sqf>
</sqf>


= Example Scenario =
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.<br>
[https://1drv.ms/u/s!AvgETyKiA6bQscEGoauxZVsxiiiJLw?e=0VKEaX Spearhead 1944 - Map Vote UI Tutorial Scenario.zip (OneDrive)]
It will only show a part of the first line of that code so you should put something descriptive into the [[isNil]] statement.<br>
You can use the same to create a subtree for any function you like. This will also work inside [[Scheduler#Scheduled_Environment|Scheduled]] ([[spawn]]ed) scripts. <br>
But using this method to "subtree" a function with return values requires a little bit of trickery to get the return value out.
 
 
== Notes ==
 
* 0.3 is a time in second used to determine what duration of a frame you consider abnormal, and first such frame will be captured.
* 0.3 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 or 0.1.  
* If it triggers too early, before the main slowdown happens, increase it to a higher value, e.g. 1.0.
 
 
== See Also ==
 
* [[Code Optimisation]]
* [[Mission Optimisation]]
 
 
[[Category:Arma Scripting Tutorials]]

Latest revision as of 12:37, 26 October 2024

If you have ever wondered why you scenario is running so badly, performance profiling is the way to find it out. It allows you to find bottlenecks and slow code by capturing a "slow" frame. The captured data can then be viewed and analysed.

Getting the correct Version

Profiling is enabled in the following Arma 3 versions

  • arma3profiling_x64.exe - Part of the Performance Profiling Build
  • arma3diag_x64.exe - Part of the Development Build

Read Arma_3: Steam Branches for a guide on how to access these branches.

It is recommended to use the Performance Profiling Build (arma3profiling_x64.exe) for performance profiling because:
  • Has tools that might not make it into development build
  • Has all the profiling related commands that arma3diag_x64.exe has
  • Its performance is closer to the default arma3_x64.exe

Frame Capturing

There are several commands that allow you to capture a frame.

In most cases you do not want to capture any or all frames, you just want to capture "slow" frames. A slow frame is a frame that takes longer than the average frame and slows down the game.

How to Use

  1. Run a mission
  2. Execute a scripted command diag_captureSlowFrame ["total", 0.3]; using any means (Debug Console, mission radio trigger...)
  3. Once a slow frame is detected, a window will open
  4. In the window you will be able to browse a lot of performance-related data, which can be interesting
  5. To export the gathered information for sharing with others:
    1. Select Main Thread (if not selected yet)
    2. Press the Copy button
    3. Open an external text editor
    4. Paste the text into a new file
    5. Save the file

Capture Frame UI

arma3-capture frame ui overview.png

  1. 🚧
    TODO: this must be updated.
  2. 🚧
    TODO: this must be updated.
  3. 🚧
    TODO: this must be updated.
  4. 🚧
    TODO: this must be updated.
  5. 🚧
    TODO: this must be updated.
  6. 🚧
    TODO: this must be updated.
  7. 🚧
    TODO: this must be updated.
  8. 🚧
    TODO: this must be updated.
  9. 🚧
    TODO: this must be updated.

External Viewer

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.


Notes

  • 0.3 is a time in second used to determine what duration of a frame you consider abnormal, and first such frame will be captured.
  • 0.3 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 or 0.1.
  • If it triggers too early, before the main slowdown happens, increase it to a higher value, e.g. 1.0.


See Also