testtest9/README.md

GAME DESIGN DOCUMENT — “DUEL OF SIGNS: A ROCK–PAPER–SCISSORS TOURNAMENT”

---

1. Concept Paragraph

Concept:
Duel of Signs is a deterministic, text-based tournament between two contenders — called Signmasters — who compete through successive matches of an expanded Rock–Paper–Scissors variant. The universe is a ceremonial arena where hand-sign duels determine dominance. Each player secretly chooses one of three signs ([Rock], [Paper], [Scissors]) per round. The goal is to win a majority of rounds in a predefined number of matches. Players can also invoke the [Predict:<Sign>] token to gamble on the opponent’s next move for bonus points. This design is entirely unrelated to any negotiation or trading scenario; it contains no resource bargaining, currency, or offers — only symbolic duels and prediction tactics.

---

2. Roles and Win Condition

Roles:

• Player A: Signmaster 1
• Player B: Signmaster 2

Each behaves symmetrically.

Primary Objective:
Earn more tournament points than the opponent after all rounds have concluded.

Scoring:

• Win a duel → +2 points
• Draw a duel → +1 point
• Loss → 0 points
• Correct use of [Predict:<Sign>] (if correct) → +1 bonus point
• Incorrect prediction → −1 penalty point

Decision Rule:
At the end of the final round:

• Higher score → Winner
• Equal scores → Draw

---

3. Turn Structure and Determinism

Each round has two turns (one per player in sequential mode).
The game proceeds through a fixed number of rounds, e.g., 5.
Turn order alternates each round (A starts odd rounds, B starts even).

After both have chosen, the system resolves the duel deterministically:

• Rock beats Scissors
• Scissors beats Paper
• Paper beats Rock
  All scoring and predictions apply deterministically without randomness.

A random seed is used only for reproducibility during environment reset (e.g., for deciding initial starting player or generating tournament metadata). Given the same seed, the entire match sequence will replay exactly.

---

4. Action Grammar (Machine‑Parsable)

4.1 Allowed Action Tokens

Action Type	Token Format	Semantic Meaning
Play Sign	[Play:Rock], [Play:Paper], [Play:Scissors]	Commit to a sign
Predict	[Predict:Rock], [Predict:Paper], [Predict:Scissors]	Attempt to forecast opponent’s next Play sign
Concede	[Concede]	Forfeit the match immediately

4.2 Formal Grammar

Regular expressions (expressed textually):

PLAY_TOKEN = r'^\[Play:(Rock|Paper|Scissors)\]$'
PREDICT_TOKEN = r'^\[Predict:(Rock|Paper|Scissors)\]$'
CONCEDE_TOKEN = r'^\[Concede\]$'

Valid examples:

• ✔ [Play:Rock] → valid play
• ✔ [Predict:Paper] → valid prediction

Invalid examples:

• ❌ [Play: Stones] → invalid sign (unrecognized subtype)
• ❌ [PredictPaper] → missing colon and brackets, invalid format
• ❌ [yield] → token not in allowed action set

---

5. Game State Schema

{
  "tournament_name": "Grand Duels 2077",
  "seed": 123,
  "round_index": 3,
  "max_rounds": 5,
  "turn_order": ["PlayerA", "PlayerB"],
  "players": {
    "PlayerA": {
      "score": 5,
      "last_action": "[Play:Rock]",
      "predicted_action": "[Predict:Paper]",
      "round_wins": 2
    },
    "PlayerB": {
      "score": 4,
      "last_action": "[Play:Scissors]",
      "predicted_action": null,
      "round_wins": 1
    }
  },
  "round_history": [
    {
      "round": 1,
      "PlayerA_action": "[Play:Rock]",
      "PlayerB_action": "[Play:Paper]",
      "winner": "PlayerB"
    },
    {
      "round": 2,
      "PlayerA_action": "[Predict:Scissors]",
      "PlayerB_action": "[Play:Scissors]",
      "winner": "Draw"
    }
  ],
  "current_turn": "PlayerB",
  "status": "active",
  "winner": null,
  "observation_log": [
    "Round 1: PlayerA played Rock; PlayerB played Paper → PlayerB wins.",
    "Round 2: PlayerA predicted Scissors correctly."
  ]
}

---

6. Initialization Rules

• Seed: A reproducible integer input for deterministic setup.
• Starting Player: Chooses first mover by fixed or seeded rule (e.g., even seed → PlayerA starts).
• Scores & History: Zeroed at start.
• Observations: Each player receives an opening message:
  • Tournament title
  • Number of rounds
  • Their player role (A or B)
  • Reminder of available actions and scoring system.

---

7. Validation and Error Handling

When an action is received (content extracted from inside \boxed{}):

Validation Steps:

1. Confirm the format matches one of the regex tokens.
2. Confirm it’s the player’s turn.
3. Ensure they haven’t already played a [Play:*] or [Predict:*] in this round (disallow duplicates).
4. If [Concede], mark immediate terminal outcome.

Invalid Move Reasons:

• “Unrecognized token format.”
• “It is not your turn.”
• “Duplicate action this round.”
• “Concession not allowed after round resolution.”

If invalid, set_invalid_move(player, reason) will be triggered and the opponent automatically wins the match.

---

8. Terminal Conditions and Scoring

Terminal checks per turn:

1. If both players have legal [Play:*] actions, resolve round outcome:
   • Update scores
   • Record to round_history
   • Increment round_index
2. If [Concede] action is made → opponent receives instant win
3. If round_index > max_rounds → tournament ends

Endgame Scoring:

• winner = player with higher score
• if equal → "Draw"

Tie‑breakers (if desired extension):
If tied, compare number of individual round wins; if still tied, declare draw.

---

9. Player Prompt Specification

Prompt Identity Blurb:

You are a Signmaster in the grand arena of Duel of Signs. Each round, you must choose a hand sign to defeat your opponent or attempt a daring prediction for extra points.

Prompt Contents:

• Current round, scores, and last known actions.
• Reminder of valid action format and consequences.
• Scoring recap.
• End instruction:
  “Put your final answer within \boxed{} at the end of your response.”

Allowed Actions:

[Play:Rock]
[Play:Paper]
[Play:Scissors]
[Predict:Rock]
[Predict:Paper]
[Predict:Scissors]
[Concede]

Example Valid Response:

I think Paper will protect me from Rock.
\boxed{[Play:Paper]}

Example Invalid Response:

I choose to play paper.
\boxed{PlayPaper}

→ invalid because brackets and colon missing.

Helper extraction rule:
\_extract_answer_content(self, action: str) -> str
Parses text inside \boxed{} and returns only the internal token string for validation and step logic.

---

10. API Mapping Plan

API Method	Purpose	Reads / Writes	Outcome
reset(seed=None)	Initialize tournament state using provided or default seed. Create base observations and metadata.	Writes: seed, tournament_name, round_index=1, players fields.	Returns initial observation to both players.
step(player_action)	Process one player’s turn. Validate syntax and legality. Update game state accordingly. If round complete, compute duel result.	Reads: current_turn, players[...], round_history. Writes: scores, round_index, winner, status.	Returns new observations, and signals win/draw when terminal.
_generate_player_prompt(player_id)	Builds contextual textual prompt per player at their turn. Displays current scores, allowed tokens, round state, and format examples.	Reads: full game_state.	Returns formatted text prompt for model or user.

---

11. Copy‑Check Against the Example

• Theme & Objective: Completely distinct — ceremonial hand‑sign duels rather than negotiation or trading.
• Entities & Resources: Signs, rounds, scores; no goods, offers, or currencies.
• Prompt Text: Focused on symbolic combat, prediction bonuses, and deterministic scoring.
• Game State Keys: (tournament_name, round_index, round_history, predicted_action, round_wins, etc.) — all unique to this design.

---

End of “Duel of Signs” Game Design Document