killer-queen

name	killer-queen
description	Domain knowledge for Killer Queen arcade. Use when reasoning about game mechanics, event semantics, feature engineering, or win condition logic. Covers the gameplay loop, player roles, map structure, and how game concepts map to code.

Killer Queen Arcade — Game Design & Code Mapping

Game Overview

Killer Queen is a 5v5 arcade strategy game played on a shared cabinet. Two teams (blue and gold) compete simultaneously across three independent win conditions. The first team to complete ANY win condition wins.

The map is horizontally contiguous — entities that exit one edge appear on the opposite side with preserved momentum.

Win Conditions

Win condition	Mechanism	Model state
Military	Kill the enemy queen 3 times	eggs[team] starts at 2 (not 3 — the queen is already alive), reaching 0 = loss
Economic	Fill all 12 berry slots on your side	food_count[team] reaches 12; food_dep[team] tracks which slots are filled
Snail	Ride the snail into the enemy goal	snail_x reaches 0 (gold goal when gold_on_left) or 1920 (blue goal when gold_on_left)

All three run concurrently. Games typically end in 60-180 seconds. Military is most common, economic second, snail rare.

Players & Roles

Each team has 5 players: 1 queen + 4 workers.

Position IDs (from HiveMind API):

• 1 = Gold Queen, 2 = Blue Queen
• 3/5/7/9 = Gold workers (Stripes/Abs/Skull/Checkers)
• 4/6/8/10 = Blue workers (Stripes/Abs/Skull/Checkers)
• Team = pid % 2 (0 = blue, 1 = gold). Worker index = (pid - 3) // 2.

Queen: Combat only. Cannot use maiden gates but tags them by contact (blessMaiden event). Has 3 lives (eggs). Kills drones/warriors in one hit. Queen-vs-queen or warrior-vs-warrior combat resolves by Y-coordinate: higher unit wins. On ties, queen beats warrior; same-class ties cause knockback (no kill). Queens can dive (fast downward) and are the only unit that can tag (re-bless) gates.

Workers start as drones (unarmed, slow). Each worker has 4 boolean state flags:

Flag	Code	Meaning
is_bot	w[team][widx][0]	AI-controlled (rare in competitive play)
has_food	w[team][widx][1]	Carrying a berry
has_speed	w[team][widx][2]	Speed upgrade from maiden gate
has_wings	w[team][widx][3]	Wings upgrade — becomes a warrior

Worker upgrade paths (via maiden gates — consumes the carried berry):

• Drone → Warrior (wings gate): can fight, fly (hover, no dive). Most common upgrade.
• Drone → Speed drone (speed gate): 1.4x ground speed, rides snail faster. Still unarmed.
• Speed drone → Speed warrior (wings gate): fastest + can fight. Strongest form.

Warriors cannot carry berries, so they cannot use gates — the only path to speed warrior is drone → speed → wings.

Warriors cannot ride the snail. Workers die in one hit from queens or warriors. On death, all upgrades are lost (revert to drone). Carried berry is dropped as a loose berry.

Maiden Gates

5 gates per map, each with a fixed type (speed or wings) and a current blessing color (blue/gold/neutral).

• Workers use a gate to receive its upgrade type (must be blessed to their team color)
• Queens tag (re-bless) gates by physical contact — this is how gate color changes
• Gate blessing persists until re-tagged by the other team's queen
• maiden_states[0..4]: +1 = blue, -1 = gold, 0 = neutral

Gate positions and types vary by map. The model tracks all 5 gate states as features. Gate control is strategically important — controlling gates denies enemy upgrades.

Berries (Economic)

Each map has berry bushes on the left and right sides (totals vary: Day/Dusk=66, Night=54, Twilight=60). Workers pick up berries and deposit them in holes near their team's hive.

• food_count[team] = number of filled berry slots (0-12)
• food_dep[team][0..11] = which specific slots are filled
• berries_avail = remaining berries on the map (decrements on deposit or kick-in)
• berryKickIn = queen kicks a loose berry into a hole (can go to either team's slot)

Workers drop carried food on death (berry becomes loose) or consume it at maiden gates (berry destroyed).

Famine cycle: When all berries are consumed or deposited (none loose or carried), a 90-second countdown begins. When it expires, all original berries respawn at their initial positions.

Snail

A large snail sits on a horizontal track. Workers ride it toward the enemy goal.

• snail_x = current position (0-1920 pixels). Starts at center (960).
• snail_vel = current velocity. 0 when not being ridden.
• Speed riders move snail at ~28.2 px/s, vanilla at ~20.9 px/s.
• gold_sym = +1 when gold_on_left, -1 otherwise. Used to normalize snail direction.
• Model feature: snail_pos = (inferred_x / 1920 - 0.5) * gold_sym (centered, direction-normalized).
• If both teams ride simultaneously, snail velocity = 0 (contested).
• A moving snail is lethal to ground-based enemies in front of it.
• snailEat = snail eats an enemy worker riding from the other side (rider continues).

Maps

4 maps: Day, Dusk, Night, Twilight. Map determines:

• Berry hole positions and total count
• Maiden gate positions and types (always 2 speed + 3 wings)
• Snail track width
• Overall layout geometry

Map structure defined in map_structure_info.json. Model uses one-hot encoding: map_idx (0-3).

gold_on_left

Each game has a gold_on_left boolean from mapstart. When True, gold hive is on the left side of the screen, blue on right. When False, the layout is mirrored (all x-coordinates flip: x → 1920 - x).

The model normalizes for this via gold_sym and team-relative features so predictions are orientation-invariant. The _MAP_LOOKUPS dict is keyed by (map_name, gold_on_left) to handle coordinate mapping.

Key Game Events

Event	What happens	State mutation
gamestart	Game begins	Sets reference timestamp
mapstart	Map loaded	Sets map name + gold_on_left
spawn	Player spawns	Sets is_bot flag
carryFood	Worker picks up berry	has_food = True
berryDeposit	Worker deposits berry	food_count++, has_food = False
berryKickIn	Queen kicks berry in	food_count++ for target team
blessMaiden	Gate changes color	maiden_states[idx] = +1/-1
useMaiden	Worker uses gate	Gets speed or wings, has_food = False
playerKill	Player killed	Queen: eggs--. Worker: all flags reset to False
getOnSnail	Worker mounts snail	Sets snail_vel based on rider speed
getOffSnail	Worker dismounts	snail_vel = 0
snailEat	Snail eats enemy rider	Position updates, rider keeps going
snailEscape	Eaten rider escapes	snail_vel = 0
victory	Game ends	Blue or Gold wins

Models

Win-probability model (LightGBM): Takes the 52-feature state vector at each event and predicts P(gold wins). This is the model described below and used by the counterfactual system.

Game quality classifier (LightGBM): Takes 69 hand-crafted heuristic features computed over an entire game and predicts whether the game is competitive (vs. casual/incomplete). Trained on logged-in games as positives, unfiltered games as negatives. Used to filter training data for the win-probability model. See game_quality_classifier/ and CLAUDE.md for details.

Win-Probability Feature Vector (52 features)

Per team (20 features x 2 teams = 40):

• eggs (queen lives remaining)
• food_count (berry slots filled)
• num_vanilla_warriors, num_speed_warriors
• 4 workers sorted by power score, each with 4 bools: [is_bot, has_food, has_speed, has_wings]

Shared features (12):

• maiden_states[0..4] (5 gate colors)
• map_one_hot[0..3] (4 map indicators)
• snail_pos (normalized position)
• snail_speed (normalized velocity)
• berries_avail (fraction remaining)

Counterfactual System

export_predictions.py computes "what-if" deltas: for each event, what would the win probability be if a hypothetical event happened instead?

Keys: bqk/gqk (queen kill), bb/gb (berry), bswd/bvwd/gswd/gvwd (warrior deaths), bsdw/bdw/bws/gsdw/gdw/gws (upgrades), sb/sg (snail), mb0-mb4/mg0-mg4 (per-gate maiden flips).