How to update and maintain CBA Settings Lock

Why

Mods can change their CBA settings between releases - add new, remove old, rename existing or even change the data type associated with a setting (ie. 0 to false). If we don't update our enforced settings, our values will simply be silently discarded and mod defaults will be used instead. As such, it's critical that we always update the settings to match current mod versions.

Additionally, it's useful to know when mods change their defaults without changing setting data type - ie. by interpreting a numerical coefficient differently in a newer (mod) version. This is usually represented by the mod changing its defaults, which we can catch by storing and comparing against a settings file containing just the default values.

Therefore, when performing any mod update that could introduce CBA setting changes (eg. virtually every mod update except for custom hotfixes), perform all of the following steps, in this order.

1. Verify that existing settings are correct

1. Clone the current cba-settings-lock repository (or update existing)
2. Start up the game using the old modset
3. Go into Editor, place any soldier unit, start singleplayer preview*
4. Hit Escape --> OPTIONS --> ADDON OPTIONS
5. Switch to SERVER and SAVE your current settings as ie. "mine"
6. Alt-tab, open up cba_settings.sqf, select all, copy
7. Alt-tab back, press IMPORT and paste the contents into the textbox, hit OK
8. Press EXPORT, make sure the top-right "Show default values" checkbox is enabled, copy/paste the contents back to cba_settings.sqf, overwriting anything that was in the file
9. Check that your git tooling (Github Desktop or other) shows no changes
   • If any changes are shown, this indicates problems, ie.
     1. Typo was made while making manual changes to cba_settings.sqf
     2. Invalid setting value was specified while making manual changes
     3. Settings were not updated after a previous mod update
     4. etc.
   • Commit and push the current state now, separately from later steps, do not make any changes
   • Resolve the change according to your best judgement (see step 18 for tips)
     • If any adjustments were needed, commit and push them now, with commit message describing the changes
   • After the commit, do the copy/pasting to-and-from game (steps 6-9) again, verify that no changes show anymore

2. Update settings to new mod versions

10. Update the modset with new mod versions / new mods / removed mods
11. Start up the game using the new modset
12. Go into Editor, place any soldier unit, start singleplayer preview*
13. Hit Escape --> OPTIONS --> ADDON OPTIONS
14. Alt-tab, open up cba_settings.sqf, select all, copy
15. Alt-tab back, press IMPORT and paste the contents into the textbox, hit OK
16. Press EXPORT, make sure the top-right "Show default values" checkbox is enabled, copy/paste the contents back to cba_settings.sqf, owerwriting anything that was in the file
17. Check diff in your git tooling (Github Desktop or other), resolve any changes
    • If there are no changes, skip to step 21
18. If changes are shown, resolve them per your best judgement
    • For new settings, set some sensible values and enforcement (none, force, force force)
    • For removed settings, just leave them removed
    • Settings which changed data type (ie. = 1; instead of = true;) resolve manually in the CBA Settings UI
      • Drop-down menus will show the raw value on mouse over the expanded items
      • Other data types are kind of self-explanatory
19. Select all in your modified cba_settings.sqf, copy, alt-tab into the game, IMPORT, paste, OK, EXPORT, select all, paste back into cba_settings.sqf
    • This passes the settings through the CBA framework internals, ensuring your hand-edits didn't break the syntax and provided valid values
    • Additionally, view the IMPORTed changes in CBA Settings UI ingame to triple-check (that correct dropdown value was selected, etc.)
20. Review the changes in git diff, don't commit yet

3. Update mod defaults

21. Alt-tab back to game, close the export textbox and options dialog (CANCEL or OK), returning back to the Escape menu
22. Paste the following into the big window (debug console), press LOCAL EXEC
    • { [_x, [_x, "default"] call CBA_settings_fnc_get, nil, "server"] call CBA_settings_fnc_set } forEach allVariables CBA_settings_server;
    • This will re-set the SERVER settings to defaults (CBA has no global button, unfortunately)
23. Go back to OPTIONS --> ADDON OPTIONS, switch to SERVER
24. Press EXPORT, ensure the "Show default values" checkbox is enabled
    • As a test, un-check / re-check the checkbox - the export window should be empty when un-checked, indicating defaults are loaded
25. Select all, copy, open up defaults.sqf, select all, paste (overwriting any previous content), save & close
    • Never make any other hand-edits to defaults.sqf
26. Now commit & push changes (for both files)
27. Go back ingame and restore your old client-side settings by LOADing "mine" (or whatever you named it), confirm OK