Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation - Rework arsenal docs #8650

Merged
merged 2 commits into from
Nov 11, 2021
Merged

Documentation - Rework arsenal docs #8650

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ed48c3f
Rework arsenal docs
BaerMitUmlaut Oct 29, 2021
e91f7d7
Undo page rename
BaerMitUmlaut Oct 31, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
255 changes: 114 additions & 141 deletions docs/wiki/framework/arsenal-framework.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,124 +17,118 @@ version:
<p>Units and objects that can have ACE Arsenal added to them will be called "Boxes" in this documentation.</p>
</div>

```cpp
// To quickly add a full ACE Arsenal to a box for all clients
To quickly add a full ACE Arsenal to a box for all clients use the following code:

```sqf
[_box, true] call ace_arsenal_fnc_initBox;
```

`_box` being the object you wish to add ACE Arsenal to. (or `this` when called from the box's init field)

## 1. Virtual items
`_box` being the object you wish to add ACE Arsenal to (or `this` when called from the box's init field).

### 1.1 Adding virtual items

`ace_arsenal_fnc_addVirtualItems`
```cpp
* Arguments:
* 0: Box <OBJECT>
* 1: Items <ARRAY of strings> or <BOOL>
* 2: Add globally <BOOL> (optional)
```
## 1. Access to ACE Arsenal

Passing an array of strings (class names) will add each one of those items to the specified box, passing true will add ALL items that are compatible with ACE Arsenal (the sorting is done on game startup).
### 1.1 Adding ACE Arsenal to a box

Examples:
- `[_box, ["item1", "item2", "itemN"]] call ace_arsenal_fnc_addVirtualItems`
- `[_box, true, false] call ace_arsenal_fnc_addVirtualItems`
`ace_arsenal_fnc_initBox`

### 1.2 Removing virtual items
| | Argument | Type | Optional (default value)
---| -------- | ---- | ------------------------
0 | Box | Object | Required
1 | Items | Array of strings or boolean | Required
2 | Initialize globally | Boolean | Optional (default: `false`)

```cpp
* 0: Box <OBJECT>
* 1: Items <ARRAY of strings> <BOOL>
* 2: Add globally <BOOL> (optional)
```

Like adding virtual items, passing an array of string (class names) will remove each ones of those items, however passing true will remove all virtual items and also remove the interaction to access ACE Arsenal.
This will add the virtual items passed as arguments and add an ACE interaction to open ACE Arsenal.

Examples:
- `[_box, ["item1", "item2", "itemN"]] call ace_arsenal_fnc_removeVirtualItems`
- `[_box, true, false] call ace_arsenal_fnc_removeVirtualItems`
- `[_box, ["MyItem1", "MyItem2", "MyItemN"]] call ace_arsenal_fnc_initBox`
- `[_box, true] call ace_arsenal_fnc_initBox`
- `[_box, false, false] call ace_arsenal_fnc_initBox`

### 1.3 Arsenal only with items from default loadouts (See section 4)
Passing an empty array or `false` will still add an interaction but no additional virtual items will be added.
Please note that at least one virtual item needs to be added otherwise ACE Arsenal will not open.

```cpp
* 0: Box <OBJECT>
* 1: Items <ARRAY of strings> <BOOL>
* 2: Add globally <BOOL> (optional)
```
### 1.2 Opening an arsenal box manually

Built upon the function of section 1.1, this can be used to make an Arsenal only with the items from your precreated loadouts. This is the best choice if you do not want to make a full arsenal available to have your Loadouts spawnable.
`ace_arsenal_fnc_openBox`

```cpp
I. Spawn the same amount of units as you have loadouts, give each unit one of them
II. Start the mission then press ESC once loaded
III. Clear the debug console then enter the following:
| | Argument | Type | Optional (default value)
---| -------- | ---- | ------------------------
0 | Box | Object | Required
1 | Unit to open ACE Arsenal on | Object | Required
2 | Ignore virtual items and fill ACE Arsenal | Boolean | Optional (default: `false`)

Examples:
- `[_box, player] call ace_arsenal_fnc_openBox`
- `[player, player, true] call ace_arsenal_fnc_openBox`

private _items = allUnits apply {getUnitLoadout _x};
_items = str _items splitString "[]," joinString ",";
_items = parseSimpleArray ("[" + _items + "]");
_items = _items arrayIntersect _items select {_x isEqualType "" && {_x != ""}};
copyToClipboard str _items;
In the second example a full ACE Arsenal will be opened on the player.

IV. Paste the created array from your clipboard into the space where the items are listed CTRL+V. The array is created with brackets.
```
### 1.3 Removing the ACE Arsenal interaction

Examples:
`ace_arsenal_fnc_removeBox`

For a new Box: - `[_box, ["item1", "item2", "itemN"]] call ace_arsenal_fnc_initBox`
| | Argument | Type | Optional (default value)
---| -------- | ---- | ------------------------
0 | Box | Object | Required
2 | Remove globally | Boolean | Optional (default: `false`)

For an existing Box: - `[_box, ["item1", "item2", "itemN"]] call ace_arsenal_fnc_addVirtualItems`
Example:
`[_box, true] call ace_arsenal_fnc_removeBox`

## 2. Access to ACE Arsenal
## 2. Virtual items

### 2.1 Adding ACE Arsenal to a box
### 2.1 Adding virtual items

`ace_arsenal_fnc_initBox`
```cpp
* 0: Box <OBJECT>
* 1: Items <BOOL> or <ARRAY>
* 2: Initialize globally <BOOL> (optional)
```
`ace_arsenal_fnc_addVirtualItems`

This will add the virtual items passed as arguments and add an ACE interaction to open ACE Arsenal.
| | Argument | Type | Optional (default value)
---| -------- | ---- | ------------------------
0 | Box | Object | Required
1 | Items | Array of strings or boolean | Required
2 | Add globally | Boolean | Optional (default: `false`)

Passing an array of strings (class names) will add each one of those items to the specified box, passing true will add ALL items that are compatible with ACE Arsenal (the sorting is done on game startup).

Examples:
- `[_box, ["MyItem1", "MyItem2", "MyItemN"]] call ace_arsenal_fnc_initBox`
- `[_box, true] call ace_arsenal_fnc_initBox`
- `[_box, false, false] call ace_arsenal_fnc_initBox`
- `[_box, ["item1", "item2", "itemN"]] call ace_arsenal_fnc_addVirtualItems`
- `[_box, true, false] call ace_arsenal_fnc_addVirtualItems`

Passing an empty array or `false` will still add an interaction but no additional virtual items will be added.
Please note that at least one virtual item needs to be added otherwise ACE Arsenal will not open.
### 2.2 Removing virtual items

if you wish to open a full ACE Arsenal on yourself or open ACE Arsenal via a custom action you can use `ace_arsenal_fnc_openBox`.
`ace_arsenal_fnc_removeVirtualItems`

`ace_arsenal_fnc_openBox`
```cpp
* 0: Box <OBJECT>
* 1: Unit to open ACE Arsenal on <OBJECT>
* 2: Ignore virtual items and fill ACE Arsenal <BOOL> (optional)
```
| | Argument | Type | Optional (default value)
---| -------- | ---- | ------------------------
0 | Box | Object | Required
1 | Items | Array of strings or boolean | Required
2 | Remove globally | Boolean | Optional (default: `false`)

Like adding virtual items, passing an array of string (class names) will remove each ones of those items, however passing true will remove all virtual items and also remove the interaction to access ACE Arsenal.

Examples:
- `[_box, player] call ace_arsenal_fnc_openBox`
- `[player, player, true] call ace_arsenal_fnc_openBox`
- `[_box, ["item1", "item2", "itemN"]] call ace_arsenal_fnc_removeVirtualItems`
- `[_box, true, false] call ace_arsenal_fnc_removeVirtualItems`

In the second example a full ACE Arsenal will be opened on the player.
### 2.3 Arsenal only with items from default loadouts (See section 4)

### 2.2 Removing the ACE Arsenal interaction
Built upon the function of section 2.1, this can be used to make an Arsenal only with the items from your precreated loadouts. This is the best choice if you do not want to make a full arsenal available to have your loadouts spawnable.

In order to remove the ACE interaction added by `ace_arsenal_fnc_initBox` you need to either use `ace_arsenal_fnc_removeBox` or remove all virtual items, since we saw how to [remove all virtual items](#12-removing-virtual-items) above we'll be focusing on `ace_arsenal_fnc_removeBox`.
1. Spawn the same amount of units as you have loadouts, give each unit one of them
2. Start the mission then press ESC once loaded
3. Clear the debug console then enter the following:
```sqf
private _items = flatten (allUnits apply {getUnitLoadout _x});
_items = _items arrayIntersect _items select {_x isEqualType "" && {_x != ""}};
copyToClipboard str _items;
```

`ace_arsenal_fnc_removeBox`
```cpp
* 0: Box <OBJECT>
* 1: Remove globally <BOOL> (optional)
```
4. Paste the created array from your clipboard into the space where the items are listed using <kbd>Ctrl</kbd> + <kbd>V</kbd>. The array is created with brackets.

Example:
`[_box, true] call ace_arsenal_fnc_removeBox`
Examples:
- For a new box:
`[_box, ["item1", "item2", "itemN"]] call ace_arsenal_fnc_initBox`
- For an existing box:
`[_box, ["item1", "item2", "itemN"]] call ace_arsenal_fnc_addVirtualItems`

## 3. Config entries

Expand All @@ -156,15 +150,16 @@ To do so:
- Click on the "Default Loadouts" tab.
- Enter a loadout name and save.

This loadout list can be exported to the clipboard by using <kbd>Shift</kbd>. + <kbd>LMB</kbd>. on the export button, doing the same on the import button will import the list currently in the clipboard.
This loadout list can be exported to the clipboard by using <kbd>Shift</kbd> + <kbd>LMB</kbd>. on the export button, doing the same on the import button will import the list currently in the clipboard.

### 4.2 Adding default loadouts via script

Since 3.13.0, you can also add default loadouts with the `ace_arsenal_fnc_addDefaultLoadout` function.
```cpp
* 0: Name of loadout <STRING>
* 1: getUnitLoadout array <ARRAY>
```
`ace_arsenal_fnc_addDefaultLoadout`

| | Argument | Type | Optional (default value)
---| -------- | ---- | ------------------------
0 | Name of loadout | String | Required
1 | getUnitLoadout array | Array | Required

Example:
`["Squad Leader", getUnitLoadout sql1] call ace_arsenal_fnc_addDefaultLoadout`
Expand Down Expand Up @@ -202,48 +197,44 @@ The arguments passed to the bar, text and condition statements are:

### 5.2 Adding stats via a function

To add a stat simply call `ace_arsenal_fnc_addStat`
```cpp
/*
* Author: Alganthe
* Add a stat to ACE Arsenal.
*
* Arguments:
* 0: Tabs to add the stat to (ARRAY of ARRAYS)
* 0.1: Left tab indexes (ARRAY of NUMBERS)
* 0.2 Right tab indexes (ARRAY of NUMBERS)
* 1: Stat class (STRING) (A unique string for each stat)
* 2: Config entries to pass (ARRAY of STRINGS)
* 3: Title (STRING)
* 4: Show bar / show text bools (ARRAY of BOOLS)
* 4.1 Show bar (BOOL)
* 4.2 Show text (BOOL)
* 5: Array of statements (ARRAY of ARRAYS)
* 5.1: Bar code (CODE)
* 5.2 Text code (CODE)
* 5.3 Condition code (CODE)
* 6: Priority (NUMBER) (Optional)
*
* Return Value:
* 0: Array of IDs (ARRAY of STRINGS)
*
* Example:
* [[[0,1,2], [7]], "scopeStat", ["scope"], "Scope", [false, true], [{}, {
params ["_statsArray", "_itemCfg"];
getNumber (_itemCfg >> _statsArray select 0)
}, {true}]] call ACE_arsenal_fnc_addStat
*
* Public: Yes
*/
`ace_arsenal_fnc_addStat`

| | Argument | Type | Optional (default value)
--- | -------- | ---- | ------------------------
0 | Tabs to add the stat to | Array of arrays | Required
0.1 | Left tab indexes | Array of numbers | Required
0.2 | Right tab indexes | Array of numbers | Required
1 | Stat class ID | String | Required
2 | Config entries to pass | Array of strings | Required
3 | Title | String | Required
4 | Show bar / show text bools | Array of booleans | Required
4.1 | Show bar | Boolean | Required
4.2 | Show text | Boolean | Required
5 | Array of statements | Array of arrays | Required
5.1 | Bar code | Code | Required
5.2 | Text code | Code | Required
5.3 | Condition | Code | Required
6 | Priority | Number | Optional (default: `0`)

Example:
```sqf
[[[0,1,2], [7]], "scopeStat", ["scope"], "Scope", [false, true], [{}, {
params ["_statsArray", "_itemCfg"];
getNumber (_itemCfg >> _statsArray select 0)
}, {true}]] call ACE_arsenal_fnc_addStat;
```

### 5.3 Removing stats via a function

Removing a stat is as simple as adding one, call `ace_arsenal_fnc_removeStat`
`ace_arsenal_fnc_removeStat`

| | Argument | Type | Optional (default value)
---| -------- | ---- | ------------------------
0 | Array of IDs | Array | Required

Stats IDs are unique, IDs are generated as follows:

`Class + side + tab`
`Class + side + tab`

For example: `testClassL03`
- Class: `testClass`
Expand All @@ -252,24 +243,6 @@ For example: `testClassL03`

For config added stats the classname is used, for function added ones the string provided is used.

```cpp
/*
* Author: Alganthe
* Remove a stat from ACE Arsenal.
*
* Arguments:
* 0: Array of IDs (ARRAY)
*
* Return Value:
* None
*
* Example:
* [["scopeStatL00","scopeStatL01","scopeStatL02","scopeStatR07"]] call ace_arsenal_fnc_removeStat;
*
* Public: Yes
*/
```

### 5.4 Stat tab numbers

Left tabs:
Expand Down