# 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:` | Plants a new tree on the specified empty plot. `` ∈ {A1–A5 (for Player A), B1–B5 (for Player B)} | `Plant:A3` | `Plant:C2` → Invalid (nonexistent plot) | | **Nurture** | `Nurture:` | Boosts growth stage of one existing, unharvested tree on a valid occupied plot. | `Nurture:B4` | `Nurture:B6` → Invalid (out of range) | | **Harvest** | `Harvest:` | 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:` - `Nurture:` - `Harvest:` - `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.