{"data":{"kind":"file","path":"README.md","version_id":"ujayvfm6543vboolm9qk2t7y","entry":{"name":"README.md","path":"README.md","is_directory":false,"size":6101,"modified_at":"2025-09-03T16:49:43","content_hash":"abb8d875f0af7df7b7b03b08cc3a38215e9dfd6dbab632c48fe1df32a74564bd"},"entries":[],"content":"# capture-the-flag-game\n\n## Overview\n\n- **Environment ID**: `capture-the-flag-game`\n- **Short description**: A simple turn-based board game where AI models compete to capture the opponent's flag while avoiding being captured themselves.\n- **Tags**: game, board-game, strategy, flag-capture, multi-turn, xml, synthetic, planning\n\n## Game Description\n\nCapture the Flag is a strategic board game played on a square grid where two players compete to capture each other's flag. Each player controls one piece and must protect their own flag while attempting to capture the opponent's flag or piece.\n\n## Game Rules\n\n1. **Board**: Played on a configurable square grid (default: 5x5)\n2. **Players**: Player 1 (AI) vs Player 2 (Environment)\n3. **Setup**: \n   - Player 1's piece starts at top-left (0,0), flag at bottom-right\n   - Player 2's piece starts at bottom-left, flag at top-right\n4. **Movement**: Players alternate turns moving their piece one step horizontally or vertically\n5. **Win Conditions**:\n   - Capture the opponent's flag by moving to its position\n   - Capture the opponent's piece by moving to its position\n6. **Draw Condition**: Game ends in draw after maximum turns (default: 50)\n\n## Board Representation\n\n```\n+---+---+---+---+---+\n| P1|   |   |   | F2|  <- P1=Your piece, F2=Opponent's flag\n+---+---+---+---+---+\n|   |   |   |   |   |\n+---+---+---+---+---+\n|   |   |   |   |   |\n+---+---+---+---+---+\n|   |   |   |   |   |\n+---+---+---+---+---+\n| F1|   |   |   | P2|  <- F1=Your flag, P2=Opponent's piece\n+---+---+---+---+---+\n```\n\n## Expected Response Format\n\nThe model should respond with XML tags indicating the desired move:\n\n```xml\n<move from_row=\"0\" from_col=\"0\" to_row=\"0\" to_col=\"1\"/>\n```\n\n## Scoring System\n\n- **Win**: 100 points\n- **Draw**: 50 points  \n- **Loss**: 0 points\n- **Quick Win Bonus**: +(max_turns - turns_taken) points (up to 20 bonus)\n- **Invalid Move Penalty**: Game ends with 0 points\n\nMaximum possible score: 120 points (normalized to 0-1 range)\n\n## Quickstart\n\nRun an evaluation with default settings:\n\n```shell\nuv run vf-eval capture-the-flag-game\n```\n\nConfigure model and sampling:\n\n```shell\nuv run vf-eval capture-the-flag-game \\\n  -m gpt-4o-mini \\\n  -n 20 -r 3 -t 1024 -T 0.7 \\\n  -a '{\"board_size\": 5, \"max_turns\": 30, \"seed\": 42}'\n```\n\nNotes:\n\n- Use `-a` / `--env-args` to pass environment-specific configuration as a JSON object.\n- Reports are written under `./capture_the_flag_game/reports/` and auto-embedded below.\n\n## Environment Arguments\n\n| Arg | Type | Default | Description |\n|-----|------|---------|-------------|\n| `board_size` | int | `5` | Size of the square board (e.g., 5 for 5x5) |\n| `max_turns` | int | `50` | Maximum number of turns before a draw |\n| `seed` | int | `None` | Random seed for reproducible games |\n| `num_games` | int | `100` | Number of games in the dataset |\n| `player2_strategy` | str | `\"random\"` | Strategy for Player 2 (currently only \"random\") |\n\n## Metrics\n\n| Metric | Meaning |\n|--------|---------|\n| `reward` | Final game score (0-1 normalized) |\n| `turns_taken` | Number of turns played |\n| `game_outcome` | \"win\", \"loss\", or \"draw\" |\n| `valid_moves_made` | Number of valid moves made by the AI |\n\n## Example Game Flow\n\n**Turn 1 (Environment):**\n```\nWelcome to Capture the Flag!\n\nThis is a turn-based strategy game played on a 5x5 board.\n\nRULES:\n- You are Player 1 (P1), I am Player 2 (P2)\n- Each player has one piece and one flag\n- Goal: Capture the opponent's flag by moving your piece to the flag's position\n- You can also win by capturing the opponent's piece\n- Pieces move one step horizontally or vertically (not diagonally)\n- Game ends in a draw after 50 turns\n\nINITIAL BOARD:\n+---+---+---+---+---+\n| P1|   |   |   | F2|\n+---+---+---+---+---+\n|   |   |   |   |   |\n+---+---+---+---+---+\n|   |   |   |   |   |\n+---+---+---+---+---+\n|   |   |   |   |   |\n+---+---+---+---+---+\n| F1|   |   |   | P2|\n+---+---+---+---+---+\n\nMake your first move using this format:\n<move from_row=\"0\" from_col=\"0\" to_row=\"0\" to_col=\"1\"/>\n\nYour turn!\n```\n\n**Turn 2 (Model):**\n```\nI'll start by moving toward the opponent's flag in the top-right corner.\n\n<move from_row=\"0\" from_col=\"0\" to_row=\"0\" to_col=\"1\"/>\n```\n\n**Turn 3 (Environment):**\n```\nTurn 1: You moved to (0,1). I moved to (3,0).\n\nCURRENT BOARD:\n+---+---+---+---+---+\n|   | P1|   |   | F2|\n+---+---+---+---+---+\n|   |   |   |   |   |\n+---+---+---+---+---+\n|   |   |   |   |   |\n+---+---+---+---+---+\n| P2|   |   |   |   |\n+---+---+---+---+---+\n| F1|   |   |   |   |\n+---+---+---+---+---+\n\nYour turn! Make your next move.\n```\n\n## Strategy Tips\n\n- **Offensive**: Move directly toward the opponent's flag\n- **Defensive**: Block the opponent's path to your flag\n- **Balanced**: Advance while maintaining defensive positioning\n- **Piece Capture**: Sometimes capturing the opponent's piece is easier than reaching their flag\n\n## Installation\n\nThis environment is designed to be installed as part of the Prime Intellect environments collection:\n\n```shell\n# Install from the environments hub\nprime env install username/capture-the-flag-game\n\n# Or install locally for development\ncd capture_the_flag_game\nuv pip install -e .\n```\n\n## Development\n\nTo contribute to this environment:\n\n1. Clone the repository\n2. Install in development mode: `uv pip install -e .`\n3. Run tests: `python test_environment.py`\n4. Make your changes\n5. Test thoroughly with different configurations\n6. Submit a pull request\n\n## Future Enhancements\n\nPotential improvements for future versions:\n\n- **Advanced AI Strategies**: Implement minimax or other strategic algorithms for Player 2\n- **Larger Boards**: Support for different board sizes and configurations\n- **Multiple Pieces**: Allow each player to control multiple pieces\n- **Obstacles**: Add walls or barriers to increase strategic complexity\n- **Power-ups**: Special abilities or temporary advantages\n- **Tournament Mode**: Multi-game tournaments with ranking\n\n## License\n\nMIT License - see the LICENSE file for details.\n\n## Evaluation Reports\n\nNo reports found. Run `uv run vf-eval capture-the-flag-game -a '{\"key\": \"value\"}'` to generate one.\n\n","encoding":"utf-8","truncated":false,"total_bytes":6101},"status":null}