🥋 Zoorkhane Fighter — AI Agent Project

This project implements an AI agent for a two-player fighting game called Pixel Warrior / Zoorkhane Fighter. Two agents compete in real-time combat, each starting with 100 HP. The first agent to reduce the opponent's HP to zero wins. Each agent is an independent program that receives the current game state as JSON input and returns an action as JSON output every frame.

The project explores adversarial AI techniques, specifically Minimax search with alpha-beta pruning and heuristic evaluation functions, to build a competitive fighting game agent.

.
├── GAMECODE-python.py   # Main game loop and rendering (Pygame)
├── fighter.py           # Fighter class — handles animation, physics, agent I/O
├── agent.py             # Primary AI agent (Minimax + heuristic)
├── random-agent.py      # Secondary agent (Markov model + strategy selection)
├── health_bar.png       # HUD asset
├── p1.png               # Player 1 victory screen
├── p2.png               # Player 2 victory screen
└── README.md

Additional required assets (backgrounds, character spritesheets, fonts, sounds) must be present in their respective folders.

The main game (GAMECODE-python.py) runs at 60 FPS using Pygame. Each frame, it calls Fighter.move() for both fighters. For AI-controlled fighters, the fighter class serializes the current game state to JSON, pipes it to the agent script via subprocess, and reads back the chosen action.

The game supports three modes, configurable via game_mode in GAMECODE-python.py:

Each agent reads a JSON object from stdin and writes a JSON action to stdout.

Input:

{
  "fighter": {
    "x": int,
    "y": int,
    "health": int,
    "attacking": bool,
    "attack_cooldown": [int, int],
    "jump": bool,
    "dash_cooldown": int
  },
  "opponent": {
    "x": int,
    "y": int,
    "health": int,
    "attacking": bool
  },
  "saved_data": {}
}

Output:

{
  "move": "left" | "right" | null,
  "attack": 1 | 2 | null,
  "jump": bool,
  "dash": "left" | "right" | null,
  "debug": any,
  "saved_data": {}
}

saved_data persists across frames and can be used to store any state your agent needs between calls.

The primary agent uses Minimax search with alpha-beta pruning (depth 3) to select the best action each frame.

Key components:

• assess_position(fighter, opponent) — Heuristic evaluation function. Scores a game state based on:

  • Health differential (highest weight)
  • Distance to opponent (attack range pressure)
  • Attack cooldown readiness
  • Vertical alignment (both on ground vs. one in air)
  • Position on screen (penalizes corner positioning)

• simulate_action(fighter, opponent, action, is_fighter_turn) — Simulates the effect of a single action without modifying actual game state.

• minimax(fighter, opponent, depth, is_maximizing, alpha, beta) — Standard minimax with alpha-beta pruning. The maximizing player is the agent; the minimizing player is the opponent.

• choose_best_move(fighter_info, opponent_info, saved_data) — Entry point. Evaluates all legal actions and returns the one with the highest minimax score.

Available actions considered:
MOVE_FORWARD, MOVE_BACKWARD, ATTACK, HEAVY_ATTACK, DASH_FORWARD, DASH_BACKWARD, JUMP_IN_PLACE

The secondary agent uses a Markov model to predict opponent behavior and adapts its strategy dynamically.

Key components:

• Opponent modeling: Tracks action transition probabilities to predict the opponent's next move.
• Strategy selection: Chooses between aggressive, defensive, counter, press, or balanced based on health differential and opponent aggression score.
• Dodge logic: With 80% probability, attempts to dodge predicted attacks via dash or jump.
• Optimal positioning: Calculates ideal distance from the opponent based on current strategy.

pip install pygame numpy

python GAMECODE-python.py

To change which agent file is used, edit the agent1_info or agent2_info dictionaries in GAMECODE-python.py:

agent1_info = {
    'enabled': True,
    'language': 'python',
    'path': os.path.join(os.path.dirname(__file__), 'agent.py')
}

game_mode = "ai_vs_ai"       # AI vs AI
# game_mode = "player_vs_ai" # Human vs AI
# game_mode = "pvp"          # Human vs Human

A good heuristic balances multiple factors. The general form used in agent.py:

score = (health_diff × w1) + (range_advantage × w2) + (cooldown_bonus × w3) − (corner_penalty × w4) − ...

Weights were tuned empirically. Key insights:

• Health difference is the dominant term.
• Being in attack range with a ready cooldown is highly rewarded.
• Being cornered is strongly penalized.
• Vertical misalignment (one fighter in air, one on ground) is penalized as attacks miss.

Minimax at depth 3 with alpha-beta pruning significantly reduces the search space. The opponent is modeled conservatively (assumes it plays optimally from a subset of moves), while the agent considers its full action space.

• Each agent call must complete within 0.4 seconds or the frame is skipped.
• If the agent crashes, the fighter loses by default.
• saved_data must be JSON-serializable.
• Agents do not share state — each runs as a separate subprocess.