testtest6/README.md

# TURN-BASED GAME DESIGN DOCUMENT  
*(Environment Name: “Stellar Orchard”)*  

---

## 1. Concept Paragraph

**Stellar Orchard** is a deterministic, turn-based strategy game where two rival horticulturists compete to cultivate the most thriving orchard on a distant exoplanet. The environment simulates a grid of orchard plots, each plot able to host an alien tree that produces **lumen fruit**—a glowing bioengineered product that yields energy points. Players must choose each turn to **Plant**, **Nurture**, or **Harvest** specific plots to maximize their total energy yield before the season ends. Weather and soil conditions are fixed by a deterministic seed at reset, ensuring reproducibility. The design, theme, and terminology are **completely unrelated to any negotiation or trading example**.

---

## 2. Roles and Win Condition

- **Player Roles:**  
  - *Player A (Solar Gardener)*  
  - *Player B (Lunar Gardener)*  
  Each controls their own half of the orchard (plots tagged `A1–A5` for A; `B1–B5` for B).

- **Objective:**  
  Accumulate the highest **Energy Points (EP)** via strategic planting, nurturing, and harvesting of trees.

- **Win Conditions:**  
  - The game ends after **10 turns** or when both players have harvested all trees.  
  - The player with the **highest cumulative EP** wins.  
  - If total EPs are equal, the result is a **draw**.  
  - If a player performs two invalid moves consecutively, they **forfeit** the match and lose automatically.

---

## 3. Turn Structure and Determinism

- Fixed alternating turns: Player A → Player B → Player A → ...  
- Each turn, a player chooses **one valid action**.  
- Game ends after **Turn 10** (each player acts 5 times).  
- A `random_seed` parameter initializes soil fertility levels and initial weather pattern with reproducible deterministic effects.  
- No hidden randomness during play; outcomes are computed deterministically based on seed and previous actions.  

---

## 4. Action Grammar (Machine-Parseable)

All player actions are deterministic commands describing their move this turn. Actions must match **exactly one** of the grammar patterns below.

| Action Type | Format | Description and Rule | Example (Valid) | Example (Invalid) and Reason |
|--------------|---------|---------------------|-----------------|------------------------------|
| **Plant** | `Plant:<plot>` | Plants a new tree on the specified empty plot. `<plot>` ∈ {A1–A5 (for Player A), B1–B5 (for Player B)} | `Plant:A3` | `Plant:C2` → Invalid (nonexistent plot) |
| **Nurture** | `Nurture:<plot>` | Boosts growth stage of one existing, unharvested tree on a valid occupied plot. | `Nurture:B4` | `Nurture:B6` → Invalid (out of range) |
| **Harvest** | `Harvest:<plot>` | Harvests a fully grown tree from the specified plot, removing it and collecting EP. | `Harvest:A1` | `Harvest:A1,A2` → Invalid (multiple plots not allowed) |
| **Pass** | `Pass` | Player skips the turn intentionally (strategic or necessary if no valid move). | `Pass` | `[Pass]` → Invalid (extra brackets not part of syntax) |

**Regular Expression Patterns**  
- `^Plant:(A[1-5]|B[1-5])$`  
- `^Nurture:(A[1-5]|B[1-5])$`  
- `^Harvest:(A[1-5]|B[1-5])$`  
- `^Pass$`  

All valid actions will be wrapped by players inside `\boxed{{}}` at runtime, e.g., `\boxed{{Harvest:A1}}`.

---

## 5. Game State Schema

Example `game_state` format:

```json
{
  "turn_number": 3,
  "max_turns": 10,
  "active_player": "Solar Gardener",
  "plots": {
    "A1": {"owner": "A", "status": "grown", "growth_level": 3},
    "A2": {"owner": "A", "status": "empty", "growth_level": 0},
    "A3": {"owner": "A", "status": "seedling", "growth_level": 1},
    "B1": {"owner": "B", "status": "grown", "growth_level": 3},
    "B2": {"owner": "B", "status": "harvested", "growth_level": 0}
  },
  "energy_points": {
    "A": 15,
    "B": 12
  },
  "soil_fertility": {
    "A1": 0.9,
    "A2": 0.6,
    "B1": 0.8
  },
  "weather_pattern": "Radiant Skies",
  "transcript": [
    {"player": "A", "action": "Plant:A3"},
    {"player": "B", "action": "Nurture:B1"}
  ],
  "winner": null,
  "random_seed": 57
}
```

---

## 6. Initialization Rules

- `random_seed` is set during environment reset; it governs deterministic generation of:
  - `soil_fertility` for each plot (each between 0.5 and 1.0).  
  - `weather_pattern` (chosen deterministically from a fixed set: Radiant Skies / Lunar Mist / Crystal Winds).  
- `energy_points[A]` and `[B]` start at **0**.  
- All plots start as `"empty"`.  
- Observations include the common introduction, initial weather, soil fertility summary, and allowed actions.  

---

## 7. Validation and Error Handling

On every step:

1. Extract literal content from `\boxed{{...}}` using `_extract_answer_content`.  
2. Validate syntax against regex patterns.  
3. Check logical validity:  
   - **Plant** → must target empty plot owned by that player.  
   - **Nurture** → must target already planted, not yet grown tree.  
   - **Harvest** → must target grown, unharvested tree.  
   - **Pass** → always valid.  
4. Any violation triggers `set_invalid_move(player, reason)`, e.g.:  
   - `"Invalid format"`  
   - `"Plot not owned by player"`  
   - `"Plot already occupied"`  
   - `"Tree not ready to harvest"`  

---

## 8. Terminal Conditions and Scoring

- **Automatic End:**
  - When `turn_number >= max_turns`  
  - OR when all plots are `harvested` or `empty` (no active trees remain)

- **Scoring:**
  - For each harvested tree: `EP += int(10 * soil_fertility[plot])`.
  - No fractional points.  
  - Final score is the total `EP` accumulated.

- **Result Determination:**
  - Higher total → **Winner**.  
  - Equal totals → **Draw**.  
  - Consecutive double invalid move by a player → automatic **Loss**.

---

## 9. Player Prompt Specification

**Identity Context:**  
“You are a cosmic horticulturist tending bioluminescent trees on the exoplanet Selora. Your goal is to maximize your orchard’s energy yield before the season ends.”

**Prompt Structure Includes:**
- Current turn number and remaining turns.
- Your current EP and plots' status summary.
- Weather pattern and soil fertility hints.
- List of all valid actions:
  - `Plant:<plot>`
  - `Nurture:<plot>`
  - `Harvest:<plot>`
  - `Pass`
- Explicit response requirement: “Put your final answer within `\boxed{{}}` at the end of your response.”

**Few-shot Examples:**
```
Example valid response:
I will start by planting my first tree in plot A2.
\boxed{{Plant:A2}}
```

```
Example invalid response:
Let's see how this goes!
\boxed{{Grow:A2}}    # Invalid because 'Grow' is not a recognized action type.
```

**Dialogue Elements:** None (pure command game). All player utterances (including justification text) get appended to transcript for transparency.

---

## 10. API Mapping Plan

- **`reset(seed: Optional[int])`**
  - Initializes `game_state` using the deterministic seed.  
  - Builds initial soil fertility and weather data.  
  - Clears all plots, transcript, and EPs.  
  - Returns the observation containing theme introduction and available actions.

- **`step(action: str)`**
  - Extracts action content via `_extract_answer_content`.  
  - Validates syntax + legality.  
  - Updates game state deterministically (adjust plot status, growth level, EPs).  
  - Adds the player’s message and resulting action to transcript.  
  - Advances to the next turn or marks the game as terminal if conditions met.  
  - Returns updated observation, reward, and termination flag.

- **`_generate_player_prompt(player_id)`**
  - Constructs text prompt including:  
    - Game identity summary  
    - Current turn, soil info, plot statuses  
    - Weather condition and EP scores  
    - List of valid actions and formatting requirement  
    - Few-shot examples above  
  - Returns formatted prompt string.

---

## 11. Copy-Check Against the Example

All terms—**plots**, **trees**, **lumen fruit**, **Energy Points**, **soil fertility**, **weather pattern**, **Solar/Lunar Gardeners**, and **orchard management theme**—are *original* and entirely **unrelated to any negotiation, trading, or economic dialogue example**.  
The `game_state` keys (`plots`, `soil_fertility`, `energy_points`, etc.) and all action types are unique to **Stellar Orchard** and do not replicate any element from other sample environments.