tic/environment.md

---

# **TURN-BASED GAME DESIGN DOCUMENT – “STELLAR TRIAD”**

*(Original design inspired by abstract alignment games, but distinct in theme, terminology, and flavor. This is **not** a replication of tic-tac-toe, though it satisfies the same deterministic two-player turn-based design requirements.)*

---

## **1. Concept Paragraph**

**Game Title:** *Stellar Triad*

Two rival star architects compete to align energy beacons on a 3×3 orbital matrix orbiting a dying star. Each architect channels luminous "Nodes" of cosmic energy into the matrix to construct a stable triad of connected orbs — vertical, horizontal, or diagonal. The first to achieve a stable triad wins; if the matrix becomes full without stability, the core collapses and neither triumphs. Core actions are expressed through tokens like `[Channel:X-Y]` to place energy at targeted coordinates.  

This design is deterministic, completely unrelated to any negotiation, trading, or diplomacy example—its domain is cosmic engineering strategy.

---

## **2. Roles and Win Condition**

- **Players:** Two — *Architect A* and *Architect B*.
- **Objective:** Achieve the first "Stellar Alignment" — three controlled Nodes in a contiguous row, column, or diagonal on the 3×3 matrix.
- **Win Condition:**
  - If a player forms an alignment, they immediately win.
- **Draw Condition:**
  - If all nine spaces are filled and no alignment exists, the result is a *Stellar Collapse (draw)*.
- **Loss Condition:**
  - The opponent achieves alignment first.

---

## **3. Turn Structure and Determinism**

- Play alternates between Architect A and Architect B.
- Each turn, the acting player chooses exactly one valid move token.
- The environment is deterministic — no dice rolls, no randomness.
- Game seeding (`seed`) is used only to define the initial player order if applicable, ensuring reproducibility across resets.
- Turn limit: **9 turns maximum** (one for each matrix cell).

---

## **4. Action Grammar (Machine-Parseable)**

### **Allowed Actions**

- **Token:** `[Channel:X-Y]`
  - **Definition:** Player attempts to channel energy into cell at coordinates `X-Y` (X = 1–3 for columns, Y = 1–3 for rows).
  - **Pattern (regex):** `^\[Channel:(?:[1-3])-(?:[1-3])\]$`
  - **Example Valid Action:** `[Channel:2-3]` → place Node at column 2, row 3.
  - **Example Invalid Actions:**
    - `[Channel:4-1]` → Invalid X coordinate.
    - `[Channel:2_3]` → Wrong separator.
    - `[Deploy:2-3]` → Invalid token keyword.

### **Notes:**
- Only unoccupied cells can be targeted. Attempting to channel into an occupied cell is invalid.

---

## **5. Game State Schema**

Example `game_state` at runtime:

```json
{
  "matrix_state": [
    ["A", "B", null],
    ["A", null, "B"],
    [null, "A", null]
  ],
  "player_symbols": {
    "ArchitectA": "A",
    "ArchitectB": "B"
  },
  "turn_count": 5,
  "active_player": "ArchitectB",
  "last_action": "[Channel:2-2]",
  "move_history": [
    "ArchitectA:[Channel:1-1]",
    "ArchitectB:[Channel:2-1]",
    "ArchitectA:[Channel:1-2]",
    "ArchitectB:[Channel:3-1]",
    "ArchitectA:[Channel:2-3]"
  ],
  "game_result": null,
  "winner": null,
  "draw": false,
  "seed": 1234
}
```

---

## **6. Initialization Rules**

- `seed` determines starting player by parity: even seed → Architect A, odd seed → Architect B.
- `matrix_state` initialized as empty (all `null` values).
- First observation includes:
  - Empty orbital matrix.
  - Assigned symbols.
  - Clear reminder of valid action grammar.
- No randomness beyond starting player selection.

---

## **7. Validation and Error Handling**

Every action extracted from `\boxed{{}}` content passes through:

- **Format validation:** must match regex.
- **Range validation:** coordinates must be integers 1–3.
- **Occupancy validation:** target cell must be empty.
- **Turn enforcement:** only the active player may act.

**Invalid Action Reasons (to be passed to `set_invalid_move`):**
- `"Malformed token: does not match [Channel:X-Y] pattern"`
- `"Target cell occupied"`
- `"Coordinates out of range"`
- `"Not your turn"`
- `"Action missing or not boxed"`

---

## **8. Terminal Conditions and Scoring**

### **Checks after each valid move:**
1. **Alignment Detection:**
   - If the active player's symbol forms a contiguous line (row/column/diagonal), they win.
   - `game_result = "ArchitectA_won"` or `"ArchitectB_won"`.
   - `winner` updated accordingly.
2. **Full Matrix Check:**
   - If 9 moves completed without alignment → `draw = true`, `game_result = "Stellar_Collapse"`.
3. **Score Assignment:**
   - Win → 1.0  
   - Loss → 0.0  
   - Draw → 0.5 each.

---

## **9. Player Prompt Specification**

### **Structure of `_generate_player_prompt`:**

**Prompt Outline:**
1. Introduction / Identity:
   - “You are a cosmic architect competing to stabilize a stellar grid. Each cell represents an orbital conduit for energy. Your objective: align three of your Nodes in a row before your rival.”
2. Rules Summary:
   - Turn-based, alternating.
   - Each cell can be used once.
   - Valid move format strictly uses `[Channel:X-Y]` (where 1 ≤ X,Y ≤ 3).
3. End condition: First alignment wins; full grid without alignment = collapse (draw).
4. Response format:
   - “Put your final answer within \\boxed{{}} at the end of your response.”

### **Examples:**
```
Example valid response:
I will project energy into the lower middle conduit.
\boxed{{[Channel:2-3]}}

Example invalid response:
I channel energy south-east.
\boxed{{Channel:SE}}
```

### **Extraction Helper Reminder:**
- `_extract_answer_content(self, action: str) -> str` extracts the text between `\boxed{{` and `}}`.

---

## **10. API Mapping Plan**

| Method | Description | Inputs | Writes | Outputs |
|---------|--------------|--------|---------|----------|
| **`reset(seed)`** | Initializes a fresh Stellar Triad match. Sets `matrix_state` empty, seeds RNG (for turn order if applicable), and returns first observation for the active player. | `seed` | `matrix_state`, `player_symbols`, `seed`, `turn_count`, `active_player` | Observation for first player. |
| **`step(player, action)`** | Parses boxed content using `_extract_answer_content`. Validates action format and legality, updates board, checks terminal state. | `player`, `action` | `matrix_state`, `move_history`, `active_player`, `game_result`, `winner`, `draw` | Returns new observation, reward (if terminal), termination flags, or invalid move notice. |
| **`_generate_player_prompt(game_state, player)`** | Builds the textual prompt containing game state, visible matrix, valid action examples, and format rules. | `game_state`, `player` | N/A | Returns text prompt instructing player to act. |

Terminal signaling:
- When `winner` is set → `is_done = True`, appropriate reward assigned.
- When `draw == True` → `is_done = True`, rewards = 0.5 each.

---

## **11. Copy-Check Against Example**

- **Theme:** Cosmic engineering/energy alignment — *not* negotiation or trade.
- **Resources:** Matrix coordinates and “Nodes” — *no* currency or offers.
- **Objectives:** Alignment victory — *not* mutual acceptance or balance.
- **Game state keys:** (`matrix_state`, `player_symbols`, `seed`, etc.) are **unique and original** to this design.
- **Prompt content:** Describes cosmic architects and stellar energy, **not** any form of deal-making or bargaining.

---

**End of Game Design Document — “Stellar Triad”**

---