Mission Parameters – Arma 3

From Bohemia Interactive Community
Jump to navigation Jump to search
(implementation)
m (→‎Config: Removed BIKI formatting from code)
(28 intermediate revisions by 5 users not shown)
Line 5: Line 5:
Important limitation. In an MP environment, the Paramsarray is not available on the client until some time after preinit. but before postinit so any code called upon the client should take this into consideration
Important limitation. In an MP environment, the Paramsarray is not available on the client until some time after preinit. but before postinit so any code called upon the client should take this into consideration


== Overview ==
== Manual Params ==
 
=== Config ===
Mission parameters are integer values that are passed to the mission at the beginning and which are used by the mission designer to customise user experience accordingly. The parameters are set in [[description.ext]]. They can also be either manually altered by a dedicated server admin or host during ROLE ASSIGNMENT in MP lobby from available parameters menu or by including override values in dedicated server config [[server.cfg]]. In short:
[[File:Arma3 Mission Parameters.png|thumb|Mission Parameters selection]]
 
Params are defined in [[description.ext]].
* Mission maker can set up a list of parameters for the game and set default values for each
<syntaxhighlight lang=cpp>
* Dedicated server admin or host can change default values by selection different options from provided parameters menu
* Dedicated server owner can additionally override the default values in server config for each mission separately
 
In any case, a person selecting parameters from parameters menu at the beginning of the mission has the final say what those options will be.
 
<gallery>
File:params.png|"Parameters" GUI
File:params_options.png|Available Options
File:params_edit.png|Editing Options
</gallery>
 
== Param Types ==
 
There are 2 types of parameters, primary and secondary. While primary parameters are inherited from earlier versions of Arma, they are still valid and recognised by the engine.
 
=== Primary Params ===
 
Also known as '''param1''' and '''param2'''. They are defined in the following way in [[description.ext]], for example:
 
<syntaxhighlight lang="cpp">
titleParam1 = "Time limit:";
textsParam1[] = {"Unlimited", "5 min", "10 min", "15 min"};
valuesParam1[] = {0, 300, 600, 900};
defValueParam1 = 900;
 
titleParam2 = "Score to win:";
textsParam2[] = {"Don't keep score", "50", "100", "150"};
valuesParam2[] = {0, 50, 100, 150};
defValueParam2 = 50;
</syntaxhighlight>
 
Here is some info about each entry and what it means:
 
* ''titleParam'' - This is the title that will be displayed in parameters menu available to server admin or host at ROLE ASSIGNMENT
* ''textsParam'' - These are options presented to the server admin or host when they double click on the title in the parameters menu
* ''valuesParam'' - These are the actual param values for each of the text options, that will be passed to the mission accordingly to chosen option
* ''defValueParam'' - This is default option which would be passed to the mission if no selection was made. It '''must''' match one of the ''valuesParam'' values
 
The chosen option value will be stored in '''param1''' or '''param2''' variable (respectfully) and then broadcast to everyone as [[publicVariable]]. As mentioned before, ''defValueParam'' value can be overridden from the server config. Here is an example of such override for both params in [[server.cfg]]:
<syntaxhighlight lang="cpp">
class Missions
{
class Mission1
{
template = "Mission1.Altis";
difficulty = "Veteran";
param1 = 600;
param2 = 100;
};
};
</syntaxhighlight>
 
As with ''defValueParam'' provided override values  '''must''' match one of the ''valuesParam'' values. The logged admin during ROLE ASSIGNMENT phase can still override even server override by selecting an option from parameters UI.
 
=== Secondary Params ===
 
You can think of the secondary params as primary params extended and wrapped in a class called ''Params'':
<syntaxhighlight lang="javascript">
class Params
class Params
{
{
class name1
class AISkill
{
{
title = "Item 1";
title = "AI Skill"; // Param name visible in the list
texts[] = {"One","Two","Three"};
values[] = {0,1,2}; // Values; must be integers; has to have the same number of elements as 'texts'
values[] = {1,2,3};
texts[] = {"Recruit","Regular","Veteran"}; // Description of each selectable item
default = 1;
default = 1; // Default value; must be listed in 'values' array, otherwise 0 is used
// Default values that are not whole numbers do not work. Param will default to 0 (or 1 if defined)
};
};
class name2
{
title = "Item 2";
texts[] = {"Ten","Twenty","Thirty"};
values[] = {10,20,30};
default = 20;
};
class name3
{
title = "Item 3";
texts[] = {"One Hundred","Two Hundred","Three Hundred"};
values[] = {100,200,300};
default = 300;
};
};
</syntaxhighlight>
As you can see the structure is the same, but the names of the entries are slightly different, but consistently different (apart from ''default''):
* ''title'' - (same as ''titleParam'') - This is the title that will be displayed in parameters menu available to server admin or host at ROLE ASSIGNMENT
* ''texts'' - (same as ''textsParam'') - These are options presented to the server admin or host when they double click on the title in the parameters menu
* ''values'' - (same as ''valuesParam'') - These are the actual param values for each of the text options, that will be passed to the mission accordingly to chosen option
* ''default'' - (same as ''defValueParam'') - This is default option which would be passed to the mission if no selection was made. It '''must''' match one of the ''values'' values
The chosen options values will be stored in '''paramsArray''' variable, in the order of appearance in the ''Params'' class and then broadcast to everyone as [[publicVariable]]. As with primary params, ''default'' value can be overridden from the server config using class names of the defined params. Here is an example of such override in [[server.cfg]]:
<syntaxhighlight lang="cpp">
class Missions
{
class Mission1
{
template = "Mission1.Altis";
difficulty = "Veteran";
class Params
{
name1 = 2;
name2 = 30;
name3 = 100;
};
};
};
</syntaxhighlight>
As override values provided '''must''' match one of the ''values'' values. The logged admin during ROLE ASSIGNMENT phase can still override the server override by selecting options from parameters UI manually.
=== Using Both Types ===
You should be careful when using both primary and secondary params in the same mission as '''paramsArray''' in this case will contain both types of parameters. For example, if just secondary params used from the example above, '''paramsArray''' would look something like this: [1,20,300]. However if both types are used at the same time, '''paramsArray''' will look something like this: [900,50,1,20,30]. The primary params are added in front of the secondary params in '''paramsArray'''.
== Mission Implementation ==
So how does it all come together? As pointed out, params are just values that are passed over to the mission. In order to retrieve passed param value in mission use [[BIS_fnc_getParamValue]] function. For example to retrieve mission param ''name2'':
<code>_param = ["name2", -1] [[call]] [[BIS_fnc_getParamValue]];</code>
This should return 20 (in default example above) or -1 if no param with this name is found. This method is good to be used in other scripts, but there is even better way of setting mission params at the start of the mission. You can instruct the game to run a function or a script of your choice automatically by including it in the secondary ''Params'' config. Note that it is not possible to do with primary params. For example:
<syntaxhighlight lang="cpp">
class Params
{
class Daytime
class Daytime
{
{
Line 143: Line 26:
values[] = {6,12,18,0};
values[] = {6,12,18,0};
default = 12;
default = 12;
function = "BIS_fnc_paramDaytime";
function = "BIS_fnc_paramDaytime"; // (Optional) Function called when player joins, selected value is passed as an argument
isGlobal = 1; // (Optional) 1 to execute script / function locally for every player who joins, 0 to do it only on server
};
};
};
</syntaxhighlight>
The [[BIS_fnc_paramDaytime]] function will be executed on mission start on the server. It will also receive current value of the parameter ''Daytime'' as an argument in <tt>[[_this]] [[select]] 0</tt>. You can also instruct the game to execute a script file instead and not just on server but on every client including the JIP clients:
<syntaxhighlight lang="cpp">
class Params
{
class ViewDistance
class ViewDistance
{
{
title = "View distance (in metres)";
title = "View distance (in metres)";
values[] = {500,1000,2000,5000};
values[] = {500,1000,2000,5000};
// When 'texts' are missing, values will be displayed directly instead
default = 1000;
default = 1000;
file = "setViewDistance.sqf";
file = "setViewDistance.sqf"; // (Optional) Script [[call]]ed when player joins, selected value is passed as an argument
isGlobal = 1;
};
};
};
};
</syntaxhighlight>
</syntaxhighlight>
The ''setViewDistance.sqf'' script will be [[execVM]]ed on every client. If for some weird reason you have both ''function'' and ''file'' entries, the priority is given to ''function''.
== Manual Params ==
=== Config ===
[[File:Arma3 Mission Parameters.png|thumb|Mission Parameters selection]]
Params are defined in [[description.ext]].
class Params
{
class AISkill
{
title = "AI Skill"; {{codecomment|// Param name visible in the list}}
values[] = {20,60,100}; {{codecomment|// Values; must be integers; has to have the same number of elements as 'texts'}}
texts[] = {"Recruit","Regular","Veteran"}; {{codecomment|// Description of each selectable item}}
default = 60; {{codecomment|// Default value; must be listed in 'values' array, otherwise 0 is used}}
                {{codecomment|// Default values that are not whole numbers do not work. Param will default to 0 (or 1 if defined)}}
};
class Daytime
{
title = "Time";
texts[] = {"Morning","Day","Evening","Night"};
values[] = {6,12,18,0};
default = 12;
function = "BIS_fnc_paramDaytime"; {{codecomment|// (Optional) [[Functions_Library_(Arma_3)|Function]] [[call]]ed when player joins, selected value is passed as an argument}}
  isGlobal = 1; {{codecomment|// (Optional) 1 to execute script / function locally for every player who joins, 0 to do it only on server}}
};
class ViewDistance
{
title = "View distance (in metres)";
values[] = {500,1000,2000,5000};
{{codecomment|// When 'texts' are missing, values will be displayed directly instead}}
default = 1000;
file = "setViewDistance.sqf"; {{codecomment|// (Optional) Script [[call]]ed when player joins, selected value is passed as an argument}}
};
};


=== Mission ===
=== Mission ===
Selected values are stored in '''paramsArray''' array, accessible anytime during the mission on any connected computer. Their order is the same as is in description.cfg (for example, params above would result in [12,1] if default values were kept).
Selected values are stored in '''paramsArray''' array, accessible anytime during the mission on any connected computer. Their order is the same as is in description.ext (for example, params above would result in [12,1] if default values were kept).


'''Example (can be used in [[init.sqf]]):'''
'''Example (can be used in [[init.sqf]]):'''
if ([[isServer]]) then {
<code>if ([[isServer]]) then  
_skill = paramsArray [[select]] 0;
{
{
_skill = [0.1, 0.5, 1] [[select]] (paramsArray [[select]] 0);
_x [[setSkill]] _skill;
{
} [[forEach]] [[allUnits]];
_x [[setSkill]] _skill;
};
}  
[[forEach]] [[allUnits]];
};</code>


'''setViewDistance.sqf:'''
'''setViewDistance.sqf:'''
Line 214: Line 57:


=== Functions ===
=== Functions ===
When you're not sure about order of '''paramsArray''' items (e.g., in a module which can be used in any mission), you can use [[BIS_fnc_getParamValue]] to get value of a param with given classname.
<u>It is highly recommended</u> that you use [[BIS_fnc_getParamValue]] instead of paramsArray to get value of a param with given class name. It is fast and secure and globally available on any connected PC as well as JIP.
 
_viewDistance = "ViewDistance" call BIS_fnc_getParamValue;


<code>_viewDistance = "ViewDistance" [[call]] [[BIS_fnc_getParamValue]];
_viewDistance = ["ViewDistance", 500] [[call]] [[BIS_fnc_getParamValue]];</code>


== Predefined Params ==
== Predefined Params ==
Arma 3 introduces a framework for defining commonly used params (e.g., time of the day or mission duration), which can be shared across multiple missions. Once included to description.ext, they will initialize automatically. Some of them can be further customized using specific [[PreProcessor_Commands|macros]].
Arma 3 introduces a framework for defining commonly used params (e.g., time of the day or mission duration), which can be shared across multiple missions. Once included to description.ext, they will initialize automatically. Some of them can be further customized using specific [[PreProcessor_Commands|macros]].
<syntaxhighlight lang=cpp>
class Params
{
#define COUNTDOWN_MIN 600
#define COUNTDOWN_MAX 3600
#define COUNTDOWN_DEFAULT -1
#include "\a3\functions_f\Params\paramCountdown.hpp"
#define DAYTIMEHOUR_DEFAULT 19
#include "\a3\functions_f\Params\paramDaytimeHour.hpp"
//#define DAYTIMEPERIOD_DEFAULT 12
//#include "\a3\functions_f\Params\paramDaytimePeriod.hpp"
#define DEBUGCONSOLE_DEFAULT 1
#include "\a3\functions_f\Params\paramDebugConsole.hpp"
#define GUERFRIENDLY_DEFAULT -1
#include "\a3\functions_f\Params\paramGuerFriendly.hpp"
#define TICKETS_MIN 100
#define TICKETS_MAX 1100
#define TICKETS_DEFAULT -1
#include "\a3\functions_f\Params\paramRespawnTickets.hpp"
#define WEATHER_DEFAULT 40
#include "\a3\functions_f\Params\paramWeather.hpp"


class Params
#define TIMEACCELERATION_DEFAULT 10
{
#include "\a3\Functions_F_MP_Mark\Params\paramTimeAcceleration.hpp"
#include "\a3\functions_f\Params\paramWeather.hpp"
 
#define VIEW_DISTANCE_MIN 1500
#define TICKETS_DEFAULT 600
#define VIEW_DISTANCE_MAX 4000
#include "\a3\functions_f\Params\paramRespawnTickets.hpp"
#define VIEW_DISTANCE_DEFAULT 2000
};
#include "\a3\Functions_F_Heli\Params\paramViewDistance.hpp"
 
        #include "\a3\Functions_F\Params\paramRevive.hpp"
 
};
</syntaxhighlight>


{{Important|Param templates currently don't work with PBO missions manually copied to MPMissions folder. Unpacked missions, Steam missions and [[Mission_Export#Addon_Format|missions which are part of an addon]] works correctly.}}
{{Important|Param templates currently don't work with PBO missions manually copied to MPMissions folder. Unpacked missions, Steam missions and [[Mission_Export#Addon_Format|missions which are part of an addon]] works correctly.}}
Line 240: Line 115:


|-
|-
| <code>\a3\functions_f\Params\paramCountdown.hpp</code>
| <code>\a3\functions_f\Params\paramCountdown.hpp</code><code>\a3\functions_f\Params\paramCountdownNoDisabled.hpp</code>
| Set mission countdown (in seconds)
| Set mission countdown (in seconds)<br />The "NoDisabled" version has no "disabled" option, and will pick the middle option by default.
|
|
  #define COUNTDOWN_MIN 600
  #define COUNTDOWN_MIN 600
Line 263: Line 138:
|-
|-
| <code>\a3\functions_f\Params\paramDebugConsole.hpp</code>
| <code>\a3\functions_f\Params\paramDebugConsole.hpp</code>
| Allow [[Mission_Editor:_Debug_Console|debug console]] for logged in admin
| Allow [[Mission_Editor:_Debug_Console_(Arma_3)|debug console]] for server host or logged in admin
|
|
  {{codecomment| //0 (disabled) or 1 (enabled)}}
  {{codecomment| //0 (disabled) or 1 (enabled)}}
Line 276: Line 151:


|-
|-
| <code>\a3\functions_f\Params\paramRespawnTickets.hpp</code>
| <code>\a3\functions_f\Params\paramRespawnTickets.hpp</code><code>\a3\functions_f\Params\paramRespawnTicketsNoDisabled.hpp</code>
| Set respawn tickets for all sides
| Set respawn tickets for all sides<br />The "NoDisabled" version has no "disabled" option, and will pick the middle option by default.
|
|
  #define TICKETS_MIN 100
  #define TICKETS_MIN 100
Line 288: Line 163:
|
|
  {{codecomment| //Can be 0 (sunny), 25, 50, 75 or 100 (storm))}}
  {{codecomment| //Can be 0 (sunny), 25, 50, 75 or 100 (storm))}}
  #define WEATHER_DEFAULT 40
  #define WEATHER_DEFAULT 75


|-
|-
Line 304: Line 179:
  #define VIEW_DISTANCE_MAX 4000
  #define VIEW_DISTANCE_MAX 4000
  #define VIEW_DISTANCE_DEFAULT 2000
  #define VIEW_DISTANCE_DEFAULT 2000
|-
| <code>"\a3\Functions_F\Params\paramRevive.hpp"</code>
| Set various revive related options [[Arma 3 Revive]]
|
Nothing
|}


|}
== See Also ==
* [[Mission Parameters]]
* [[Description.ext#Mission_parameters|Description.ext]]

Revision as of 17:44, 19 July 2019


Server admin / host can customize multiplayer missions in ROLE ASSIGNMENT menu using parameters prepared by the mission designer.

Important limitation. In an MP environment, the Paramsarray is not available on the client until some time after preinit. but before postinit so any code called upon the client should take this into consideration

Manual Params

Config

Mission Parameters selection

Params are defined in description.ext. 

class Params
{
	class AISkill
	{
		title = "AI Skill"; // Param name visible in the list
		values[] = {0,1,2}; // Values; must be integers; has to have the same number of elements as 'texts'
		texts[] = {"Recruit","Regular","Veteran"}; // Description of each selectable item
		default = 1; // Default value; must be listed in 'values' array, otherwise 0 is used
		// Default values that are not whole numbers do not work. Param will default to 0 (or 1 if defined)
	};
	class Daytime
	{
		title = "Time";
		texts[] = {"Morning","Day","Evening","Night"};
		values[] = {6,12,18,0};
		default = 12;
		function = "BIS_fnc_paramDaytime"; // (Optional) Function called when player joins, selected value is passed as an argument
		isGlobal = 1; // (Optional) 1 to execute script / function locally for every player who joins, 0 to do it only on server
	};
	class ViewDistance
	{
		title = "View distance (in metres)";
		values[] = {500,1000,2000,5000};
		// When 'texts' are missing, values will be displayed directly instead
		default = 1000;
		file = "setViewDistance.sqf"; // (Optional) Script [[call]]ed when player joins, selected value is passed as an argument
	};
};

Mission

Selected values are stored in paramsArray array, accessible anytime during the mission on any connected computer. Their order is the same as is in description.ext (for example, params above would result in [12,1] if default values were kept).

Example (can be used in init.sqf): if (isServer) then { _skill = [0.1, 0.5, 1] select (paramsArray select 0); { _x setSkill _skill; } forEach allUnits; };

setViewDistance.sqf: 

setViewDistance (_this select 0);

Functions

It is highly recommended that you use BIS_fnc_getParamValue instead of paramsArray to get value of a param with given class name. It is fast and secure and globally available on any connected PC as well as JIP.

_viewDistance = "ViewDistance" call BIS_fnc_getParamValue; _viewDistance = ["ViewDistance", 500] call BIS_fnc_getParamValue;

Predefined Params

Arma 3 introduces a framework for defining commonly used params (e.g., time of the day or mission duration), which can be shared across multiple missions. Once included to description.ext, they will initialize automatically. Some of them can be further customized using specific macros. 

class Params
{
	#define COUNTDOWN_MIN 600
	#define COUNTDOWN_MAX 3600
	#define COUNTDOWN_DEFAULT -1
	#include "\a3\functions_f\Params\paramCountdown.hpp"

	#define DAYTIMEHOUR_DEFAULT 19
	#include "\a3\functions_f\Params\paramDaytimeHour.hpp"

	//#define DAYTIMEPERIOD_DEFAULT 12
	//#include "\a3\functions_f\Params\paramDaytimePeriod.hpp"

	#define DEBUGCONSOLE_DEFAULT 1
	#include "\a3\functions_f\Params\paramDebugConsole.hpp"

	#define GUERFRIENDLY_DEFAULT -1
	#include "\a3\functions_f\Params\paramGuerFriendly.hpp"

	#define TICKETS_MIN 100
	#define TICKETS_MAX	1100
	#define TICKETS_DEFAULT	-1
	#include "\a3\functions_f\Params\paramRespawnTickets.hpp"

	#define WEATHER_DEFAULT	40
	#include "\a3\functions_f\Params\paramWeather.hpp"

	#define TIMEACCELERATION_DEFAULT 10
	#include "\a3\Functions_F_MP_Mark\Params\paramTimeAcceleration.hpp"

	#define VIEW_DISTANCE_MIN 1500
	#define VIEW_DISTANCE_MAX 4000
	#define VIEW_DISTANCE_DEFAULT 2000
	#include "\a3\Functions_F_Heli\Params\paramViewDistance.hpp"

        #include "\a3\Functions_F\Params\paramRevive.hpp"

};
⚠
Param templates currently don't work with PBO missions manually copied to MPMissions folder. Unpacked missions, Steam missions and missions which are part of an addon works correctly.

Available Templates

File Description Optional variables
\a3\functions_f\Params\paramCountdown.hpp\a3\functions_f\Params\paramCountdownNoDisabled.hpp Set mission countdown (in seconds)
The "NoDisabled" version has no "disabled" option, and will pick the middle option by default. 
#define COUNTDOWN_MIN		600
#define COUNTDOWN_MAX		3600
#define COUNTDOWN_DEFAULT	-1
\a3\functions_f\Params\paramDaytimeHour.hpp Set starting hour, options are represented by whole hours 
 //Can be any integer between 0 and 23
#define DAYTIMEHOUR_DEFAULT	19
\a3\functions_f\Params\paramDaytimePeriod.hpp Set starting hour, options are described by words 
 //Can be 0, 6, 12 or 18
#define DAYTIMEPERIOD_DEFAULT	12
\a3\functions_f\Params\paramDebugConsole.hpp Allow debug console for server host or logged in admin 
 //0 (disabled) or 1 (enabled)
#define DEBUGCONSOLE_DEFAULT	1
\a3\functions_f\Params\paramGuerFriendly.hpp Set to whom will independent side be friendly 
 //Can be any -1 (Nobody}, 0 (OPFOR), 1 (BLUFOR) or 2 (Everybody)
#define GUERFRIENDLY_DEFAULT	-1
\a3\functions_f\Params\paramRespawnTickets.hpp\a3\functions_f\Params\paramRespawnTicketsNoDisabled.hpp Set respawn tickets for all sides
The "NoDisabled" version has no "disabled" option, and will pick the middle option by default. 
#define TICKETS_MIN		100
#define TICKETS_MAX		1100
#define TICKETS_DEFAULT		-1
\a3\functions_f\Params\paramWeather.hpp Set default weather 
 //Can be 0 (sunny), 25, 50, 75 or 100 (storm))
#define WEATHER_DEFAULT		75
\a3\Functions_F_MP_Mark\Params\paramTimeAcceleration.hpp Sets a time multiplier for in-game time. See setTimeMultiplier 
 //Can be x1, x2, x5, x10 or x20
#define TIMEACCELERATION_DEFAULT	10
\a3\Functions_F_Heli\Params\paramViewDistance.hpp Set rendering distance, in meters. See setViewDistance 
#define VIEW_DISTANCE_MIN	1500
#define VIEW_DISTANCE_MAX	4000
#define VIEW_DISTANCE_DEFAULT	2000
"\a3\Functions_F\Params\paramRevive.hpp" Set various revive related options Arma 3 Revive

Nothing

See Also

Retrieved from "https://community.bistudio.com/wiki?title=Arma_3:_Mission_Parameters&oldid=125058"