Add environment documentation from Openverse builder
This commit is contained in:
Openverse Builder
224
environment.md
Normal file
224
environment.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# GAME DESIGN DOCUMENT — “ELEMENTAL CHAMPIONS: THE TOURNAMENT OF TRIADS”
|
||||
|
||||
---
|
||||
|
||||
## 1. Concept Paragraph
|
||||
|
||||
**Setting & Core Idea:**
|
||||
In *Elemental Champions*, two mystic duelists face off in a ritual tournament governed by the Triad Spirits: **Flame**, **Tide**, and **Gale** (analogous to rock-paper-scissors but reimagined with magical elements). Each duel is a best-of-N match where players secretly channel one elemental force each turn. Outcomes are deterministic and reproducible via seed-based initialization. This design is **fully original** and **unrelated to any negotiation or commerce-based example**. Core actions are expressed through tokens `[Channel: <Element>]`.
|
||||
|
||||
The environment is abstract, turn-based, and competitive—players accumulate “Essence Points” by winning rounds. When either player reaches the required victory count or the maximum number of rounds is played, the tournament concludes.
|
||||
|
||||
---
|
||||
|
||||
## 2. Roles and Win Condition
|
||||
|
||||
- **Players:** Two — `duelist_A` and `duelist_B`.
|
||||
- **Objective:** Reach a majority of victories (e.g., first to 3 wins in a best-of-5).
|
||||
- **Rules of Elemental Dominance:**
|
||||
- **Flame** overpowers **Gale**
|
||||
- **Gale** overpowers **Tide**
|
||||
- **Tide** overpowers **Flame**
|
||||
- **Scoring:**
|
||||
- Win → +1 Essence Point.
|
||||
- Draw (same element) → No points.
|
||||
|
||||
**Win Condition:**
|
||||
- The first duelist to acquire 3 Essence Points wins instantly.
|
||||
- If all rounds are played and both have equal points, the result is a **Draw**.
|
||||
|
||||
---
|
||||
|
||||
## 3. Turn Structure and Determinism
|
||||
|
||||
**Turn Order:**
|
||||
Each round, both duelists select an element simultaneously. The environment reveals both actions, determines outcomes, updates scores, and proceeds to the next round.
|
||||
|
||||
**Turn Limit:**
|
||||
Fixed to 5 rounds maximum.
|
||||
|
||||
**Determinism:**
|
||||
Randomized initial seed (used only for consistent replay ordering and optional random tiebreaks) set through `seed`. Every simulation is reproducible given the same seed.
|
||||
|
||||
---
|
||||
|
||||
## 4. Action Grammar (Machine-Parseable)
|
||||
|
||||
**Allowed Actions:**
|
||||
```
|
||||
[Channel: Flame]
|
||||
[Channel: Tide]
|
||||
[Channel: Gale]
|
||||
```
|
||||
|
||||
**Formal Pattern (regex):**
|
||||
```
|
||||
^\[Channel:\s*(Flame|Tide|Gale)\]$
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
- ✅ *Valid:* `[Channel: Flame]`
|
||||
- ❌ *Invalid:* `[Cast: Flame]` → wrong token keyword (`Cast` not allowed)
|
||||
- ❌ *Invalid:* `[Channel: Fire]` → invalid element name (`Fire` not in set)
|
||||
- ❌ *Invalid:* `[Channel: Gale ] Surprised!` → extra text not allowed
|
||||
|
||||
---
|
||||
|
||||
## 5. Game State Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"seed": 20240514,
|
||||
"current_round": 3,
|
||||
"max_rounds": 5,
|
||||
"score_to_win": 3,
|
||||
"duelist_A": {
|
||||
"name": "duelist_A",
|
||||
"essence_points": 2,
|
||||
"last_action": "[Channel: Tide]"
|
||||
},
|
||||
"duelist_B": {
|
||||
"name": "duelist_B",
|
||||
"essence_points": 1,
|
||||
"last_action": "[Channel: Flame]"
|
||||
},
|
||||
"transcript": [
|
||||
{"round": 1, "A": "[Channel: Flame]", "B": "[Channel: Gale]", "outcome": "A wins"},
|
||||
{"round": 2, "A": "[Channel: Gale]", "B": "[Channel: Gale]", "outcome": "Draw"}
|
||||
],
|
||||
"winner": null,
|
||||
"is_terminal": false,
|
||||
"invalid_reason": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Initialization Rules
|
||||
|
||||
- **Seeding:** A deterministic pseudo-random generator initialized via `seed`.
|
||||
- **Initial Values:**
|
||||
- `current_round = 0`
|
||||
- Both players’ `essence_points = 0`
|
||||
- `winner = null`
|
||||
- `is_terminal = false`
|
||||
- **Onboarding Observation:**
|
||||
- Each duelist receives a system message:
|
||||
```
|
||||
Welcome to the Tournament of Triads! First to 3 Essence Points wins.
|
||||
Choose your elemental channel each round: Flame, Tide, or Gale.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Validation and Error Handling
|
||||
|
||||
**Illegal Action Detection:**
|
||||
- The action string (after extracting from `\boxed{{}}`) must match the allowed regex.
|
||||
- If mismatched or contains text outside pattern, trigger:
|
||||
- `set_invalid_move(player, reason="Malformed or unsupported action format.")`
|
||||
- If a player repeatedly sends invalid actions, the opponent automatically wins that round by default.
|
||||
|
||||
**Invalid Examples and Reasons:**
|
||||
- `[Burn: Flame]` → `"Malformed action keyword"`
|
||||
- `[Channel: Lightning]` → `"Unsupported element 'Lightning'"`
|
||||
- `[Channel: Flame] Extra text` → `"Extraneous text beyond action token"`
|
||||
|
||||
---
|
||||
|
||||
## 8. Terminal Conditions and Scoring
|
||||
|
||||
At end of every round:
|
||||
1. Score comparison decides winner if `essence_points >= score_to_win`.
|
||||
2. If `current_round >= max_rounds` → end tournament.
|
||||
3. **End-state logic:**
|
||||
- Highest score → winner
|
||||
- Equal scores → draw
|
||||
|
||||
**Tie-break Handling:**
|
||||
If round limit reached and scores equal, set:
|
||||
```
|
||||
"winner": "Draw"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Player Prompt Specification
|
||||
|
||||
**Prompt Outline:**
|
||||
|
||||
Identity Blurb:
|
||||
“You are a mystical duelist in the Tournament of Triads, channeling elemental forces of Flame, Tide, and Gale. Each round, you must select one element to channel. The first duelist to collect three Essence Points wins.”
|
||||
|
||||
Rules Reminder:
|
||||
- Flame defeats Gale
|
||||
- Gale defeats Tide
|
||||
- Tide defeats Flame
|
||||
- Use one of the valid tokens inside `\boxed{{}}`.
|
||||
|
||||
Allowed Actions:
|
||||
```
|
||||
[Channel: Flame]
|
||||
[Channel: Tide]
|
||||
[Channel: Gale]
|
||||
```
|
||||
|
||||
**Strict Format Requirement:**
|
||||
“Put your final answer within `\boxed{{}}` at the end of your response.”
|
||||
|
||||
**Few-shot Examples:**
|
||||
|
||||
Example valid response:
|
||||
```
|
||||
Flame is powerful this turn; I trust its strength.
|
||||
\boxed{{[Channel: Flame]}}
|
||||
```
|
||||
|
||||
Example invalid response:
|
||||
```
|
||||
I'll unleash fire this round.
|
||||
\boxed{{[Cast: Flame]}}
|
||||
(reason: invalid token prefix)
|
||||
```
|
||||
|
||||
**Helper Function Expectation:**
|
||||
`_extract_answer_content(self, action: str) -> str` will isolate content inside `\boxed{{}}` for parsing.
|
||||
|
||||
---
|
||||
|
||||
## 10. API Mapping Plan
|
||||
|
||||
**`reset`**
|
||||
- Initialize `game_state` according to Section 6.
|
||||
- Seed RNG.
|
||||
- Return introduction observation for both players.
|
||||
|
||||
**`step`**
|
||||
- Accept both players’ boxed actions.
|
||||
- Use `_extract_answer_content` to parse.
|
||||
- Validate against grammar. If invalid, mark `invalid_reason` and set opponent as round winner.
|
||||
- Record round result in `transcript`.
|
||||
- Increment `current_round`.
|
||||
- Check terminal conditions (Section 8).
|
||||
- Return updated observations and revised state.
|
||||
|
||||
**`_generate_player_prompt`**
|
||||
- Build per-player turn messages:
|
||||
- Identity blurb.
|
||||
- Current score, round number, opponent’s last move (if revealed).
|
||||
- Reminder of action grammar and response format.
|
||||
- Example snippet (as above).
|
||||
- Append running transcript for situational awareness.
|
||||
|
||||
---
|
||||
|
||||
## 11. Copy-Check Against the Example
|
||||
|
||||
All elements, naming, and objectives are **completely distinct** from any negotiation or trading-themed example.
|
||||
- **Domain:** Elemental dueling tournament (combat fantasy).
|
||||
- **Resource names:** “Essence Points,” “Flame,” “Tide,” “Gale.”
|
||||
- **Objectives:** Victory by earning points via element matchups.
|
||||
- **Game state keys:** unique (`essence_points`, `transcript`, `elemental outcome`, etc.).
|
||||
- **Prompt:** reflective of magical battle, not negotiations or deals.
|
||||
|
||||
**Therefore**, this design is original, self-consistent, and ready for environment implementation.
|
||||
Reference in New Issue
Block a user