Add environment documentation from Openverse builder
This commit is contained in:
Openverse Builder
231
environment.md
Normal file
231
environment.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# **TextArena Game Design Document: “Runic Grid”**
|
||||
|
||||
*(Design stage only – no code yet)*
|
||||
This design invents an original game, **Runic Grid**, inspired structurally by turn-based spatial strategy but **completely distinct** in theme, background, and terminology from any tic-tac-toe or negotiation examples.
|
||||
|
||||
---
|
||||
|
||||
## 1. Concept Paragraph
|
||||
|
||||
In **Runic Grid**, two rival mystics, the **Solar Scribe** and the **Lunar Scribe**, compete to inscribe magical runes onto a sacred 3×3 **Runic Tablet**. Each cell of the Tablet can bear only one rune, either a **Sun Rune (☼)** or a **Moon Rune (☽)**. The goal is to channel divine alignment by creating a continuous triad of your own rune horizontally, vertically, or diagonally before your opponent does. This design has no themes of trade, debate, or negotiation—it is a deterministic puzzle duel of pattern claiming. The core actions are **[Inscribe:x,y]**, where each player selects a tile to mark on their turn.
|
||||
|
||||
---
|
||||
|
||||
## 2. Roles and Win Condition
|
||||
|
||||
- **Players**:
|
||||
- Player 1: *Solar Scribe* (places **Sun Runes, ☼**)
|
||||
- Player 2: *Lunar Scribe* (places **Moon Runes, ☽**)
|
||||
|
||||
- **Win Condition**:
|
||||
A player wins immediately upon forming three of their runes in a continuous line—horizontal, vertical, or diagonal—on the Runic Tablet.
|
||||
|
||||
- **Loss Condition**:
|
||||
The opponent achieves a triad alignment first.
|
||||
|
||||
- **Draw Condition**:
|
||||
All nine cells are occupied with no winning triad.
|
||||
|
||||
---
|
||||
|
||||
## 3. Turn Structure and Determinism
|
||||
|
||||
- Turns alternate between Solar and Lunar Scribe starting with Solar Scribe.
|
||||
- One action per turn.
|
||||
- Deterministic: No randomness; the entire environment is reproducible from the same sequence of moves and initial seed.
|
||||
- Maximum turn count: **9** (since there are 9 cells).
|
||||
- Each step is deterministic; random seed affects only initial player ordering if randomized (optional).
|
||||
|
||||
---
|
||||
|
||||
## 4. Action Grammar (Machine-Parseable)
|
||||
|
||||
**Allowed Action Format**:
|
||||
Each player submits an action inside `\boxed{{}}`.
|
||||
Inside the braces, the content must follow one of the following patterns:
|
||||
|
||||
### 4.1 `[Inscribe:x,y]`
|
||||
|
||||
Places the player's rune at coordinates `(x, y)` on the 3×3 Runic Tablet.
|
||||
|
||||
- **Pattern**:
|
||||
```
|
||||
^\[Inscribe:(?:[0-2]),(?:[0-2])\]$
|
||||
```
|
||||
where `x` and `y` are integers 0, 1, or 2 representing row and column indexes.
|
||||
|
||||
- **Interpretation**:
|
||||
(0,0) = top-left, (2,2) = bottom-right.
|
||||
|
||||
- **Example Valid Action**:
|
||||
```
|
||||
[Inscribe:1,2]
|
||||
```
|
||||
→ Marks the middle-right cell.
|
||||
|
||||
- **Example Invalid Action**:
|
||||
```
|
||||
[draw:1,2]
|
||||
```
|
||||
→ Invalid because the verb “draw” does not match required token “Inscribe”.
|
||||
|
||||
Another invalid example:
|
||||
```
|
||||
[Inscribe:3,0]
|
||||
```
|
||||
→ Invalid because coordinate 3 is outside permitted range 0–2.
|
||||
|
||||
**Only one grammar token exists**; the rest of the system enforces availability, legality, and turn order.
|
||||
|
||||
---
|
||||
|
||||
## 5. Game State Schema
|
||||
|
||||
Full run-time `game_state` example:
|
||||
|
||||
```json
|
||||
{
|
||||
"turn_count": 4,
|
||||
"current_player": "Solar Scribe",
|
||||
"board": [
|
||||
["☼", "☽", null],
|
||||
[null, "☼", null],
|
||||
["☽", null, null]
|
||||
],
|
||||
"players": {
|
||||
"Solar Scribe": {
|
||||
"symbol": "☼",
|
||||
"actions": ["[Inscribe:0,0]", "[Inscribe:1,1]"]
|
||||
},
|
||||
"Lunar Scribe": {
|
||||
"symbol": "☽",
|
||||
"actions": ["[Inscribe:0,1]", "[Inscribe:2,0]"]
|
||||
}
|
||||
},
|
||||
"winner": null,
|
||||
"outcome": "ongoing",
|
||||
"observations": [
|
||||
{"player": "Solar Scribe", "action": "[Inscribe:0,0]"},
|
||||
{"player": "Lunar Scribe", "action": "[Inscribe:0,1]"},
|
||||
{"player": "Solar Scribe", "action": "[Inscribe:1,1]"},
|
||||
{"player": "Lunar Scribe", "action": "[Inscribe:2,0]"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Initialization Rules
|
||||
|
||||
- The board initializes as a 3×3 matrix of `null`.
|
||||
- Turn count = 0.
|
||||
- `current_player` defaults to *Solar Scribe*, unless overridden by a deterministic seed-controlled random choice.
|
||||
- No randomness affects board contents.
|
||||
- `game_state["observations"]` starts empty.
|
||||
- At reset, the first observation returned describes player identities, symbol assignments, and available actions.
|
||||
|
||||
---
|
||||
|
||||
## 7. Validation and Error Handling
|
||||
|
||||
On each step, before updating the state:
|
||||
|
||||
1. **Extract content** between `\boxed{{}}` using `_extract_answer_content(action: str) → str`.
|
||||
If missing or malformed, mark move invalid with reason `"Malformed boxed syntax"`.
|
||||
|
||||
2. **Check Regex Pattern**:
|
||||
Must match `^\[Inscribe:[0-2],[0-2]\]$`.
|
||||
If not, invalid with reason `"Action does not match grammar [Inscribe:x,y]"`.
|
||||
|
||||
3. **Check Turn Ownership**:
|
||||
If action comes from incorrect player, invalid with reason `"Action out of turn"`.
|
||||
|
||||
4. **Check Tile Availability**:
|
||||
If the chosen cell is already marked, invalid with reason `"Tile already inscribed"`.
|
||||
|
||||
Invalid actions trigger `set_invalid_move(player, reason)` and the turn passes without board change.
|
||||
|
||||
---
|
||||
|
||||
## 8. Terminal Conditions and Scoring
|
||||
|
||||
**Terminal Checks each turn:**
|
||||
|
||||
1. **Triad Alignment**:
|
||||
After a valid inscription, check all possible lines for three identical rune symbols belonging to the acting player.
|
||||
- If true → `winner = that player`, `outcome = "win"`.
|
||||
2. **Draw**:
|
||||
If the board is full (`9 moves`) and no winner → `outcome = "draw"`.
|
||||
3. **Otherwise** → `outcome = "ongoing"`.
|
||||
|
||||
**Scoring Rules**:
|
||||
- Win: +1 point to the winner, 0 to loser.
|
||||
- Draw: 0 points both sides.
|
||||
|
||||
No fractional or cumulative scoring beyond the single session.
|
||||
|
||||
**Tie-Breaker**: None; draw is final.
|
||||
|
||||
---
|
||||
|
||||
## 9. Player Prompt Specification
|
||||
|
||||
### Prompt Outline for `_generate_player_prompt`
|
||||
|
||||
Identity:
|
||||
> You are a **mystic scribe** engraving the sacred **Runic Tablet** to align divine energies.
|
||||
> On your turn, you use the `[Inscribe:x,y]` action to claim an empty slot on the 3×3 grid.
|
||||
> Your goal: form a continuous line of your rune symbols before your opponent does.
|
||||
|
||||
Rules Recap:
|
||||
- Solar Scribe marks **☼**, Lunar Scribe marks **☽**.
|
||||
- Valid format: `\boxed{{[Inscribe:x,y]}}` where `x` and `y` are 0–2.
|
||||
- You may not inscribe an already-occupied tile.
|
||||
- Example grid coordinate map:
|
||||
```
|
||||
(0,0) (0,1) (0,2)
|
||||
(1,0) (1,1) (1,2)
|
||||
(2,0) (2,1) (2,2)
|
||||
```
|
||||
|
||||
Response Format Requirement:
|
||||
- Provide any reasoning text first.
|
||||
- Conclude with your action token within `\boxed{{}}`.
|
||||
|
||||
### Few-Shot Examples
|
||||
|
||||
```
|
||||
Example valid response:
|
||||
I shall inscribe my rune on the center tile for strength.
|
||||
\boxed{{[Inscribe:1,1]}}
|
||||
|
||||
Example invalid response:
|
||||
I think I will go middle-right.
|
||||
\boxed{{Move:1,2}}
|
||||
```
|
||||
|
||||
Ensure every response ends with exactly one `\boxed{{}}` block containing the action token.
|
||||
|
||||
---
|
||||
|
||||
## 10. API Mapping Plan
|
||||
|
||||
| Method | Purpose | Reads / Writes | Outcome Handling |
|
||||
|---------|----------|----------------|------------------|
|
||||
| **`reset(seed)`** | Initializes `game_state`, applies seed (e.g., random start player if supported), returns initial observation of empty board and player roles. | Sets `turn_count=0`, clears `observations`, resets `winner/outcome`. | Returns observation for both players with board layout and available format instructions. |
|
||||
| **`step(player_id, action)`** | Processes player’s action each turn, updates `board`, verifies legality, appends to `observations`, checks for terminal conditions. | Reads current board, writes updated cell, increments `turn_count`, flips `current_player`. | Returns updated observation, `done` flag if terminal, and optional reward dictionary `{+1,0}`. |
|
||||
| **`_generate_player_prompt(player_id)`** | Constructs human-readable prompt describing game status, coordinates, runes, and legal actions. | Reads entire `game_state` to present board, current turn, valid syntax. | Ensures prompt ends with instruction: *“Put your final answer within \boxed{{}} at the end of your response.”* |
|
||||
|
||||
---
|
||||
|
||||
## 11. Copy-Check Against Example
|
||||
|
||||
- **Theme Check**: Distinct from negotiation example—no trading, communication, or offers.
|
||||
- **Objective Check**: Pattern-alignment on a Runic Tablet vs. any negotiation outcomes.
|
||||
- **Terminology**: Original names—*Runic Tablet*, *Solar Rune*, *Lunar Rune*, *Inscribe*—entirely unique.
|
||||
- **Game state keys**: `"board"`, `"players"`, `"observations"`, `"turn_count"`, `"winner"`, `"outcome"` are original to this schema.
|
||||
- **Prompt and grammar**: Use custom `[Inscribe:x,y]` format unseen in example sources.
|
||||
|
||||
---
|
||||
|
||||
**End of Design Document for “Runic Grid”**
|
||||
Reference in New Issue
Block a user