H3: Balance pass from 200 bot matches (make balance)

make balance (tools/balance.sh, tools/balance.gd, BalanceReport) plays 200
bot-only matches in four processes under nice and reports match length,
players standing over time, causes of death, eliminations by weapon and by
difficulty, judged against the new BALANCE_* targets in Tuning and the
GDD's Balance section.

Before: median match 5.0 min, 3.4 of 24 standing at 2 min, the boathook
41% of eliminations. After, over seeds 1001-1200: median 13.1 min (p10 9.2,
p90 14.6), top weapon the rivet repeater at 31.7%. Passes.

Changes, each traced from single-match runs (docs/BALANCE.md):
- Fix: bots leapt from the barge on a timer and landed hundreds of metres
  short of their spot; they now leap when it's in gliding reach or the
  barge starts drawing away from it.
- Bots spread their landings, only brawl whoever hit them, pick out new
  opponents within 30 m, roam locally and hold ground, run from a gun when
  unarmed, and (normal and hard) break off when badly hurt.
- Aim error widened; rivet repeater damage 17 to 15.
- Tide: lower early levels, longer holds; every match ends within 17.75 min.

Tests: BalanceReport, the new bot behaviours, the tide length. Tests that
leaned on old bot luck now pin or set up what they check. make match moves
to seed 29, where the scripted player still builds.

Closes #56

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-14 06:28:15 -05:00
co-authored by Claude Opus 5.5
parent ffb68a1e89
commit 38812120df
24 changed files with 774 additions and 61 deletions
+121
View File
@@ -0,0 +1,121 @@
## Adds up BotBatch.run_match() results for the balance pass (H3) and judges them
## against the targets in Tuning (BALANCE_*). Shared by tools/balance.gd and its test.
class_name BalanceReport
extends RefCounted
## Minutes at which the report counts who is still standing.
const STANDING_AT_MINUTES: Array[int] = [2, 4, 6, 8, 10, 12, 14]
## The value at fraction `q` (0 to 1) of a sorted list, interpolating between neighbours.
static func quantile(sorted: Array[float], q: float) -> float:
if sorted.is_empty():
return 0.0
var position: float = q * (sorted.size() - 1)
var low: int = floori(position)
var high: int = mini(low + 1, sorted.size() - 1)
return lerpf(sorted[low], sorted[high], position - low)
## Returns {"matches", "minutes": {"p10", "p25", "median", "p75", "p90", "min", "max"},
## "finished", "with_winner", "timed_out", "causes", "deaths", "tide_share",
## "weapon_kills", "weapon_share": {weapon: fraction of weapon eliminations},
## "top_weapon", "top_share", "wins", "eliminations", "mean_place",
## "standing": {minute: mean players standing}, "problems": [String]}.
static func analyse(results: Array[Dictionary]) -> Dictionary:
var minutes: Array[float] = []
var weapon_kills: Dictionary = {}
var standing: Dictionary = {}
for minute: int in STANDING_AT_MINUTES:
standing[minute] = 0.0
for result: Dictionary in results:
minutes.append(float(result["ticks"]) / Tuning.TICK_RATE_HZ / 60.0)
for weapon: String in result.get("weapon_kills", {}):
weapon_kills[weapon] = int(weapon_kills.get(weapon, 0)) + int(result["weapon_kills"][weapon])
var deaths: Array = result.get("death_seconds", [])
var players: int = Tuning.SOLO_PLAYERS
for minute: int in STANDING_AT_MINUTES:
var fallen: int = 0
for at: Variant in deaths:
if float(at) <= minute * 60.0:
fallen += 1
standing[minute] += float(players - fallen)
minutes.sort()
var typed: Array[Dictionary] = results
var total: Dictionary = BotBatch.summarise(typed)
var analysis: Dictionary = {
"matches": results.size(),
"minutes": {
"min": minutes[0] if not minutes.is_empty() else 0.0,
"p10": quantile(minutes, 0.1), "p25": quantile(minutes, 0.25),
"median": quantile(minutes, 0.5), "p75": quantile(minutes, 0.75),
"p90": quantile(minutes, 0.9), "max": minutes[-1] if not minutes.is_empty() else 0.0,
},
"finished": total["finished"], "with_winner": total["with_winner"], "timed_out": total["timed_out"],
"causes": total["causes"], "deaths": total["deaths"],
"tide_share": float(int(total["causes"].get("drown", 0)) + int(total["causes"].get("tide", 0))) / maxi(total["deaths"], 1),
"weapon_kills": weapon_kills, "weapon_share": {}, "top_weapon": "", "top_share": 0.0,
"wins": total["wins"], "eliminations": total["eliminations"], "mean_place": total["mean_place"],
"standing": {}, "problems": [],
}
var weapon_total: int = 0
for weapon: String in weapon_kills:
weapon_total += int(weapon_kills[weapon])
for weapon: String in weapon_kills:
var share: float = float(weapon_kills[weapon]) / maxi(weapon_total, 1)
analysis["weapon_share"][weapon] = share
if share > analysis["top_share"]:
analysis["top_share"] = share
analysis["top_weapon"] = weapon
for minute: int in STANDING_AT_MINUTES:
analysis["standing"][minute] = standing[minute] / maxi(results.size(), 1)
var problems: Array = analysis["problems"]
if results.size() < Tuning.BALANCE_MIN_MATCHES:
problems.append("only %d matches; the pass needs %d" % [results.size(), Tuning.BALANCE_MIN_MATCHES])
if total["finished"] != results.size() or total["with_winner"] != results.size():
problems.append("%d of %d matches finished with a winner" % [total["with_winner"], results.size()])
var median: float = analysis["minutes"]["median"]
if median < Tuning.BALANCE_MEDIAN_MINUTES_MIN or median > Tuning.BALANCE_MEDIAN_MINUTES_MAX:
problems.append("median match length %.1f min is outside %.0f to %.0f" % [median, Tuning.BALANCE_MEDIAN_MINUTES_MIN, Tuning.BALANCE_MEDIAN_MINUTES_MAX])
if analysis["top_share"] > Tuning.BALANCE_MAX_WEAPON_SHARE:
problems.append("%s took %.0f%% of weapon eliminations, over the %.0f%% limit" % [analysis["top_weapon"], analysis["top_share"] * 100.0, Tuning.BALANCE_MAX_WEAPON_SHARE * 100.0])
return analysis
## The report as plain text.
static func format(a: Dictionary) -> String:
var lines: PackedStringArray = []
var m: Dictionary = a["minutes"]
lines.append("Tidewall balance report: %d bot-only matches, %d players each" % [a["matches"], Tuning.SOLO_PLAYERS])
lines.append("")
lines.append("Match length (minutes from the barge leaving):")
lines.append(" min %.1f p10 %.1f p25 %.1f median %.1f p75 %.1f p90 %.1f max %.1f" % [m["min"], m["p10"], m["p25"], m["median"], m["p75"], m["p90"], m["max"]])
lines.append(" target median %.0f to %.0f; %d of %d ended by the tide's clock" % [Tuning.BALANCE_MEDIAN_MINUTES_MIN, Tuning.BALANCE_MEDIAN_MINUTES_MAX, a["timed_out"], a["matches"]])
var curve: PackedStringArray = []
for minute: int in STANDING_AT_MINUTES:
curve.append("%d min: %.1f" % [minute, a["standing"][minute]])
lines.append(" mean players standing: " + ", ".join(curve))
lines.append("")
lines.append("Causes of %d falls:" % a["deaths"])
var causes: Array = a["causes"].keys()
causes.sort()
for cause: String in causes:
lines.append(" %-8s %5d %5.1f%%" % [cause, a["causes"][cause], 100.0 * a["causes"][cause] / maxi(a["deaths"], 1)])
lines.append(" the sea (drown + tide): %.1f%%" % (a["tide_share"] * 100.0))
lines.append("")
lines.append("Eliminations by weapon (limit %.0f%% for any one):" % (Tuning.BALANCE_MAX_WEAPON_SHARE * 100.0))
var weapons: Array = a["weapon_kills"].keys()
weapons.sort_custom(func(x: String, y: String) -> bool: return a["weapon_kills"][x] > a["weapon_kills"][y])
for weapon: String in weapons:
lines.append(" %-16s %5d %5.1f%%" % [weapon, a["weapon_kills"][weapon], a["weapon_share"][weapon] * 100.0])
lines.append("")
lines.append("By difficulty:")
for level: String in ["easy", "normal", "hard"]:
lines.append(" %-6s wins %3d eliminations %5d mean place %.2f" % [level, a["wins"].get(level, 0), a["eliminations"].get(level, 0), a["mean_place"].get(level, 0.0)])
lines.append("")
if a["problems"].is_empty():
lines.append("balance: ok")
else:
for problem: String in a["problems"]:
lines.append("balance FAIL: %s" % problem)
return "\n".join(lines) + "\n"
+1
View File
@@ -0,0 +1 @@
uid://b7srh0xr2vucq
+13 -3
View File
@@ -12,8 +12,9 @@ static func tick_limit() -> int:
## Plays one match of `bots` bots on `seed_value`. `difficulty` -1 mixes the levels.
## Returns {"seed", "finished", "ticks", "winner", "winner_difficulty", "timed_out",
## "causes": {cause: count}, "places": {difficulty name: [place, ...]},
## "eliminations": {difficulty name: count}, "shots", "slow_ticks", "timing",
## "state_hash"}.
## "eliminations": {difficulty name: count}, "weapon_kills": {item id: count},
## "death_seconds": [seconds into the match of each fall], "shots", "slow_ticks",
## "timing", "state_hash"}. Seconds count from the barge leaving.
static func run_match(seed_value: int, bots: int = Tuning.SOLO_PLAYERS, difficulty: int = -1) -> Dictionary:
var loop: ServerLoop = ServerLoop.new(seed_value, 0, bots, null, difficulty)
var flow: Match = loop.match_flow
@@ -23,7 +24,7 @@ static func run_match(seed_value: int, bots: int = Tuning.SOLO_PLAYERS, difficul
var result: Dictionary = {
"seed": seed_value, "finished": false, "winner": 0, "winner_difficulty": "",
"timed_out": false, "causes": {}, "places": {}, "eliminations": {}, "shots": 0,
"slow_ticks": [],
"slow_ticks": [], "weapon_kills": {}, "death_seconds": [],
}
var limit: int = tick_limit()
while loop.ticks < limit and flow.phase != Match.RESULTS:
@@ -52,6 +53,15 @@ static func run_match(seed_value: int, bots: int = Tuning.SOLO_PLAYERS, difficul
if row["place"] != 1:
var cause: String = row["cause"]
result["causes"][cause] = int(result["causes"].get(cause, 0)) + 1
for record: Dictionary in flow.placements:
if record["left"]:
continue
result["death_seconds"].append(snappedf(float(record["tick"]) / Tuning.TICK_RATE_HZ, 0.1))
if record["cause"] == "weapon" and int(record["by"]) != 0:
var def: ItemDef = ItemCatalog.get_def(int(record["item"]))
# The boathook isn't in the catalog: its code is ItemCatalog.NONE.
var weapon: String = def.id if def != null else (ItemCatalog.BOATHOOK if int(record["item"]) == ItemCatalog.NONE else "unknown")
result["weapon_kills"][weapon] = int(result["weapon_kills"].get(weapon, 0)) + 1
result["timing"] = loop.timing_stats()
result["state_hash"] = loop.sim.state_hash()
return result
+54
View File
@@ -0,0 +1,54 @@
extends TestCase
## The balance pass's report (H3): match length quantiles, weapon shares, survivors
## over time, and the verdict against the BALANCE_* targets.
func _match(seed_value: int, minutes: float, kills: Dictionary, winner: String = "normal") -> Dictionary:
var deaths: Array = []
for index: int in Tuning.SOLO_PLAYERS - 1:
deaths.append(minutes * 60.0 * (index + 1) / Tuning.SOLO_PLAYERS)
return {
"seed": seed_value, "finished": true, "winner": -1, "winner_difficulty": winner, "timed_out": false,
"causes": {"weapon": Tuning.SOLO_PLAYERS - 1}, "places": {"normal": [1, 2]}, "eliminations": {"normal": 2},
"weapon_kills": kills, "death_seconds": deaths, "shots": 10, "ticks": roundi(minutes * 60.0 * Tuning.TICK_RATE_HZ),
"timing": {"p99_us": 100, "over_budget": 0}, "state_hash": "x",
}
func test_quantiles_interpolate() -> void:
var values: Array[float] = [1.0, 2.0, 3.0, 4.0]
assert_eq(BalanceReport.quantile(values, 0.0), 1.0)
assert_eq(BalanceReport.quantile(values, 0.5), 2.5)
assert_eq(BalanceReport.quantile(values, 1.0), 4.0)
assert_eq(BalanceReport.quantile([] as Array[float], 0.5), 0.0)
func test_a_balanced_batch_passes() -> void:
var results: Array[Dictionary] = []
for index: int in Tuning.BALANCE_MIN_MATCHES:
results.append(_match(index, 13.0 + (index % 5) * 0.5, {"dock_carbine": 8, "signal_revolver": 8, "rivet_repeater": 7}))
var a: Dictionary = BalanceReport.analyse(results)
assert_eq(a["problems"], [], "no problems: %s" % [a["problems"]])
assert_eq(a["minutes"]["median"], 14.0)
assert_true(absf(a["weapon_share"]["dock_carbine"] - 8.0 / 23.0) < 0.001)
assert_true(a["standing"][12] > 1.0 and a["standing"][2] > a["standing"][12], "survivors fall over time: %s" % [a["standing"]])
assert_true(BalanceReport.format(a).contains("balance: ok"))
func test_short_matches_a_dominant_weapon_and_a_small_batch_fail() -> void:
var results: Array[Dictionary] = []
for index: int in 10:
results.append(_match(index, 6.0, {"rivet_repeater": 20, "dock_carbine": 3}))
var a: Dictionary = BalanceReport.analyse(results)
var text: String = BalanceReport.format(a)
assert_eq(a["problems"].size(), 3, "count, length and weapon: %s" % [a["problems"]])
assert_true(text.contains("only 10 matches"))
assert_true(text.contains("median match length 6.0 min"))
assert_true(text.contains("rivet_repeater took 87%"))
func test_every_match_ends_inside_the_longest_target() -> void:
var seconds: float = float(Tide.new(0).time_limit_offset()) / Tuning.TICK_RATE_HZ
assert_true(seconds <= Tuning.BALANCE_MEDIAN_MINUTES_MAX * 60.0, "the tide and sudden death take %.0f s" % seconds)
assert_true(seconds >= Tuning.BALANCE_MEDIAN_MINUTES_MIN * 60.0, "and leave room for a %.0f-minute match" % Tuning.BALANCE_MEDIAN_MINUTES_MIN)
+1
View File
@@ -0,0 +1 @@
uid://c1yqg4w0d1y1a
+93
View File
@@ -39,6 +39,14 @@ func _bot(at: Vector3, level: int = BotBrain.NORMAL, yaw: int = 0) -> BotBrain:
return brain
## Keeps an idle bot where it stands, facing as it was put, instead of roaming off and
## turning its back on whoever the test placed.
func _pin(brain: BotBrain) -> void:
brain._hunt_goal = sim.entities.find(brain.player_id).position
brain._holding = true
brain._hunt_until = 1 << 30
func _arm(player: SimEntity, weapon: String = "dock_carbine", ammo: String = "cartridges", rounds: int = 150) -> void:
assert_eq(Inventory.give(player, ItemCatalog.code_of(weapon), 1), 0)
Inventory.give(player, ItemCatalog.code_of(ammo), rounds)
@@ -144,6 +152,7 @@ func test_an_armed_bot_eliminates_an_opponent_it_can_see() -> void:
_arm(sim.entities.find(brain.player_id))
var victim: SimEntity = _player(HOME + Vector3(25.0, 0.0, 0.0))
_ready_world()
_pin(brain)
_run(30 * TICKS, func() -> bool: return victim.eliminated)
assert_true(victim.eliminated, "the opponent fell (health %d)" % victim.health)
assert_eq(victim.last_attacker, brain.player_id)
@@ -191,6 +200,7 @@ func test_bots_wait_out_their_reaction_time() -> void:
_arm(sim.entities.find(brain.player_id))
_player(HOME + Vector3(20.0, 0.0, 0.0))
_ready_world()
_pin(brain)
_run(4 * TICKS, func() -> bool: return not first_shot.is_empty())
assert_true(first_shot.has(brain.player_id), "%s fired" % brain.difficulty_name())
var reaction: int = roundi(float(Tuning.BOT_DIFFICULTIES[level]["reaction"]) * TICKS)
@@ -330,6 +340,8 @@ func test_an_unarmed_bot_closes_in_and_swings_its_boathook() -> void:
var victim: SimEntity = _player(HOME + Vector3(4.5, 0.0, 0.0))
var start: int = victim.health
_ready_world()
# Unarmed bots only brawl someone who hit them (H3).
Weapons.damage_player(sim, sim.entities.find(brain.player_id), 5, victim.id)
var swings: Array[int] = [0]
for _tick: int in 6 * TICKS:
_run(1)
@@ -353,3 +365,84 @@ func test_an_unarmed_bot_leaves_a_distant_opponent_alone() -> void:
_run(3 * TICKS)
assert_ne(brain.state, "brawl")
assert_eq(victim.health, Tuning.PLAYER_MAX_HEALTH)
func test_an_unarmed_bot_does_not_start_a_brawl() -> void:
_setup()
var brain: BotBrain = _bot(HOME, BotBrain.HARD, FACING_X)
var other: SimEntity = _player(HOME + Vector3(4.5, 0.0, 0.0))
_ready_world()
_run(3 * TICKS)
assert_ne(brain.state, "brawl")
assert_eq(other.health, Tuning.PLAYER_MAX_HEALTH, "nobody was hit")
func test_a_bot_ignores_a_far_opponent_until_it_is_shot() -> void:
_setup()
var brain: BotBrain = _bot(HOME, BotBrain.HARD, FACING_X)
var me: SimEntity = sim.entities.find(brain.player_id)
_arm(me)
# In sight (hard bots see 90 m) but further than a bot picks out a new opponent.
var other: SimEntity = _player(HOME + Vector3(Tuning.BOT_ENGAGE_METRES + 15.0, 0.0, 0.0))
_ready_world()
_pin(brain)
_run(2 * TICKS)
assert_eq(brain.target_id, 0, "it doesn't go looking for a fight that far off")
assert_true(shots_by.is_empty())
Weapons.damage_player(sim, me, 10, other.id)
_run(3 * TICKS)
assert_eq(brain.target_id, other.id, "but answers one who shoots at it")
assert_true(int(shots_by.get(me.id, 0)) > 0, "and fires back")
func test_an_unarmed_bot_runs_from_a_gun() -> void:
_setup()
var brain: BotBrain = _bot(HOME, BotBrain.EASY, FACING_X)
var me: SimEntity = sim.entities.find(brain.player_id)
var gunner: SimEntity = _player(HOME + Vector3(12.0, 0.0, 0.0), FACING_X * 3)
_arm(gunner)
gunner.selected = 1
_ready_world()
_pin(brain)
_run(2 * TICKS)
assert_eq(brain.state, "retreat", "an unarmed bot breaks away from a held gun")
_run(4 * TICKS)
assert_true(me.position.distance_to(gunner.position) > 16.0, "and gets further off (%.1f m)" % me.position.distance_to(gunner.position))
func test_a_badly_hurt_bot_breaks_off_but_an_easy_one_does_not() -> void:
for level: int in [BotBrain.HARD, BotBrain.EASY]:
_setup()
var brain: BotBrain = _bot(HOME, level, FACING_X)
var me: SimEntity = sim.entities.find(brain.player_id)
_arm(me)
Inventory.give(me, ItemCatalog.code_of("sailcloth_bandage"), 2)
me.health = 30
var other: SimEntity = _player(HOME + Vector3(20.0, 0.0, 0.0), FACING_X * 3)
_arm(other)
other.selected = 1
_ready_world()
_pin(brain)
var states: Dictionary = {}
for _tick: int in 2 * TICKS:
_run(1)
states[brain.state] = true
if level == BotBrain.HARD:
assert_true(states.has("retreat"), "hard breaks off at 30 health with bandages: %s" % [states.keys()])
else:
assert_false(states.has("retreat"), "easy fights on: %s" % [states.keys()])
assert_true(states.has("fight"), "easy fights: %s" % [states.keys()])
func test_a_bot_with_nothing_to_do_holds_its_ground() -> void:
_setup()
var brain: BotBrain = _bot(HOME)
var me: SimEntity = sim.entities.find(brain.player_id)
_arm(me)
_ready_world()
_run(60 * TICKS, func() -> bool: return brain.state == "hold")
assert_eq(brain.state, "hold", "it roams somewhere and settles")
var at: Vector3 = me.position
_run(roundi(Tuning.BOT_HOLD_SECONDS * 0.8) * TICKS)
assert_true(me.position.distance_to(at) < 3.0, "and stays put while holding (moved %.1f m)" % me.position.distance_to(at))
assert_true(at.distance_to(HOME) <= Tuning.BOT_ROAM_METRES + 5.0, "it didn't roam far (%.1f m)" % at.distance_to(HOME))
+4 -3
View File
@@ -16,9 +16,10 @@ func test_a_scripted_seat_sends_commands_like_anyone_else() -> void:
func test_harvests_driftwood_and_builds_with_it() -> void:
# Seed 2 is the match `make match` plays: the player lands, finds a weapon, cuts
# driftwood and puts up a breakwater and a wall about a minute in.
var loop: ServerLoop = ServerLoop.new(2, 1, 23)
# Seed 29 is the match `make match` plays: the player lands, finds a weapon, cuts
# driftwood and puts up a breakwater and a wall within a minute. (It was seed 2 until
# H3 changed where bots land; there the scripted player now falls in a landing fight.)
var loop: ServerLoop = ServerLoop.new(29, 1, 23)
loop.play_humans_by_script()
var player: ScriptedPlayer = loop.scripted[0]
var placed: int = 0