honey-heist-battle/environment.md

Game Design Document: Honey Heist: Battle of the Bears

---

1. Concept Paragraph

Honey Heist: Battle of the Bears is a deterministic, turn-based strategy game where two rival bears compete in a forest clearing to collect the most honey from a shared hive before it is depleted. Each bear must decide whether to forage, defend, or steal on its turn, balancing risk against reward. The environment features a finite supply of honey, and both bears act in partial opposition — every move affects the shared resource and their honey stores.
This design is entirely unrelated to any negotiation or trading game. It focuses instead on resource competition and strategic timing in an original woodland theme.

---

2. Roles and Win Condition

• Players: Two rival bears: Bear A and Bear B.
• Objective: End the game with more honey than the opponent when the hive is empty or the maximum number of turns is reached.
• Win Condition:
  • Win: A bear has more honey than the other at the end of the game.
  • Loss: A bear has less honey than the other when the game ends.
  • Draw: Both bears have equal honey at game end.

---

3. Turn Structure and Determinism

• The game proceeds in alternating turns beginning with Bear A.
• On each turn, the current player submits one valid action token.
• Each turn’s outcome is deterministic, derived exclusively from the game state and player actions.
• The game lasts until either:
  1. The hive’s honey reaches 0, or
  2. A turn limit (default = 10 rounds per bear, 20 turns total) is reached.
• A fixed seed ensures deterministic replay: the hive’s starting honey and any numeric parameters (like attack/defense outcomes) are seeded and reproducible.

---

4. Action Grammar (Machine-Parseable)

Allowed Player Actions

Action Token	Pattern Format	Description
[Forage:X]	`^[Forage:(?:1	2
[Defend]	^\[Defend\]$	Protect your stored honey; blocks part of a steal attempt this turn.
[Steal:X]	`^[Steal:(?:1	2

Examples

Valid:

• [Forage:2] → Forages 2 honey from hive.
• [Steal:3] → Attempts to steal 3 honey from the opponent.
• [Defend] → Adopts a defensive stance.

Invalid:

• [Forage:5] → Invalid, X must be within 1–3.
• [Steal honey] → Invalid format; must use integer param.
• [Hide] → Invalid token; not part of the grammar.

---

5. Game State Schema

{
  "turn_number": 7,
  "current_player": "BearB",
  "hive_honey": 12,
  "max_turns": 20,
  "players": {
    "BearA": {
      "stored_honey": 9,
      "last_action": "[Forage:2]",
      "defending": false,
      "score": 9
    },
    "BearB": {
      "stored_honey": 10,
      "last_action": "[Steal:3]",
      "defending": false,
      "score": 10
    }
  },
  "history": [
    {"turn":1,"actor":"BearA","action":"[Forage:3]"},
    {"turn":2,"actor":"BearB","action":"[Defend]"},
    {"turn":3,"actor":"BearA","action":"[Steal:2]"}
  ],
  "winner": null,
  "draw": false,
  "seed": 12345
}

---

6. Initialization Rules

• Hive honey starts between 15 and 20, seeded deterministically.
• Stored honey for each player starts at 0.
• Turn number begins at 1, with BearA going first.
• A random seed determines only initial hive honey; all later effects are deterministic.
• On reset(), both players receive initial observations describing:
  • Starting hive size
  • Their honey score (=0)
  • Available action grammar

---

7. Validation and Error Handling

Illegal Actions

The environment validates the extracted content (from within \boxed{}).

Invalid Move Reasons:

1. Action string empty or malformed → "Invalid format, must use [Forage:X], [Steal:X], or [Defend]."
2. X out of range for [Forage:X] or [Steal:X] → "Illegal quantity, X must be 1–3."
3. Attempt to forage more honey than exists in hive → "Not enough honey in hive."
4. Attempt to steal more honey than opponent has → "Opponent has insufficient honey."
5. Action submitted after terminal state → "Game is already over."

When validation fails, the environment triggers set_invalid_move(reason) and ends the turn without effect.

---

8. Terminal Conditions and Scoring

Checked after each pair of turns (full round):

1. Hive depletion: if hive_honey <= 0, game ends.
2. Turn limit: if turn_number > max_turns, game ends.
3. All honey gathered: if total honey = 0 (hive + players), end early.

Scoring:

• Each bear’s score = stored_honey.
• Winner = bear with higher stored_honey.
• Draw if equal.

Tie-breaker: If equal and turns remain, continue until max_turns; if still equal at end → draw.

---

9. Player Prompt Specification

Each player receives a contextual prompt describing their role and the rules:

---

Prompt Outline

You are a hungry bear competing for the last honey in the forest.
- Your goal: End the game with more honey than your rival.
- Each turn, choose ONE of the following actions:
  [Forage:X]  Gather X units (1–3) from the hive.
  [Defend]    Protect your honey from theft this turn.
  [Steal:X]   Steal X units (1–3) from your rival if they do not defend.

Game facts:
- Hive honey remaining: {hive_honey}
- Your stored honey: {player_honey}
- Rival stored honey: {rival_honey}
- Turn {turn_number} / {max_turns}

Format rule:
State your reasoning briefly, then put your final action in the following format at the end:

"Put your final answer within \\boxed{{}} at the end of your response."

Example valid response:
I will risk a quick grab of honey before the hive gets low.
\boxed{{[Forage:3]}}

Example invalid response:
\boxed{{Forage 3}}  <-- Must include brackets and colon.

---

A helper _extract_answer_content(self, action: str) -> str will strip the outer \boxed{} to obtain the core action token for parsing and validation.

---

10. API Mapping Plan

reset(seed)

• Initialize game_state fields as specified.
• Apply seed to determine initial hive_honey.
• Set both stored_honey = 0, defending=False.
• Return the first observation for BearA.

step(action)

• Extract content from player’s input using _extract_answer_content.
• Validate; if illegal, set invalid move and skip reward changes.
• Apply deterministic resolution:
  • [Forage:X]: Reduce hive honey by X, add to player’s store.
  • [Defend]: Set defending=True.
  • [Steal:X]: If opponent.defending=False, transfer min(X, opponent.honey) to current player.
• Reset defending flags at the end of round.
• Increment turn_number, switch current_player.
• Check terminal conditions and set winner/draw if applicable.
• Produce updated observation for next player.

_generate_player_prompt(player_id)

• Inserts current state data into the prompt template (see section 9).
• Explains available actions, format rules, and examples.
• Used each turn to query model actions in deterministic play.

---

11. Copy-Check Against Example

This design—

• Uses bears, honey, and forest resources, not trade, offers, or negotiation.
• Has unique resource names: hive_honey, stored_honey, defending, etc.
• Defines original objectives (collect more honey) and distinct action grammar.
• Uses distinct theme and prompt text centered on competitive foraging bears.

All terminology and game_state keys are purely original to Honey Heist: Battle of the Bears.