209 lines
8.2 KiB
Markdown
209 lines
8.2 KiB
Markdown
# 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. |