Add some documentation to default balance config files

Explained how non-default ones work in conjunction with the default balance files.
Provided some examples to make it easier to understand.
Updated the dumpweapons command so it adds the documentation comments to the top of the file.

diff --git a/bal-wep-xonotic.cfg b/bal-wep-xonotic.cfg
index 347dc420d2c7e1fc9fa88c30b891920861ef7a5f..a84f54d808236d805d910162ec64597765c8743b 100644 (file)
--- a/bal-wep-xonotic.cfg
+++ b/bal-wep-xonotic.cfg
@@ -1,3 +1,27 @@
+// ************************************************************************************ //
+// **                 WARNING - MANUALLY EDIT THIS FILE WITH CAUTION                 ** //
+// **                                                                                ** //
+// **  This file can be automatically generated with the command 'dumpweapons'.      ** //
+// **  This is useful to create custom weapon balance configs, after changing some   ** //
+// **  weapon balance cvars in-game.                                                 ** //
+// **  If you are creating a custom weapon balance config file, delete this.         ** //
+// **                                                                                ** //
+// **  If you are just editing the default weapon balance (bal-wep-xonotic.cfg),     ** //
+// **  please keep this comment as it contains helpful documentation.                ** //
+// **                                                                                ** //
+// **  These are the default weapon-related balance config settings, categorized by  ** //
+// **  weapon.                                                                       ** //
+// **  Other default settings are in balance-xonotic.cfg, which executes this file.  ** //
+// **  Other wep balance configs like bal-wep-nexuiz25.cfg first execute this, then  ** //
+// **  override some settings.                                                       ** //
+// **  Therefore any changes made to the default balance here will affect all        ** //
+// **  bal-wep-*.cfg files, unless you override it in such files.                    ** //
+// **                                                                                ** //
+// **  If you add a new weapon cvar, remove a weapon cvar, or rename a weapon cvar,  ** //
+// **  please regenerate this file with that command, or manually add it here.       ** //
+// **                                                                                ** //
+// ************************************************************************************ //
+
 // {{{ #1: Blaster
 set g_balance_blaster_primary_animtime 0.2
 set g_balance_blaster_primary_damage 20

diff --git a/balance-xonotic.cfg b/balance-xonotic.cfg
index 858a8a4f4fa7df6da6aedb5c3ec1083116e513c8..4664f3bed4bde79a812a8cbd9445ea382fdc2148 100644 (file)
--- a/balance-xonotic.cfg
+++ b/balance-xonotic.cfg
@@ -1,3 +1,21 @@
+// ******************************************************************************************** //
+// **                     WARNING - MANUALLY EDIT THIS FILE WITH CAUTION                     ** //
+// **                                                                                        ** //
+// **  These are the default balance config settings, excluding weapon-related settings,     ** //
+// **  which are instead in bal-wep-xonotic.cfg.                                             ** //
+// **  Therefore any edits to this file will affect default gameplay.                        ** //
+// **                                                                                        ** //
+// **  Other balance configs like balance-overkill.cfg first execute this, then override     ** //
+// **  some settings.                                                                        ** //
+// **  Therefore any changes made to the default balance here will affect all balance-*.cfg  ** //
+// **  files, unless you override it in such files.                                          ** //
+// **  Generally balance config files execute their wep balance config file, if one exists.  ** //
+// **  The name of the current balance set is stored in g_mod_balance, which is read by      ** //
+// **  some parts of the code, e.g. the Overkill mutator can only be enabled if              ** //
+// **  g_mod_balance is Overkill.                                                            ** //
+// **                                                                                        ** //
+// ******************************************************************************************** //
+
 g_mod_balance Xonotic
 testing_disable
 

diff --git a/qcsrc/common/weapons/config.qc b/qcsrc/common/weapons/config.qc
index 596540dd3940c64fe04eb22dfaaa98bf097e3ce1..1891f6c59f5ba18ce07699cbf16507c2d52c979d 100644 (file)
--- a/qcsrc/common/weapons/config.qc
+++ b/qcsrc/common/weapons/config.qc
@@ -34,6 +34,33 @@ void Dump_Weapon_Settings()
        int totalweapons = 0, totalsettings = 0;
        int wepcount = 1;
        #define WEP_CONFIG_WRITETOFILE(str) write_String_To_File(wep_config_file, str, wep_config_alsoprint)
+
+       WEP_CONFIG_WRITETOFILE(
+               "// ************************************************************************************ //\n"
+               "// **                 WARNING - MANUALLY EDIT THIS FILE WITH CAUTION                 ** //\n"
+               "// **                                                                                ** //\n"
+               "// **  This file can be automatically generated with the command 'dumpweapons'.      ** //\n"
+               "// **  This is useful to create custom weapon balance configs, after changing some   ** //\n"
+               "// **  weapon balance cvars in-game.                                                 ** //\n"
+               "// **  If you are creating a custom weapon balance config file, delete this.         ** //\n"
+               "// **                                                                                ** //\n"
+               "// **  If you are just editing the default weapon balance (bal-wep-xonotic.cfg),     ** //\n"
+               "// **  please keep this comment as it contains helpful documentation.                ** //\n"
+               "// **                                                                                ** //\n"
+               "// **  These are the default weapon-related balance config settings, categorized by  ** //\n"
+               "// **  weapon.                                                                       ** //\n"
+               "// **  Other default settings are in balance-xonotic.cfg, which executes this file.  ** //\n"
+               "// **  Other wep balance configs like bal-wep-nexuiz25.cfg first execute this, then  ** //\n"
+               "// **  override some settings.                                                       ** //\n"
+               "// **  Therefore any changes made to the default balance here will affect all        ** //\n"
+               "// **  bal-wep-*.cfg files, unless you override it in such files.                    ** //\n"
+               "// **                                                                                ** //\n"
+               "// **  If you add a new weapon cvar, remove a weapon cvar, or rename a weapon cvar,  ** //\n"
+               "// **  please regenerate this file with that command, or manually add it here.       ** //\n"
+               "// **                                                                                ** //\n"
+               "// ************************************************************************************ //\n"
+               "\n");
+
        FOREACH(Weapons, it != WEP_Null, {
                if(it.spawnflags & WEP_FLAG_SPECIALATTACK)
                        continue; // never include the attacks