Merge pull request #52 from DustinHendrickson/Dustin/DocUpdated

Clarifying how Dynamic Scaling and player weight works

README.md

@@ -79,8 +79,8 @@ BotLevelBrackets.LiteDebugMode               | Enables lite debug logging for th
 BotLevelBrackets.CheckFrequency              | Frequency (in seconds) at which the bot level distribution check is performed.                                                  | 300     | Positive Integer
 BotLevelBrackets.CheckFlaggedFrequency       | Frequency (in seconds) at which the bot level reset is performed for flagged bots that initially failed safety checks.             | 15      | Positive Integer
 BotLevelBrackets.FlaggedProcessLimit         | Maximum number of flagged bots to process per pending level change step.                                                           | 5       | Positive Integer
-BotLevelBrackets.Dynamic.UseDynamicDistribution      | Enables dynamic recalculation of bot distribution percentages based on non-bot player counts per bracket.                        | 0       | 0 (off) / 1 (on)
+BotLevelBrackets.Dynamic.UseDynamicDistribution | Enables dynamic bot distribution: when on, brackets with more real players get a higher share of bots, based on the weight below. | 0 | 0 (off) / 1 (on)
-BotLevelBrackets.Dynamic.RealPlayerWeight            | Multiplier applied to each real player's contribution (active only if dynamic distribution is enabled).                          | 1.0     | Floating point number
+BotLevelBrackets.Dynamic.RealPlayerWeight | Controls how much bots "follow" real player activity when dynamic distribution is enabled. 0.0 = bots always spread evenly; 1.0 = mild effect; higher values = more bots go where players are, but the effect is scaled. | 1.0 | ≥ 0.0 (float)
 BotLevelBrackets.Dynamic.SyncFactions      | Enables synchronized brackets and weighting between Alliance and Horde factions when Dynamic Distribution is also enabled.                        | 0       | 0 (off) / 1 (on)
 BotLevelBrackets.IgnoreFriendListed           | Ignores bots that are on real players' friend lists from any bracket calculations.                                              | 1       | 0 (off) / 1 (on)
 BotLevelBrackets.IgnoreGuildBotsWithRealPlayers | Excludes bots in a guild with at least one real (non-bot) player online from adjustments.                                       | 1       | 0 (disabled) / 1 (enabled)

conf/mod_player_bot_level_brackets.conf.dist

@@ -82,11 +82,23 @@ BotLevelBrackets.NumRanges = 9
 #                     Valid values: 0 (off) / 1 (on)
 BotLevelBrackets.Dynamic.UseDynamicDistribution = 0
 
-#
 #    BotLevelBrackets.Dynamic.RealPlayerWeight
-#        Description: A multiplier applied to each real player's contribution in their level bracket.
+#        Description: This setting controls how much extra weight is given to brackets (level ranges) that contain real (non-bot) players, when dynamic distribution is enabled.
-#                     When combined with inverse scaling by total player count, a higher value significantly boosts the effective weight
+#                     The higher you set this value, the more bots will move to the same level brackets where real players are found, but the effect is *gentle*, not extreme.
-#                     of a real player when few are online.
+#                     A value of 0.0 means bots always distribute evenly across all brackets, regardless of where players are. The default value of 1.0 gives a mild, balanced effect.
+#                     Raising this to 3.0, 5.0, or higher will make bots concentrate more in brackets with real players.
+#                     The value is a multiplier (not a percent): 0.0 = no extra effect, 1.0 = default, 3.0 = stronger, 5.0 = strong but not extreme.
+#                     Experiment based on your total bot count and real player counts to find a good number for your server.
+#                     If you want a large congestion of bots in your level bracket for solo play I recommend 10-15 for RealPlayerWeight.
+#        What to expect:
+#          - With 1.0 (default): If 6/10 real players are in one bracket, that bracket gets about 12.77% of bots. All-empty brackets get about 10.69% each.
+#          - With 3.0: Same scenario: bracket gets about 15.73% of bots. All-empty brackets: 9.93% each.
+#          - With 5.0: Bracket with 6/10 real players gets 18.31%. All-empty brackets: 9.28% each.
+#          - If all real players are in one bracket and weight is 5.0, that bracket gets about 21.56% of bots (others: 9.80% each).
+#          - With 0.0: Every bracket always gets the same number of bots (e.g., 11.11% each for 9 brackets).
+#        Formula (per bracket):
+#          bracket_weight = 1.0 + (RealPlayerWeight × (1 / TotalRealPlayers) × log(1 + RealPlayersInBracket))
+#          All bracket weights are normalized to total 100%.
 #        Default:      1.0
 BotLevelBrackets.Dynamic.RealPlayerWeight = 1.0