testtest8/README.md

# GAME DESIGN DOCUMENT — “EchoMaze: The Labyrinth Duel”

---

## 1. Concept Paragraph

**EchoMaze** is a deterministic, turn-based strategy game set in a shifting underground labyrinth. Two explorers, **Player Sun** and **Player Moon**, race to reach the **Exit Glyph** hidden deep within a maze of corridors. Each turn, players issue one of several movement or tactical commands to navigate or manipulate the maze: **[Move: Direction]**, **[Scan]**, **[Mark]**, or **[Rest]**. The maze layout is fully deterministic and generated based on a fixed random seed to allow reproducibility. **This design is completely unrelated to the negotiation example**; it is a navigation and exploration contest with no bargaining or trade mechanics.  

---

## 2. Roles and Win Condition

- **Roles:**  
  - *Player Sun (Explorer A)* — Seeks to reach the Exit Glyph first.  
  - *Player Moon (Explorer B)* — Competes to reach the same goal.  

- **Objective:**  
  Each player tries to reach the cell containing the **Exit Glyph** before their opponent.

- **Win Condition:**
  - If one player’s position matches the Exit Glyph's location at the end of their move, they **win immediately**.
  - If both players reach the Exit Glyph simultaneously in the same round, the game ends in a **draw**.
  - If no player reaches the exit within `MAX_TURNS`, the game ends and the player **closer to the Exit Glyph** (by Manhattan distance) **wins**. If distances are equal, it’s a **draw**.

---

## 3. Turn Structure and Determinism

- Players alternate turns: **Player Sun → Player Moon → repeat**.  
- One action per turn.  
- After each player has acted an equal number of times, a **round** is completed.  
- `MAX_TURNS = 60` total (30 rounds per player).  
- Determinism is ensured through a **`maze_seed`** integer: the same seed produces the identical maze layout and Exit Glyph position for reproducibility.

---

## 4. Action Grammar (Machine-Parseable)

Each player provides one legal action per turn.  
**Action format:**  

| Action Type | Token Pattern | Description | Example Valid | Example Invalid |
|--------------|---------------|--------------|----------------|------------------|
| **Move** | `\[Move: (North|South|East|West)\]` | Move one cell in direction if path open | `[Move: North]` | `[Move: Up]` — invalid direction |
| **Scan** | `\[Scan\]` | Reveals adjacent wall/open information | `[Scan]` | `[Scan: East]` — invalid argument |
| **Mark** | `\[Mark\]` | Place a marker on current cell (for tracking visited locations) | `[Mark]` | `[Mark: X]` — arguments unsupported |
| **Rest** | `\[Rest\]` | Skip the turn but recover 1 Focus point | `[Rest]` | `[Rest for a while]` — invalid syntax |

All tokens are matched case-sensitively.  
On validation, anything outside these exact tokens will trigger an invalid move error.

---

## 5. Game State Schema

Example `game_state` (prettified JSON):

```json
{
  "maze_seed": 1234,
  "turn_count": 8,
  "max_turns": 60,
  "maze_layout": [
    ["#", "#", "#", "#", "#"],
    ["#", "S", ".", ".", "#"],
    ["#", ".", "#", "E", "#"],
    ["#", ".", ".", ".", "#"],
    ["#", "#", "#", "#", "#"]
  ],
  "exit_location": [2, 3],
  "players": {
    "Sun": {
      "position": [1, 1],
      "markers": [[1, 1]],
      "focus": 3,
      "observations": ["Turn 1: Started at (1,1).", "Turn 2: Moved East."],
      "last_action": "[Move: East]"
    },
    "Moon": {
      "position": [3, 3],
      "markers": [],
      "focus": 4,
      "observations": ["Turn 1: Started at (3,3).", "Turn 2: Scanned nearby walls."],
      "last_action": "[Scan]"
    }
  },
  "public_transcript": [
    "Sun: [Move: East]",
    "Moon: [Scan]"
  ],
  "winner": null,
  "is_terminal": false,
  "invalid_move_reason": null
}
```

---

## 6. Initialization Rules

- `maze_seed` determines deterministic maze generation and Exit Glyph placement.  
- Both explorers spawn at opposite corners of the maze (Sun: top-left open cell; Moon: bottom-right open cell).  
- Each player starts with:
  - `focus = 5`
  - Empty `markers` list.
- The **first observation** per player includes their starting coordinates and known adjacent walls.
- The same seed across runs produces the exact same maze walls, exits, and spawn coordinates.

---

## 7. Validation and Error Handling

**Validation steps:**
1. Extract content inside `\boxed{{}}` using `_extract_answer_content(self, action: str) -> str`.  
2. Match against grammar patterns:
   - If pattern mismatch → `set_invalid_move("Unrecognized action syntax.")`
   - If Move chosen but target cell is wall or outside maze → `set_invalid_move("Cannot move through wall or outside bounds.")`
   - If player already at Exit Glyph → ignore turn and end game.
   - If player has zero focus and action is not `[Rest]` → `set_invalid_move("Insufficient focus to perform action.")`
3. All invalid moves terminate the game for that player as **automatic loss**.

---

## 8. Terminal Conditions and Scoring

**Checks each turn:**
1. If player’s position == `exit_location` → **Immediate win**
2. If both reach exit same round → **Draw**
3. If `turn_count >= MAX_TURNS` → distance comparison:
   - Compute Manhattan distance for both to Exit Glyph.
   - Smaller distance → **Win**
   - Equal distance → **Draw**

**Scores:**
- Winner: +1 point, Loser: 0, Draw: 0.5 each.

---

## 9. Player Prompt Specification

### Prompt Outline:

**Theme intro:**  
> You are an explorer in the ancient labyrinth of EchoMaze. Your goal is to reach the Exit Glyph before your rival. The maze’s layout is consistent across turns, and every action reshapes your advantage.

**You can take exactly one of the following actions per turn, placing it within `\boxed{{}}`:**
- `[Move: North]`, `[Move: South]`, `[Move: East]`, `[Move: West]`
- `[Scan]`
- `[Mark]`
- `[Rest]`

**Rules summary:**
- You cannot move through walls or outside the maze.
- You need Focus > 0 to act (except `[Rest]` recovers 1 Focus).
- The game ends when someone reaches the Exit Glyph or the move limit expires.

**Format requirement:**  
At the end of your response, write your final chosen action inside `\boxed{{}}`.

**Few-shot examples:**

Example valid response:
```
I see a corridor to the east. I will advance through it carefully.
\boxed{{[Move: East]}}
```

Example invalid response:
```
I move upward.
\boxed{{[Move: Up]}}    <-- Invalid action (not a defined direction)
```

---

## 10. API Mapping Plan

- **`reset(seed)`**
  - Generates maze layout deterministically.
  - Initializes player positions, Focus, and empty markers.
  - Sets `turn_count = 0`, `winner = None`, `is_terminal = False`.
  - Returns initial observation dict for both players, including visible adjacent cells.

- **`step(player_id, action)`**
  - Extract content via `_extract_answer_content()`.
  - Validate action format and game legality.
  - Update positions, Focus, markers, and transcript.
  - Check terminal conditions (exit reached, invalid move, or turn limit).
  - Append the action description to `public_transcript`.
  - Return new observation, reward, and whether the game is terminal.

- **`_generate_player_prompt(player_id)`**
  - Uses the latest `game_state` to prepare a narrative prompt:
    - Brief summary of player’s position and known environment.
    - Note of Focus value and any markers placed.
    - Reminder that actions must be inside `\boxed{{}}`.
  - Returns prompt text.

---

## 11. Copy-Check Against the Example

This design is **entirely original**:
- The theme (labyrinth navigation and strategy) differs completely from any negotiation or economic scenario.  
- Resource names like *Focus*, *markers*, *Exit Glyph*, and *maze_seed* are unique.  
- Objectives (reach exit first) are spatial and exploratory, not bargaining-based.  
- All `game_state` keys and prompt text are unique to the **EchoMaze** concept.

---

**End of Design Document — EchoMaze: The Labyrinth Duel**