From 0d939fbda499f3fdd4968c9e76578557bd8f68b6 Mon Sep 17 00:00:00 2001 From: Openverse Builder Date: Mon, 1 Jan 2001 00:00:00 +0000 Subject: [PATCH] Add environment documentation from Openverse builder --- environment.md | 220 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 220 insertions(+) create mode 100644 environment.md diff --git a/environment.md b/environment.md new file mode 100644 index 0000000..ca399e3 --- /dev/null +++ b/environment.md @@ -0,0 +1,220 @@ +# **Turn-Based TextArena Environment Design Document** + +## 1. Concept Paragraph + +**Game Title:** *Crown of Fools* + +In *Crown of Fools*, two rival jesters compete in a royal card challenge, vying to assemble the most powerful hand before the court’s patience expires. The deck includes number cards (1–10), special Trick cards (that can reverse or multiply values), and the single **Crown Joker**, a wildcard that can turn a weak hand into a masterpiece. Players take turns drawing, playing, or discarding cards to manipulate their hand values strategically. The game is **unrelated to any negotiation or trading simulation example**; instead, it is a whimsical, competitive card duel focused on tactical card management and risk. The core action tokens revolve around `[Draw]`, `[Play:]`, `[Discard:]`, and `[Pass]`. + +--- + +## 2. Roles and Win Condition + +- **Players:** + Two jesters: *Player A (Jester Red)* and *Player B (Jester Blue)*. + +- **Objective:** + Each jester seeks to achieve the **highest total hand value** when the deck runs out, or when a jester declares “Crown” (their confidence in having the superior hand). + +- **Win Condition:** + - If a player declares `[Crown]`, both hands are revealed: + - The player with the greater total hand value **wins**. + - If the totals are equal, the **one holding the Crown Joker wins**. + - If neither holds the Joker, the game is a **draw**. + - If the deck depletes naturally (both run out of possible draws), scores are calculated automatically using the same rule. + +--- + +## 3. Turn Structure and Determinism + +- Turns alternate strictly: Player A → Player B → Player A → … +- Each turn consists of one valid action. +- The game ends immediately once a terminal condition (deck empty or `[Crown]` declaration) is met. +- Maximum of 30 turns (combined), after which an **automatic scoring** occurs. +- A pseudo-random seed initializes deck order; same seed ensures **deterministic reproducibility** for all runs. + +--- + +## 4. Action Grammar (Machine-Parseable) + +Allowed player actions (contents within `\boxed{{}}`): + +| Action Token | Format | Description | +|---------------|---------|-------------| +| Draw card | `[Draw]` | Take top card from the deck into hand | +| Play card | `[Play:]` | Use a card’s effect (must exist in hand) | +| Discard card | `[Discard:]` | Remove a card from hand to discard pile | +| Pass | `[Pass]` | Skip a turn (no effect) | +| Declare crown | `[Crown]` | End the round and reveal hands | + +**Validation Examples:** + +1. **Valid:** `[Draw]` – Correct token. + **Invalid:** `[DrawCard]` – Not a recognized keyword. + +2. **Valid:** `[Play:Trick_7]` – Matches held card label pattern. + **Invalid:** `[Play7]` – Missing colon and invalid syntax. + +3. **Valid:** `[Discard:Num_3]` – Legal if `Num_3` in hand. + **Invalid:** `[Discard:Joker]` – Joker cannot be voluntarily discarded. + +4. **Valid:** `[Pass]` – Legal at any time. + **Invalid:** `[Pause]` – Keyword not permitted. + +5. **Valid:** `[Crown]` – Legal action any time after turn 5. + **Invalid:** `[CrownNow]` – Not a recognized pattern. + +**Formal Regular Expressions:** + +- `^\[Draw\]$` +- `^\[Play:[A-Za-z0-9_]+\]$` +- `^\[Discard:[A-Za-z0-9_]+\]$` +- `^\[Pass\]$` +- `^\[Crown\]$` + +--- + +## 5. Game State Schema + +Example runtime schema: + +```json +{ + "phase": "active", + "turn_index": 7, + "current_player": "A", + "deck_order": ["Num_9", "Num_2", "Trick_1", "Crown_Joker", "Num_8", "Trick_3"], + "discard_pile": ["Num_5"], + "players": { + "A": { + "hand": ["Num_1", "Num_4", "Trick_2"], + "score": 7, + "has_joker": false, + "last_action": "[Play:Trick_2]" + }, + "B": { + "hand": ["Num_6", "Crown_Joker"], + "score": 16, + "has_joker": true, + "last_action": "[Draw]" + } + }, + "history": [ + {"player": "A", "action": "[Draw]"}, + {"player": "B", "action": "[Play:Num_3]"} + ], + "seed": 20240506, + "terminal": false, + "winner": null +} +``` + +--- + +## 6. Initialization Rules + +- **Deck Composition:** + - Number cards: `Num_1`–`Num_10`, each duplicated twice. + - Trick cards: `Trick_1`–`Trick_5`. + - One `Crown_Joker`. + Total = 26 cards. +- **Initial Hands:** Each player draws 3 cards from the shuffled deck. +- **Seed Control:** + A provided or default integer seed initializes the deterministic shuffle. +- **Onboarding Observation:** + Introduces theme, player roles, and first 3 cards each player holds. + +--- + +## 7. Validation and Error Handling + +When validating extracted action content: + +- **Unrecognized pattern:** + → `set_invalid_move("Unrecognized action format")` +- **Invalid card reference:** + → `set_invalid_move("Card not in hand")` +- **Prohibited discard of Joker:** + → `set_invalid_move("Cannot discard the Crown Joker")` +- **Premature ‘Crown’ declaration (before turn 5):** + → `set_invalid_move("Crown can only be declared after turn 5")` +- **Deck empty when trying to draw:** + → `set_invalid_move("Deck empty; cannot draw")` + +Each invalid move triggers an immediate loss for the acting player (to discourage random token submissions). + +--- + +## 8. Terminal Conditions and Scoring + +**Terminal checks each turn:** +1. `[Crown]` declared → reveal both hands. +2. Deck exhausted → automatic reveal. +3. Turn counter ≥ 30 → automatic reveal. + +**Scoring rule:** +- Each `Num_X` value contributes its digit. +- Each `Trick_X` doubles another card of the same digit value. +- The `Crown_Joker` adds +5 to total and breaks ties. + +**Decision:** +- Highest total wins; ties broken by possession of Joker; otherwise draw. + +--- + +## 9. Player Prompt Specification + +### Prompt Outline + +**Identity Blurb:** +> You are a jester in the royal court, dueling your rival by drawing and playing cards to earn the court’s applause. Gather the highest hand value before your opponent declares “Crown”! + +**Action Instructions:** +> You must select exactly **one action each turn** using the bracketed tokens below: +> - `[Draw]` – take the top card from the deck +> - `[Play:]` – apply a card’s effect +> - `[Discard:]` – remove a unwanted card (not Joker) +> - `[Pass]` – skip +> - `[Crown]` – declare your confidence and end the round + +> Put your final answer within `\boxed{{}}` at the end of your response. + +**Example valid response:** +``` +I need to strengthen my hand first. +\boxed{{[Draw]}} +``` + +**Example invalid response:** +``` +I choose DrawCard. +\boxed{{[DrawCard]}} +``` + +**Implementation Helper:** +- `_extract_answer_content(self, action: str) -> str` must extract only the contents within `\boxed{{}}`. + +Players are encouraged to include reasoning before their boxed token, but only the token itself is parsed as the action command. + +--- + +## 10. API Mapping Plan + +| API Method | Purpose | Reads/Writes | Terminal Logic | +|-------------|----------|--------------|----------------| +| **reset(seed)** | Initializes deck using deterministic shuffle; deals hands; resets counters and history. | Writes entire `game_state`. | Sets `terminal=false`, `winner=null`. | +| **step(player_action)** | Extracts boxed contents, validates grammar and legality, executes turn effects. | Reads: `current_player`, hands, deck. Writes: `history`, `hands`, `discard_pile`, `turn_index`. | After action, checks terminal conditions; sets `winner` or marks draw. | +| **_generate_player_prompt()** | Builds a textual observation containing: current turn, visible discard pile top, hand summary, and rules. | Reads: `game_state`; may embed last few transcript lines. | None; just generates prompt text. | + +--- + +## 11. Copy-check Against the Example + +This design is **completely original** and **not derived** from any negotiation or trading scenario. +- **Theme:** whimsical court card duel. +- **Resources:** cards (numbers, tricks, joker), not goods or proposals. +- **Objectives:** achieve high hand value, not mutual agreement. +- **State Keys:** e.g., `"deck_order"`, `"discard_pile"`, `"has_joker"` — all unique to this design. +- **Prompt and grammar:** completely new and unrelated to negotiation format. + +This document therefore satisfies the independence, determinism, and structural clarity required for future TextArena implementation. \ No newline at end of file