ImperialAlex/FixedArsenal – User

@XLA_FixedArsenal

The Arsenal (often called 'virtual arsenal') is a very impressive character/equipment editor for Arma 3 developed by Karel Mořický of Bohemia Interactive. The arsenal has been part of Arma 3 since v1.24 ('Bootcamp' update).

The feature is implemented entirely with SQF functions and UI Cfg with no in-engine components.

This means that it is possible to change aspects of this system by either overriding or copying-and-modifying parts of it. The @XLA_FixedArsenal mods does exactly this. Previous versions would override the arsenal implementation while current versions add a duplicated (and modified) version that works alongside the 'vanilla' version.

Usage (Scripting)

The official Arsenal wiki page gives a good introduction to using the 'vanilla' arsenal in missions.

Unrestricted Arsenal

	@XLA_FixedArsenal	'vanilla' Arma 3
Opening (unrestricted) arsenal. Will open arsenal where executed. Useful in the debug console or as part of scripts.	["Open",true] spawn xla_fnc_arsenal;	["Open",true] spawn BIS_fnc_arsenal;
Creating an 'arsenal crate'. (Explanation of Parameters)	["AmmoboxInit",[<box>,<allowAll>,<condition>,<text>,<allowEquipped>]] spawn xla_fnc_arsenal; box: Object - ammo box on which the action will be added allowAll (Optional): Boolean Set to true to add all weapons, magazines, items and backpacks to the box (default: false) condition (Optional): Condition for showing the Arsenal action (default: {true}) Passed arguments are the same as in addAction condition, i.e., _target - the box, _this - caller text (Optional): String that is shown in the addAction on the box (default: "Arsenal")* Can take structuredText (e.g. colour, bold, etc) allowEquipped (Optional): Boolean Set to true to add players current equipment to available equipment (default: true) It is recommended to set this to false when allowAll is false. Makes whitelisting rules easier to understand.	["AmmoboxInit",[<box>,<allowAll>,<condition>]] spawn BIS_fnc_arsenal; box: Object - ammo box on which the action will be added allowAll (Optional): Boolean  Set to true to add all weapons, magazines, items and backpacks to the box (default: false) condition (Optional): Condition for showing the Arsenal action (default: {true}) Passed arguments are the same as in addAction condition, i.e., _target - the box, _this - caller
Example: Unrestricted crate. In case of modded version also with custom text.	["AmmoboxInit",[this,true,{true},"<t color='#45B6EA'>Open Arsenal")]] spawn xla_fnc_arsenal;	["AmmoboxInit",[this,true,{true})]] spawn BIS_fnc_arsenal;

Restricted Arsenal

The arsenal has an option to restrict the items that are available (N.B. there will always be infinitely many copies available, the restriction limits what items are available, not how many copies of those items are available).

This is done via a system dubbed 'virtual cargo' (internally implemented as arrays of classnames held in the ammocrate's object namespace and/or the mission namespace). This virtual cargo can be manipulated with various functions:

	@XLA_FixedArsenal	'vanilla' Arma 3
Generic Add Function Call (same for all types)	[<target>,<classes>,<isGlobal>,<addAction>] call xla_fnc_addVirtualWeaponCargo; target: Object or Namespace - ammo box to which classes will be added. When missionNamespace is used, they will be available across all boxes. classes: Boolean or Array of Strings - whitelisted classes. Alternatively, use true to whitelist everything of the given type !! N.B. Known Bug in v2.0.2: ["%ALL"] only works properly in "side" cargo/blacklist. isGlobal (Optional): Boolean - true to add classes globally (default: false) addAction (Optional): Code  {true} to add "Arsenal" action which players can access the Arsenal (default: {true}) Will always add the default "Arsenal" text. Set to false and use AmmoBoxInit for custom text. Returned value:  Array of Arrays: All virtual items within the target's space in format [<items>,<weapons>,<magazines>,<backpacks>,<sides>]	[<target>,<classes>,<isGlobal>,<addAction>] call BIS_fnc_addVirtualWeaponCargo; target: Object or Namespace - ammo box to which classes will be added. When missionNamespace is used, they will be available across all boxes. classes: Boolean or Array of Strings - whitelisted classes. Alternatively, use true to whitelist everything of the given type Using ["%ALL"] has the same effect isGlobal (Optional): Boolean - true to add classes globally (default: false) addAction (Optional): Code - {true} to add "Arsenal" action which players can access the Arsenal (default: {true}) Returned value: Array of Arrays: All virtual items within the target's space in format [<items>,<weapons>,<magazines>,<backpacks>]
Generic Remove Function Call (same for all types)	[<target>,<classes>,(<isGlobal>)] call xla_fnc_removeVirtualWeaponCargo; target: Object or Namespace - ammo box from which classes will be removed. classes: Array of Stringss - removed classes isGlobal (Optional): Boolean - true to remove classes globally (default: false) Returned value: Array of Arrays: All virtual items within the target's space in format [<items>,<weapons>,<magazines>,<backpacks>,<sides>]	[<target>,<classes>,(<isGlobal>)] call BIS_fnc_removeVirtualWeaponCargo; target: Object or Namespace - ammo box from which classes will be removed. classes: Array of Stringss - removed classes isGlobal (Optional): Boolean - true to remove classes globally (default: false) Returned value: Array of Arrays: All virtual items within the target's space in format [<items>,<weapons>,<magazines>,<backpacks>]
Generic Get Function Call (same for all types)	[<target>] call xla_fnc_getVirtualWeaponCargo; target: Object or Namespace - ammo box from which classes will be removed Returned value: Array of Arrays: All virtual items within the target's space in format [<items>,<weapons>,<magazines>,<backpacks>,<sides>]	[<target>] call BIS_fnc_getVirtualWeaponCargo; target: Object or Namespace - ammo box from which classes will be removed Returned value: Array of Arrays: All virtual items within the target's space in format [<items>,<weapons>,<magazines>,<backpacks>]

Instead of "Weapon" in the function names you can substitute "Weapon", "Magazine","Item", "Backpack" or "Side" (Side is only an option in the modded version and will be explained shortly).

	Usage
Weapon	Primary weapons like rifles, secondary weapons like launchers and handguns (pistols). Binoculars/Rangefinders and Laser-designators are also considered "Weapon"s. The "mine detector" migh also be a "Weapon".
Magazine	Magazines for rifles, launchers pistols Also grenades and explosives
Item	Goggles, GPS, watch, compass, first aid kits, toolkits, etc
Backpack	Backpacks, including static weapon backpacks
Side	Used for "side" based whitelisting. See explanation below.

Blacklisting

This feature is exclusive to the modded version. It essentially represents a second "Virtual Cargo" (again, array of classnames stored in object/mission namespace).

Any items present on the blacklist will not be available in the arsenal. This only makes sense in combination when using either the "Side" system or when using "%ALL" in at least one Virtual Cargo type. (!! currently broken in v2.0.2)

The blacklist functions work in the exact same way, simply replace "Cargo" with "Blacklist", i.e.

 [<target>,<classes>,<isGlobal>,<addAction>] call xla_fnc_addVirtualWeaponBlacklist;

will add classes to the blacklist for weapons.

"Side"-system

This is another feature that is only present in the modded version. This systems works by looking up the config of each item in the arsenal and finding it's "side", "faction >> side" or "xla_arsenal_side" (in inverse order of precedence) attribute.

Possible values for these are east/west/indep/civillian/neutral/enemy/friendly/logic or "no side". More accurately the possible values are the interal integer equivalents of these sides.

While east/west/indep and civillian should be fairly straight foward, the other might require some explanation.

"friendly" (the side that 'captives' are assigned to) is used for items that are common to all 'real' sides. (e.g. compass, map, etc).

"enemy" could (but isn't currently) be used to represent items not used by any of the 'real' sides. "neutral" and "logic" are not used in this mod but nothing is stopping you or mod authors from defining things onto these sides.

Sides can be black/whitelisted like normal equipment items. Instead of their names, you'll have to pass them in as numbers (enclosed as a string).

E.g. to allow all "west" and "common"/"friendly" side equipment in "ammo_crate" (globally, without adding arsenal addaction):

//Example for "west" and "common"/"friendly" equipment:
[ammo_crate,["1","6"],true,false] call xla_fnc_addVirtualSideCargo; 

name	value
no side	-1
east	0
west	1
independent	2
civillian	3
neutral	4
enemy	5
friendly	6
logic	7

The side-based "allow/deny" decision is always overruled by individual classname whitelist/blacklist.

// Pseudo code, example where "item" is of type weapon
// Not actual implementation. Uses fake commands like 'getSide' which don't work on classnames
_item_side_decision = ( (getSide _item) in SIDE_CARGO || "%ALL" in SIDE_CARGO) && !( (getSide _item) in SIDE_BLACKLIST || "%ALL" in SIDE_BLACKLIST);
_item_decision = if (_item_side_decision) then { !( (_item in WEAPON_BLACKLIST) || ("%ALL" in WEAPON_BLACKLIST)) } else {  (_item in WEAPON_CARGO) || ("%ALL" in WEAPON_CARGO) };

Note that in all versions up to and including v2.0.2 the check for "%ALL" is only present in the SIDE_CARGO/SIDE_BLACKLIST conditions but mission from the _item_decision.

Warning: "Side"-system and mods

Since not many equipment items have these set by default the mod adds "xla_arsenal_side" attributes to most of the vanilla equipment. Mods that aren't specifically designed to work with this system will usually have no such attributes.

If a modded item inherits from a vanilla item it might end up with an inherited side as well which in many cases will be nonsensical. (I.e. if an RPG launcher from a mod inherits from the NLAW it will inherit the "Blufor" side).

You can use the blacklisting/whitelisting feature to remove/add any items that were wrongly allowed/denied by the "side" system. Alternatively, you can ask mod authors for support of this feature or implement it yourself by creating a compatibility pbo.