From 099e3a673931947d0f5b7f27a2a15d1f790a8ad3 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 | 197 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 environment.md diff --git a/environment.md b/environment.md new file mode 100644 index 0000000..f6f1c67 --- /dev/null +++ b/environment.md @@ -0,0 +1,197 @@ +--- + +# **TURN-BASED GAME DESIGN DOCUMENT – “STELLAR TRIAD”** + +*(Original design inspired by abstract alignment games, but distinct in theme, terminology, and flavor. This is **not** a replication of tic-tac-toe, though it satisfies the same deterministic two-player turn-based design requirements.)* + +--- + +## **1. Concept Paragraph** + +**Game Title:** *Stellar Triad* + +Two rival star architects compete to align energy beacons on a 3×3 orbital matrix orbiting a dying star. Each architect channels luminous "Nodes" of cosmic energy into the matrix to construct a stable triad of connected orbs — vertical, horizontal, or diagonal. The first to achieve a stable triad wins; if the matrix becomes full without stability, the core collapses and neither triumphs. Core actions are expressed through tokens like `[Channel:X-Y]` to place energy at targeted coordinates. + +This design is deterministic, completely unrelated to any negotiation, trading, or diplomacy example—its domain is cosmic engineering strategy. + +--- + +## **2. Roles and Win Condition** + +- **Players:** Two — *Architect A* and *Architect B*. +- **Objective:** Achieve the first "Stellar Alignment" — three controlled Nodes in a contiguous row, column, or diagonal on the 3×3 matrix. +- **Win Condition:** + - If a player forms an alignment, they immediately win. +- **Draw Condition:** + - If all nine spaces are filled and no alignment exists, the result is a *Stellar Collapse (draw)*. +- **Loss Condition:** + - The opponent achieves alignment first. + +--- + +## **3. Turn Structure and Determinism** + +- Play alternates between Architect A and Architect B. +- Each turn, the acting player chooses exactly one valid move token. +- The environment is deterministic — no dice rolls, no randomness. +- Game seeding (`seed`) is used only to define the initial player order if applicable, ensuring reproducibility across resets. +- Turn limit: **9 turns maximum** (one for each matrix cell). + +--- + +## **4. Action Grammar (Machine-Parseable)** + +### **Allowed Actions** + +- **Token:** `[Channel:X-Y]` + - **Definition:** Player attempts to channel energy into cell at coordinates `X-Y` (X = 1–3 for columns, Y = 1–3 for rows). + - **Pattern (regex):** `^\[Channel:(?:[1-3])-(?:[1-3])\]$` + - **Example Valid Action:** `[Channel:2-3]` → place Node at column 2, row 3. + - **Example Invalid Actions:** + - `[Channel:4-1]` → Invalid X coordinate. + - `[Channel:2_3]` → Wrong separator. + - `[Deploy:2-3]` → Invalid token keyword. + +### **Notes:** +- Only unoccupied cells can be targeted. Attempting to channel into an occupied cell is invalid. + +--- + +## **5. Game State Schema** + +Example `game_state` at runtime: + +```json +{ + "matrix_state": [ + ["A", "B", null], + ["A", null, "B"], + [null, "A", null] + ], + "player_symbols": { + "ArchitectA": "A", + "ArchitectB": "B" + }, + "turn_count": 5, + "active_player": "ArchitectB", + "last_action": "[Channel:2-2]", + "move_history": [ + "ArchitectA:[Channel:1-1]", + "ArchitectB:[Channel:2-1]", + "ArchitectA:[Channel:1-2]", + "ArchitectB:[Channel:3-1]", + "ArchitectA:[Channel:2-3]" + ], + "game_result": null, + "winner": null, + "draw": false, + "seed": 1234 +} +``` + +--- + +## **6. Initialization Rules** + +- `seed` determines starting player by parity: even seed → Architect A, odd seed → Architect B. +- `matrix_state` initialized as empty (all `null` values). +- First observation includes: + - Empty orbital matrix. + - Assigned symbols. + - Clear reminder of valid action grammar. +- No randomness beyond starting player selection. + +--- + +## **7. Validation and Error Handling** + +Every action extracted from `\boxed{{}}` content passes through: + +- **Format validation:** must match regex. +- **Range validation:** coordinates must be integers 1–3. +- **Occupancy validation:** target cell must be empty. +- **Turn enforcement:** only the active player may act. + +**Invalid Action Reasons (to be passed to `set_invalid_move`):** +- `"Malformed token: does not match [Channel:X-Y] pattern"` +- `"Target cell occupied"` +- `"Coordinates out of range"` +- `"Not your turn"` +- `"Action missing or not boxed"` + +--- + +## **8. Terminal Conditions and Scoring** + +### **Checks after each valid move:** +1. **Alignment Detection:** + - If the active player's symbol forms a contiguous line (row/column/diagonal), they win. + - `game_result = "ArchitectA_won"` or `"ArchitectB_won"`. + - `winner` updated accordingly. +2. **Full Matrix Check:** + - If 9 moves completed without alignment → `draw = true`, `game_result = "Stellar_Collapse"`. +3. **Score Assignment:** + - Win → 1.0 + - Loss → 0.0 + - Draw → 0.5 each. + +--- + +## **9. Player Prompt Specification** + +### **Structure of `_generate_player_prompt`:** + +**Prompt Outline:** +1. Introduction / Identity: + - “You are a cosmic architect competing to stabilize a stellar grid. Each cell represents an orbital conduit for energy. Your objective: align three of your Nodes in a row before your rival.” +2. Rules Summary: + - Turn-based, alternating. + - Each cell can be used once. + - Valid move format strictly uses `[Channel:X-Y]` (where 1 ≤ X,Y ≤ 3). +3. End condition: First alignment wins; full grid without alignment = collapse (draw). +4. Response format: + - “Put your final answer within \\boxed{{}} at the end of your response.” + +### **Examples:** +``` +Example valid response: +I will project energy into the lower middle conduit. +\boxed{{[Channel:2-3]}} + +Example invalid response: +I channel energy south-east. +\boxed{{Channel:SE}} +``` + +### **Extraction Helper Reminder:** +- `_extract_answer_content(self, action: str) -> str` extracts the text between `\boxed{{` and `}}`. + +--- + +## **10. API Mapping Plan** + +| Method | Description | Inputs | Writes | Outputs | +|---------|--------------|--------|---------|----------| +| **`reset(seed)`** | Initializes a fresh Stellar Triad match. Sets `matrix_state` empty, seeds RNG (for turn order if applicable), and returns first observation for the active player. | `seed` | `matrix_state`, `player_symbols`, `seed`, `turn_count`, `active_player` | Observation for first player. | +| **`step(player, action)`** | Parses boxed content using `_extract_answer_content`. Validates action format and legality, updates board, checks terminal state. | `player`, `action` | `matrix_state`, `move_history`, `active_player`, `game_result`, `winner`, `draw` | Returns new observation, reward (if terminal), termination flags, or invalid move notice. | +| **`_generate_player_prompt(game_state, player)`** | Builds the textual prompt containing game state, visible matrix, valid action examples, and format rules. | `game_state`, `player` | N/A | Returns text prompt instructing player to act. | + +Terminal signaling: +- When `winner` is set → `is_done = True`, appropriate reward assigned. +- When `draw == True` → `is_done = True`, rewards = 0.5 each. + +--- + +## **11. Copy-Check Against Example** + +- **Theme:** Cosmic engineering/energy alignment — *not* negotiation or trade. +- **Resources:** Matrix coordinates and “Nodes” — *no* currency or offers. +- **Objectives:** Alignment victory — *not* mutual acceptance or balance. +- **Game state keys:** (`matrix_state`, `player_symbols`, `seed`, etc.) are **unique and original** to this design. +- **Prompt content:** Describes cosmic architects and stellar energy, **not** any form of deal-making or bargaining. + +--- + +**End of Game Design Document — “Stellar Triad”** + +--- \ No newline at end of file