Two-team mode: optionally keep clans together, within a gap

[jbob06]

What

An optional setting on the Two-team mode rule: keep clans together. A player moved off the closed faction is placed on the open side most of their clan is on, while that leaves the side at most N players ahead of the other. Off by default; a rule without it behaves exactly as it does today.

Why

We are looking at running a 50v50 round on our server with this rule (tested live this morning: closed Lonestar, moved and whispered as expected). The one thing players lose compared with a normal round is that a clan joining together is split across the two sides, because each of them is placed on whichever side is smaller at that moment. Groups that turn up to play together are the people most likely to leave over that.

How it places

• A clan is the tag in square brackets at the front of the name, [WOLF] Dan, folded for case and width, twelve characters at most (clanTag).
• For a closed-faction player with a tag, the rule counts that clan per open side: players on the side, and moves in flight toward it. The side with strictly more of the clan is preferred.
• The preference is taken only if, after the move, that side is at most clanGap ahead of the other. Otherwise the player goes to the smaller side, as now.
• A clan split evenly between the sides has no preferred side.
• Players placed during this look count too, so a clan that lands on the closed faction together at a match start follows its first member, until the gap is reached.
• Only a player's first ask in the ten-minute window is placed by clan. A move that did not land is asked for again toward the smaller side, exactly as before, so a clan move the game refuses costs nothing new and cannot walk a player into the three-asks cap by itself.

It still never moves anyone between the two open sides, so this changes only where a closed-faction player lands.

Setting and compatibility

• clanGap on the rule's config, 1 to 10 (TWO_TEAMS_MAX_CLAN_GAP). validateTwoTeams leaves the key out when it is 0, so a rule saved before the setting existed keeps the same settings fingerprint when it is saved again, and its queued moves are not dropped.
• No migration, route, action or capability change.
• The editor has one more field, "Keep clans together (optional)", and the rule's summary line says "clans kept together, up to N ahead" when it is on.
• A move decided by a clan says so: Moved [WOLF] Dan to Red, with [WOLF]., and clan in the audit detail.
• README row updated.

Tests

• two-teams.test.ts: clanTag; a rule without the setting is unchanged; joining the clan's side though it is larger; a clan arriving together; members in flight counting at the next look; the gap as a hard limit; an evenly split clan; a second ask going to the smaller side; validation and the fingerprint staying the same when off.
• triggers-two-teams.test.ts: the move intent's faction, message and detail with a clan.

CI on my fork (jbob06#3, opened only for CI and now closed), with the TimescaleDB service as in ci.yml: lint, check and bun test green, 995 pass, 0 fail.

Not tested

• On a live server. The placement is covered by the unit tests only. Our live test this morning was of the rule as it is on main, with two players on.
• Whether the game's overpopulation lock refuses an RCON move onto the side that is ahead. I do not know that it does. If it does, the retry goes to the smaller side (see above), so the rule is no worse off, but the setting would then do less than it says on a server with a tight threshold.
• A tag that shows a moment after the player is in. The README says the game can do this. A player seen on the closed faction before their tag appears is placed as anyone else. In practice a player picks a faction some seconds after joining, so I expect this to be rare, but I have not measured it.

Prior art

The idea of a clan preference bounded by a gap is from SIXFIVE's balancer (AE-WD-BATTLESUITE/WARDOGS-RVG-50v50, MIT). No code is taken from it. Two differences: that one counts a clan from the player list at the start of a pass, so clan members placed in the same pass do not see each other, and here moves in flight and moves decided this look count; and here a refused clan move falls back to the smaller side.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KVnrnLs54SCrQzy3JDv3mz

[jbob06]

Closing: Team balance (merged 2026-10-01) covers this. It keeps clan tags together within the gap, which is what this PR added to Two-team mode. Thanks.