From b4e3220250fa16248f36dcc4a3a4da6988339d8c Mon Sep 17 00:00:00 2001 From: Qiuyang Mang Date: Mon, 8 Jun 2026 23:41:17 -0400 Subject: [PATCH] [2.0] Clarify Generals.io bot task docs --- .../generals_io_bot/harbor/app/README.md | 57 +++++++++++++++++++ .../harbor/app/generals_agent/README.md | 43 ++++++++++++++ 2.0/problems/generals_io_bot/readme | 41 ++++++++++--- README.md | 2 +- 4 files changed, 134 insertions(+), 9 deletions(-) diff --git a/2.0/problems/generals_io_bot/harbor/app/README.md b/2.0/problems/generals_io_bot/harbor/app/README.md index d925183c..a0ac147d 100644 --- a/2.0/problems/generals_io_bot/harbor/app/README.md +++ b/2.0/problems/generals_io_bot/harbor/app/README.md @@ -1,5 +1,62 @@ # Generals.io Bot Arena +![Generals.io gameplay](https://raw.githubusercontent.com/strakam/generals-bots/master/generals/assets/gifs/wider_gameplay.gif) + +Image credit: `strakam/generals-bots`, MIT license. + +Implement a bot for a local Generals.io-style two-player arena. The online +generals.io service is not used. + +## Game Setting + +Each game is a square-grid game with fog of war. The default Frontier-CS setting +uses 10x10 maps, a 180-turn truncation limit, and one game per baseline matchup +so that submissions return feedback quickly. + +Your goal is to protect your own general and capture the opponent's general as +often and as quickly as possible. If neither general is captured by the +truncation limit, the game is a draw for win-rate scoring. + +The simulator rules are: + +- The grid contains empty passable cells, impassable mountains, neutral cities, + and one general per player. +- You observe every cell in the 3x3 neighborhood around your owned cells. + Everything else is fogged, except fogged cities/mountains may appear as + `structures_in_fog` obstacles. +- Every turn, each player returns one action: + +```text +[pass, row, col, direction, split] +``` + +- Directions are `0=up`, `1=down`, `2=left`, `3=right`. +- If `pass` is true, the bot does nothing. Otherwise `(row, col)` must be an + owned source cell and the destination must be adjacent and passable. +- If `split == 0`, the move sends `source_army - 1` armies and leaves one + behind. If `split == 1`, the move sends `source_army // 2` armies. +- Moving into your own cell reinforces it. Moving into a neutral or enemy cell + captures it only when the moving army is strictly larger than the defending + army. The remaining army is the absolute difference. +- Capturing the enemy general immediately wins. +- Army growth is deterministic: every owned cell gains one army when + `timestep % 50 == 0`, and owned generals/cities gain one army when + `timestep % 2 == 1`. + +Your `act(observation, key)` receives a `generals.core.observation.Observation` +with these fields: + +```text +armies, generals, cities, mountains, neutral_cells, owned_cells, +opponent_cells, fog_cells, structures_in_fog, owned_land_count, +owned_army_count, opponent_land_count, opponent_army_count, timestep +``` + +All spatial fields have shape `(H, W)`. Boolean masks use `True` for presence; +`armies` is zero in fog. + +## Workflow + Work in `/app/generals_agent`, then run: ```bash diff --git a/2.0/problems/generals_io_bot/harbor/app/generals_agent/README.md b/2.0/problems/generals_io_bot/harbor/app/generals_agent/README.md index 47854f1f..e6de8d74 100644 --- a/2.0/problems/generals_io_bot/harbor/app/generals_agent/README.md +++ b/2.0/problems/generals_io_bot/harbor/app/generals_agent/README.md @@ -6,6 +6,34 @@ The judge-side arena is black-box. This workspace contains the bot skeleton and the public `generals-bots` package, but no Frontier-CS evaluation harness, baseline ensemble, seeds, or match runner. +## Goal + +Protect your own general and capture the opponent's general as often and as +quickly as possible. The final score combines win rate against several fixed +baseline bot families with a speed tiebreaker for faster wins. + +## Game Rules + +The task uses the local `generals-bots` simulator, not the online generals.io +service. + +- The game is played on a square grid. The default Frontier-CS setting is 10x10 + with a 180-turn truncation limit. +- The grid contains passable empty cells, impassable mountains, neutral cities, + your general, and the opponent's general. +- You observe every cell in the 3x3 neighborhood around your owned cells. + Other cells are fogged. Fogged cities/mountains may appear as + `structures_in_fog` obstacles. +- Each turn both players choose one action. Invalid actions become no-ops. +- Moving into your own cell reinforces it. Moving into a neutral or enemy cell + captures it only when the moving army is strictly larger than the defending + army. The remaining army is the absolute difference. +- Capturing the enemy general immediately wins. If neither general is captured + before truncation, the game is a draw for win-rate scoring. +- Army growth is deterministic: every owned cell gains one army when + `timestep % 50 == 0`, and owned generals/cities gain one army when + `timestep % 2 == 1`. + Useful imports: ```python @@ -26,6 +54,21 @@ Directions: 0 up, 1 down, 2 left, 3 right ``` +If `pass` is true, the bot does nothing. Otherwise `(row, col)` is the owned +source cell. If `split == 0`, the move sends `source_army - 1` armies and leaves +one behind. If `split == 1`, the move sends `source_army // 2` armies. + +The `observation` passed to `act(observation, key)` has these fields: + +```text +armies, generals, cities, mountains, neutral_cells, owned_cells, +opponent_cells, fog_cells, structures_in_fog, owned_land_count, +owned_army_count, opponent_land_count, opponent_army_count, timestep +``` + +All spatial fields have shape `(H, W)`. Boolean masks use `True` for presence; +`armies` is zero in fog. + Create a patch submission: ```bash diff --git a/2.0/problems/generals_io_bot/readme b/2.0/problems/generals_io_bot/readme index 91ae0b66..a68d47fe 100644 --- a/2.0/problems/generals_io_bot/readme +++ b/2.0/problems/generals_io_bot/readme @@ -1,13 +1,19 @@ # Generals.io Bot Arena +![Generals.io gameplay](https://raw.githubusercontent.com/strakam/generals-bots/master/generals/assets/gifs/wider_gameplay.gif) + +Image credit: `strakam/generals-bots`, MIT license. + ## Problem Implement a bot for a local Generals.io-style arena. Your bot plays repeated two-player games against fixed baseline bots in the `generals-bots` simulator. -Each game is played on a square grid with fog of war. A player wins by capturing -the opponent's general. If no general is captured before the truncation limit, -the game is scored as a draw for win-rate purposes. +Your goal is simple: protect your own general and capture the opponent's +general as often and as quickly as possible. + +Each game is played on a square grid with fog of war. If no general is captured +before the truncation limit, the game is scored as a draw for win-rate purposes. The environment is the local `generals-bots` simulator, not the online generals.io service. Each turn your bot receives an observation containing: @@ -18,11 +24,30 @@ opponent_cells, fog_cells, structures_in_fog, owned/opponent land and army counts, and timestep ``` -Fog hides cells outside the visibility radius around your territory. Mountains -are impassable. Cities and generals produce armies over time. A valid move sends -army from one owned cell to an adjacent passable cell; moving into enemy or -neutral territory captures it only when the moving army is larger than the -defending army. +## Game Rules + +The arena follows the local `generals-bots` simulator rules: + +- The grid contains passable empty cells, impassable mountains, neutral cities, + and one general per player. +- You see every cell in the 3x3 neighborhood around your owned cells. Other + cells are fogged. Cities and mountains in fog may appear as + `structures_in_fog` obstacles. +- Each turn both players choose one action. An action is either pass or move + from one owned source cell to one adjacent passable destination cell. +- A non-split move sends `source_army - 1` armies and leaves one army behind. + A split move sends `source_army // 2` armies. Moves from cells with one army + are invalid and become no-ops. +- Moving into your own cell reinforces it. Moving into neutral or enemy + territory is an attack. The attack captures the destination only when the + moving army is strictly larger than the defending army; the remaining army is + the absolute difference. +- Capturing the enemy general immediately wins the game. +- Army growth is deterministic: every owned cell gains one army when + `timestep % 50 == 0`, and owned generals/cities gain one army when + `timestep % 2 == 1`. +- The default task setting uses 10x10 maps, truncates at 180 turns, and runs + one game per baseline matchup for quick iteration. ## Submission diff --git a/README.md b/README.md index 939acf4b..31d4d542 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Research Problems Algorithmic Problems - 2.0 Problems + 2.0 Problems

## News