# GAME DESIGN DOCUMENT — **"StarGrid Duel"**

---

### 1. Concept Paragraph
**StarGrid Duel** is a deterministic, turn-based strategy game inspired by the simplicity of grid conquest, but it is **not** tic‑tac‑toe. Two rival star‑navigators take turns deploying *energy beacons* on a 3×3 stellar grid. Their aim is to align three of their own beacons in a straight line of cosmic power (horizontal, vertical, or diagonal) before the opponent does, or to fill the grid entirely for a balanced standoff. Players will issue commands like `[Place: A2]` to deposit a beacon on a coordinate. The environment is purely deterministic: no randomness or negotiation mechanics are involved. The game’s purpose is to measure spatial foresight and terminal pattern recognition—completely unrelated to any negotiation or resource trading examples.

---

### 2. Roles and Win Condition
- **Roles**  
  - **Player A ("Navigator Alpha")**: Uses energy color **Blue**.  
  - **Player B ("Navigator Beta")**: Uses energy color **Crimson**.  

- **Objective**  
  Be the first navigator to align three of your beacons continuously (row, column, or diagonal) on the 3×3 StarGrid.

- **Win Rule**
  - A player **wins** immediately upon forming a line of three of their own symbols.
  - The game is a **draw** if all nine cells are filled without a three‑in‑a‑line configuration.
  - Upon win or draw, the game enters a terminal state and no further actions are accepted.

---

### 3. Turn Structure and Determinism
- Players alternate turns beginning with Player A at turn index `0`.
- Each turn is atomic: exactly one action is taken.
- A deterministic seed ensures that initialization and any potential random ordering (none required here, but included for reproducibility) follow identical patterns.
- The turn counter increments after each valid action. Once nine valid turns have been processed or a win condition is met, the environment halts.

---

### 4. Action Grammar (Machine‑Parsable)
Players specify grid placement commands targeting one unused cell.

**Allowed Actions**
```
[Place: <cell_id>]
```

**Cell IDs**  
Valid values: `A1, A2, A3, B1, B2, B3, C1, C2, C3` (Rows A–C, Columns 1–3)

**Formal Pattern (Regex)**  
`^\[Place:\s*(A|B|C)(1|2|3)\]$`

**Examples**
- **Valid:** `[Place: B2]` → Places player’s beacon in the center cell.
- **Invalid Examples:**  
  - `[place: B2]` → Invalid capitalization and token name.  
  - `[Place: D1]` → `D1` not in allowed grid range.  
  - `[Deploy: A1]` → Invalid action token.  
  - `[Place: B2 extra]` → Extra text violates strict grammar.

All player outputs later will be wrapped in `\boxed{{…}}`. The implementation will extract the internal `[Place: X#]` command to validate according to the above pattern.

---

### 5. Game State Schema
```json
{
  "turn_index": 4,
  "active_player": "B",
  "board": {
    "A1": "Blue",
    "A2": null,
    "A3": "Crimson",
    "B1": "Blue",
    "B2": "Crimson",
    "B3": null,
    "C1": null,
    "C2": null,
    "C3": null
  },
  "player_symbols": {
    "A": "Blue",
    "B": "Crimson"
  },
  "move_history": [
    {"player": "A", "action": "[Place: A1]"},
    {"player": "B", "action": "[Place: A3]"},
    {"player": "A", "action": "[Place: B1]"},
    {"player": "B", "action": "[Place: B2]"}
  ],
  "winner": null,
  "is_draw": false,
  "observations": {
    "A": "Text transcript of latest game state for Alpha",
    "B": "Text transcript of latest game state for Beta"
  },
  "seed": 42
}
```

---

### 6. Initialization Rules
- `reset(seed)` initializes an empty 3×3 board with all cells `null`.
- The turn index resets to `0` with `active_player = "A"`.
- The same seed always ensures that turn order, board labeling, and any deterministic tie logic behave identically.
- Both players receive an onboarding observation describing:
  - Empty StarGrid layout
  - Their color and symbol
  - Instructions and the legal action syntax

---

### 7. Validation and Error Handling
- Upon receiving a player move, extract the content inside `\boxed{{}}` using `_extract_answer_content`.
- Validate against the regex `^\[Place:\s*(A|B|C)(1|2|3)\]$`.
- Check that the specified cell is unoccupied.
- **Invalid Move Reasons**  
  - `"MalformedAction"`: Does not match required pattern.  
  - `"CellOutOfRange"`: Coordinate not part of StarGrid labels.  
  - `"CellOccupied"`: Target cell already taken.  
  - `"NotYourTurn"`: Attempt to act out of sequence after loss or between turns.  
  The environment calls `set_invalid_move(reason)` with a human-readable reason, retaining determinism (the turn is forfeited or handled as draw according to policy).

---

### 8. Terminal Conditions and Scoring
**Checks each turn immediately after placing a valid beacon:**
1. **Victory Check** – If the current player’s beacons form any of the eight winning line patterns, set `winner = active_player`, terminate game.
2. **Draw Check** – If no empty cells remain and no winner exists, set `is_draw = true`.
3. **Scoring** –  
   - Win: `+1` score for winner, `0` for loser.  
   - Draw: `0.5` each as tie credit (for potential series mode).

**Tie‑Break Procedure**  
If multiple win conditions appear simultaneously (impossible under normal rules), the first detected alignment pattern is applied deterministically.

---

### 9. Player Prompt Specification
Each player receives a structured prompt reflecting the current board and legal moves.

**Prompt Outline**

> **Identity Blurb:**  
> You are a star navigator placing energy beacons on a galactic grid. Each cell you claim radiates your color’s energy. The goal is to align three of your beacons in a line before the opponent.

> **Current Board State:**  
> - Display a 3×3 grid with coordinates and current occupancy.

> **Your Color:** Blue or Crimson  
> **Turn Information:** Which player moves next (`Navigator Alpha` or `Navigator Beta`)  

> **Allowed Actions:**  
> Format: `[Place: <cell_id>]`, where `<cell_id>` ∈ {A1,…,C3} and the cell must be empty.  
> You must wrap your selected action inside `\boxed{{}}` at the end of your message.

> **Response Format:**  
> You may reason about your move, then output your final choice within `\boxed{{}}`.

**Few‑Shot Examples**

```
Example valid response:
I will claim the center of the grid to control diagonals.
\boxed{{[Place: B2]}}

Example invalid response:
I think I'll move now.
\boxed{{[Move: B2]}}  ← "Move" not a valid token.
```

The function `_extract_answer_content(self, action: str) -> str` will remove `\boxed{{}}` wrappers and yield `[Place: X#]` for validation.

---

### 10. API Mapping Plan

- **`reset(seed)`**  
  - Sets initial empty `board`, `turn_index=0`, and seeds RNG for determinism.  
  - Returns initial observations (`"Navigator Alpha"`, `"Navigator Beta"`).  

- **`step(player_action)`**  
  - Extracts action token with `_extract_answer_content`.  
  - Validates syntax and target cell availability.  
  - Updates `board`, appends to `move_history`, increments `turn_index`.  
  - After update, executes terminal checks (victory or draw).  
  - Produces new observations describing updated board state.  

- **`_generate_player_prompt(player_id)`**  
  - Compiles textual description of board, current scores, and open cells.  
  - Lists permitted `[Place: <cell_id>]` choices.  
  - Concludes with directive: *Put your final answer within \boxed{{}} at the end of your response.*

All actions and resultant board states are deterministic given identical seeds and action sequences.

---

### 11. Copy‑Check Against the Example
- The environment, terminology, and objective are **entirely original**.  
- There is **no negotiation**, **no trading**, **no resource exchange**, and **no alignment with any bargaining mechanics** from the example environment.  
- Entities (“Navigator Alpha/Beta,” “energy beacons,” “StarGrid”) and game state keys (`board`, `player_symbols`, `move_history`, etc.) are unique to this design.  
- The theme is cosmic grid conquest, **not** any prior example domain.

---

**End of Design Document – “StarGrid Duel”**