Agent Programming Contest Platform

This repository hosts the full framework for a 1v1 Agent-vs-Agent battle game, designed for a turn-based programming competition. Participants implement intelligent agents to collect resources, capture power nodes, and defeat opponents in an automated simulation environment.

---

Directory Structure

.
├── agent-contest/                  # Main project directory
│   ├── __pycache__/                # Compiled Python files
│   ├── agents/                     # All agent implementations
│   │   ├── naive.py                # Baseline agent
│   │   ├── smart1.py               # Heuristic-based agent
│   │   ├── smart2.py               # Advanced pathfinding agent
│   │   └── smart4.py               # Q-learning based agent
│   ├── action_handler.py           # Parses and processes agent actions
│   ├── agent.py                    # Defines the base Agent class
│   ├── engine.py                   # Core game engine (handles game loop, turns, scoring)
│   ├── game_state.py               # Maintains map, units, rules, and game logic
│   ├── generate_leaderboard.py     # Aggregates results into leaderboard
│   ├── map_gen.py                  # Utility to generate individual maps
│   ├── parallel_visualizer.py      # Parallel match visualizer
│   ├── pathfinding.py              # Pathfinding utilities (e.g., BFS, A*)
│   ├── tempCodeRunnerFile.py       # Temporary file (VSCode)
│   ├── test_log_gen.py             # Debug script for generating log files
│   ├── tournaments.py              # Runs round-robin tournaments between agents
│   └── visualizer.py               # In-terminal game visualizer
│
├── logs/                           # Stores match logs
│   ├── game_log.json
│   ├── match_*.json                # Individual match logs
│
├── maps/                           # Game map definitions
│   ├── map1.json
│   ├── map2.json
│   └── ...
│
├── AgentDesign.md                  # Mathematical & strategic agent descriptions
├── GameDesign.md                   # Game rules, world design, and mechanics
├── leaderboard.json                # Stores final leaderboard scores
├── Readme.md                     
├── smart4_qtable.json              # Q-learning model data (Q-table for smart4)
└── tournament_results.json         # Tournament results summary

.

---

How to Run a Match

To run a 1v1 match:

python agent-contest/engine.py --map maps/map1.json --agent1 agents.smart1 --agent2 agents.smart2 --log logs/game_log.json

To replay the match:

python agent-contest/visualizer.py logs/game_log.json --delay 0.3 

---

Running a Tournament

To run a round-robin tournament between all agents:

python agent-contest/tournaments.py
python agent-contest/generate_leaderboard.py

This will save results in tournament_results.json and print a leaderboard.

After the tournament do this to clear the records

rm -rf logs/*.json
rm tournament_results.json

---

Agent Descriptions

• naive.py: Randomized and greedy. Baseline agent.
• smart1.py: Heuristic-based, balances gathering and attacking.
• smart2.py: Memory-enabled, multi-turn planning, smart coordination.
• smart4.py: Advanced Q-learning-based bot (with state-action value memory).

All agents implement a get_actions(state) function that returns decisions based on the visible state.

---

Game Design Highlights

• Grid size: 11×11
• Agents: 2 (each controls 2 units)
• Actions: move, gather, attack, scan, wait
• Objectives:
  • Gather 100 energy
  • Eliminate all enemy units
  • Control all power nodes for 5 turns
• Power Nodes: Provide strategic control points
• Resources: Regenerate 3 turns after collection

See full documentation in GameDesign.md

---

Bonus Features

• Parallelized tournament using ProcessPoolExecutor
• Visual health and unit overlays in visualizer.py
• Deterministic log format for replays and evaluation

---

Generate Maps

To create 5 random competitive maps:

python agent-contest/map_gen.py

This will populate the maps/ directory with map1.json, map2.json, etc.

---