dummy-test-kw-v2/environment.md

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

{
  "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.