pokemon-battle-engine/tools/data/README.md

Pokemon Data Tools

This directory contains tools for downloading and processing Pokemon data from the PokeAPI.

Pokemon Downloader (pokemon_downloader.py)

A comprehensive tool for downloading generation-specific Pokemon data from the PokeAPI.

Features

• Type Effectiveness: Downloads type matchup charts for each generation
• Pokemon Data: Downloads Pokemon species data including stats, types, and abilities
• Moves Data: Downloads move information filtered by generation availability
• Progress Tracking: Uses progress bars and detailed logging
• Error Handling: Robust error handling with retry logic
• Flexible Output: Configurable output directory structure

Usage

Basic Usage

# Download all data for all generations
python pokemon_downloader.py --all-generations --all-data-types

# Download specific generations and data types
python pokemon_downloader.py --generations generation-i,generation-ii --data-types types,pokemon

# Download only type effectiveness for Generation I
python pokemon_downloader.py --generations generation-i --data-types types

Command Line Options

• --generations: Comma-separated list of generations (generation-i, generation-ii, etc.)
• --all-generations: Download data for all available generations
• --data-types: Comma-separated list of data types (types, pokemon, moves)
• --all-data-types: Download all data types
• --output-dir: Output directory (default: data)

Examples

# Download Pokemon and moves for Generation I and II
python tools/data/pokemon_downloader.py \
    --generations generation-i,generation-ii \
    --data-types pokemon,moves \
    --output-dir data

# Download all type effectiveness data
python tools/data/pokemon_downloader.py \
    --all-generations \
    --data-types types

Output Structure

The tool creates the following directory structure:

data/
├── types/
│   ├── generation-i.json
│   ├── generation-ii.json
│   └── ...
├── pokemon/
│   ├── generation-i.json
│   ├── generation-ii.json
│   └── ...
└── moves/
    ├── generation-i.json
    ├── generation-ii.json
    └── ...

Data Formats

Type Effectiveness (types/generation-X.json)

{
  "fire": {
    "double_damage_from": ["water", "ground", "rock"],
    "double_damage_to": ["grass", "ice", "bug", "steel"],
    "half_damage_from": ["fire", "water", "rock", "dragon"],
    "half_damage_to": ["fire", "water", "rock", "dragon"],
    "no_damage_from": ["fire"],
    "no_damage_to": ["fire"]
  }
}

Pokemon Data (pokemon/generation-X.json)

[
  {
    "id": 1,
    "name": "bulbasaur",
    "types": ["grass", "poison"],
    "stats": {
      "hp": 45,
      "attack": 49,
      "defense": 49,
      "special-attack": 65,
      "special-defense": 65,
      "speed": 45
    },
    "abilities": [...],
    "species": {
      "generation": "generation-i",
      "is_legendary": false,
      "is_mythical": false
    }
  }
]

Moves Data (moves/generation-X.json)

[
  {
    "id": 1,
    "name": "pound",
    "power": 40,
    "pp": 35,
    "accuracy": 100,
    "type": "normal",
    "damage_class": "physical",
    "generation": "generation-i"
  }
]

Dependencies

The tool requires the following Python packages (available in tools/requirements.txt):

• requests - HTTP requests to PokeAPI
• tqdm - Progress bars
• argparse - Command line argument parsing (built-in)

API Rate Limiting

The tool includes:

• Retry logic with exponential backoff
• Respectful request timing
• User-agent identification
• Error handling for rate limits

New Features (Latest Update)

Efficient Moves Download:

• Downloads all moves once and saves to data/all_moves.json
• Subsequent generations filter from this master file instead of re-downloading
• Dramatically reduces API calls and download time

Smart Caching:

• Checks if data files already exist and contain expected amount of data
• Skips re-downloading if files are present and valid
• Supports partial downloads (e.g., if some Pokemon are missing, only downloads missing ones)

File Structure:

data/
├── all_moves.json          # Complete moves database (all generations)
├── types/
│   ├── generation-i.json   # Type effectiveness for each generation
│   ├── generation-ii.json
│   └── ...
├── pokemon/
│   ├── generation-i.json   # Pokemon data for each generation
│   ├── generation-ii.json
│   └── ...
└── moves/
    ├── generation-i.json   # Moves available in each generation
    ├── generation-ii.json  # (filtered from all_moves.json)
    └── ...

Performance Improvements

• Moves: Downloads all 900+ moves once, then filters per generation
• Caching: Checks file existence and validity before downloading
• Batch Processing: Downloads complete datasets efficiently
• Resume Support: Can continue interrupted downloads

Usage Examples with Caching

# First run - downloads all data
python tools/data/pokemon_downloader.py --all-generations --all-data-types

# Subsequent runs - uses cached data (much faster!)
python tools/data/pokemon_downloader.py --all-generations --all-data-types

# Only downloads missing data
python tools/data/pokemon_downloader.py --generations generation-v --data-types pokemon

Notes

• Some Pokemon and moves appear in multiple generations
• Type effectiveness is consistent across generations in the base game
• The tool respects the PokeAPI fair use policy
• Data is cached locally to avoid repeated API calls
• all_moves.json contains the complete moves database for efficient filtering