CBA Settings System

1. How to use already existing settings?
   1.1. Client Settings
   1.2. Mission Settings
   1.3. Server Settings
   1.4. Setting Overwrite Cheat Sheet
   1.5. Userconfig
   1.6. Export and Import Function
   1.7. Add Settings File To Mission Without CBA
   1.8. Presets System
   1.9. Access Whitelist

2. Create a custom setting for mission or mod
   2.1. Creating a setting
   2.2. Arguments of CBA_fnc_addSetting
       2.2.1. Supported setting types
       2.2.2. Setting type specific arguments
       2.2.3. Global and local settings
       2.2.4. Setting changed script
   2.3. Example - Custom view distance slider

How to use already existing settings?

Client Settings

Settings can be changed in the ingame settings menu as seen above. The settings menu can be accessed from the pause menu during a mission (ESC → OPTIONS → GAME → CONFIGURE ADDONS), from the briefing screen (CONFIGURE ADDONS-Button) or in the Eden-Editor (Settings → Addon Options... shortcut: Ctrl + Alt + S).
If a settings value is changed, it will be stored in the profile. The changed value will also be applied the next time the setting is initialized (e.g. next mission start), even when the game was closed.

Mission Settings

All settings can be stored in a mission (mission.sqm). Mission makers can change the mission settings in the Eden-Editor by selecting the Mission tab.
Mission settings have no influence on the players by default. This is indicated by a red exclamation mark ❗. They can however be set to overwrite all clients playing the mission by clicking the Overwrite Clients checkbox.
Instead of changing the settings using the ingame settings menu, the mission maker can export all settings using the export funtion (described below) and paste them into the optional cba_settings.sqf file in the missions main folder. Settings that are defined using this method cannot be changed in the ingame settings menu.

Server Settings

The settings of the server are broadcasted to all clients. The server can be a local host or a dedicated server. To change the settings of a dedicated server, log in as admin and select the Server tab.
The servers settings only apply to the server machine and have no influence on the clients by default. They can however be set to overwrite the clients settings by clicking the Overwrite Clients checkbox.
If a mission setting is set to overwrite the clients, it also overwrites the server by default. This can be changed by clicking the Overwrite Mission checkbox.
In single-player mode, the players machine is the server and has therefore the option to overwrite the mission settings.

Setting Overwrite Cheat Sheet

On Server No Force:
    On Mission No Force:
        Client > Mission > Server
    On Mission Force:
        Mission > Client > Server

On Server 1 Force:
    On Mission No Force:
        Server > Client > Mission
    On Mission Force:
        Mission > Server > Client

On Server 2 Force:
    Server > All

Userconfig

Settings can be exported using the export function (described below) and be pasted into an optional file in the userconfig folder. The filepath is Arma 3\userconfig\cba_settings.sqf, where "Arma 3" is the games installation folder.
This works for a dedicated server as well as the clients, but requires the -filePatching startup parameter.
Alternatively one can use Addon Builder to create a PBO that contains the userconfig settings file. The addon is called cba_settings_userconfig and can be found in the template folder. An empty cba_settings.sqf is already placed inside. The binarized PBO could be placed inside the @CBA_A3\addons\ folder or a custom addon could be created (and could also be uploaded to the Steam Workshop etc.). This method does not require file patching to be enabled.

Userconfig limitations

• Settings defined in the userconfig cannot be changed in the ingame settings menu.
• (v3.15.8 or earlier) Setting values in the userconfig cannot be multiline (arrays must be defined in single line etc.)

Export and Import Function

Settings can be exported to the clipboard and imported from the clipboard using the ingame settings menu in a format that can be stored in any type of text file.
The exported settings can be pasted into the various cba_settings.sqf files described above.
Note that the Import and Export functions might not be available in multiplayer, because Arma disables the clipboard for security reasons.

Add Settings File To Mission Without CBA

requires 3.5
The cba_settings.sqf file of a mission is ignored by default. If the file is present when the mission is saved in the editor, a flag will be set and enable the mission to read the file. This only works if CBA is present when the mission is saved. To avoid creating a dependency, the mission maker can manually add the flag to the description.ext:

cba_settings_hasSettingsFile = 1;

Note that this will crash the mission on a dedicated server if the file is not present in the mission.

Presets System

The ingame settings menu can save whole presets of settings. These presets can be used to quickly transfer settings from the client to the server or the mission and vice versa.
The presets of the last three missions you played and of the last three servers you played on will be "autosaved".
Presets can be selected during the briefing. The admin can also change the servers preset (or change any individual setting).

Access Whitelist

requires 3.7
You can limit who can edit the settings on the Server tab by addon or description.ext.
See: https://github.com/CBATeam/CBA_A3/pull/892

---

Create a custom setting for mission or mod

Creating a setting

All settings are created with CBA_fnc_addSetting. The function can be used anywhere and has local effects . The function has to be executed on every machine.
It is recommended to execute the function via a CBA XEH preInit event. This way you can make sure that the setting is available in the Eden-Editor.
Settings have a name and a value. The name is unique and will be the resulting global variable that can be used in scripts. Since it's a global variable, it must contain a tag.
The possible values a setting can take depend on the type of the setting.

Arguments of CBA_fnc_addSetting

Parameters:
    _setting     - Unique setting name. Matches resulting variable name <STRING>
    _settingType - Type of setting. Can be "CHECKBOX", "EDITBOX", "LIST", "SLIDER", "COLOR" or "TIME" <STRING>
    _title       - Display name or display name + tooltip (optional, default: same as setting name) <STRING, ARRAY>
    _category    - Category for the settings menu + optional sub-category <STRING, ARRAY>
    _valueInfo   - Extra properties of the setting depending of _settingType. See examples below <ANY>
    _isGlobal    - 1: all clients share the same setting, 2: setting can't be overwritten (optional, default: 0) <NUMBER>
    _script      - Script to execute when setting is changed. (optional) <CODE>
    _needRestart - Setting will be marked as needing mission restart after being changed. (optional, default false) <BOOL>

Supported setting types (_settingType)

Currently six different setting "types" are supported:

• CHECKBOX: A checkbox. The resulting settings value is a boolean.
• EDITBOX: A string type setting that players can type.
• SLIDER: Resulting settings value is a number between a min and a max value. (e.g. view distance slider)
• LIST: A dropdown list. Resulting value can be anything, but only one item can be selected at any time.
• COLOR: Will create a "color picker" setting. The value will be an array representing a color.
• TIME: Similar to a slider, but allows input in the HH:MM:SS format and returns the corresponding value in seconds. The array size can be 3 or 4, depending on the passed default value. The fourth element will represent the opacity ("alpha value").

Optional Sub-Category

Setting type specific arguments (_valueInfo)

CHECKBOX:

• Default value <BOOLEAN>

EDITBOX:

• Default value <STRING>

SLIDER:

• 0: Minimum (lowest possible value) <NUMBER>
• 1: Maximum (highest possible value) <NUMBER>
• 2: Default value <NUMBER>
• 3: Number of displayed trailing decimals (should be 0, 1 or 2) <NUMBER>
• 4: Percentage display <BOOL>
  Example: [1, 25, 5, 2] (value), [0, 1, 0.5, 2, true] (percentage)

LIST:

• 0: Values this setting can take. <ARRAY>
• 1: Corresponding pretty names for the ingame settings menu. Can be stringtable entries. <ARRAY>
• 2: Index of the default value. Not the default value itself. <NUMBER>
  Example: [[false, true], ["STR_A3_OPTIONS_DISABLED", "STR_A3_OPTIONS_ENABLED"], 0]

COLOR:

• Default color. Array size can be 3 or 4, depending on whether the setting uses the alpha value. <ARRAY>
  Example: [1,0,0] (red), [1,1,0,0.5] (semi transparent yellow)

TIME:

• 0: Minimum (lowest possible value) <NUMBER>
• 1: Maximum (highest possible value) <NUMBER>
• 2: Default value <NUMBER>

Global and local settings (_isGlobal)

A setting can be changed on all machines by default. Sometimes you want a specific setting to be the same on all machines. By setting _isGlobal to true or 1, the setting will always overwrite the clients and is therefore the same on all connected machines.
By setting _isGlobal to 2, the setting can be made to never overwrite the clients. Those settings cannot be set to overwrite by the mission or the server. It is not advised to use this.

Setting changed script (_script)

This is a optional script that will be executed every time the setting is changed. The new value of the setting will be passed in the _this variable.
Alternatively it's possible to add a CBA eventhandler that will fire when any setting is changed. The name of the setting and the new value will be passed in the _this variable:

["CBA_SettingChanged", {
    params ["_setting", "_value"];
    systemChat format ["%1 = %2", _setting, _value];
}] call CBA_fnc_addEventHandler;

Setting requires mission restart (_needRestart)

Optional flag to mark a setting that only takes updated effect after a mission restart. Will display a marker in the settings menu.

Example - Custom view distance slider

Files in the mission folder:

description.ext with CBA preInit eventhandler. This can be used identically for addons in a config.cpp.

The preInit eventhandler creating the setting for the mission or addon:

[
    "Commy_ViewDistance", // Internal setting name, should always contain a tag! This will be the global variable which takes the value of the setting.
    "SLIDER", // setting type
    "View Distance", // Pretty name shown inside the ingame settings menu. Can be stringtable entry.
    "My Mission Settings", // Pretty name of the category where the setting can be found. Can be stringtable entry.
    [200, 15000, 5000, 0], // data for this setting: [min, max, default, number of shown trailing decimals]
    nil, // "_isGlobal" flag. Set this to true to always have this setting synchronized between all clients in multiplayer
    {  
        params ["_value"];
        setViewDistance _value;
    } // function that will be executed once on mission start and every time the setting is changed.
] call CBA_fnc_addSetting;