Pokémon Battle Simulator

A fully interactive Pokémon battle simulator built with PyScript that runs entirely in your browser - no backend, no JavaScript, just pure Python!

Features

• 1300+ Pokémon from all generations pulled via PokeAPI
• Interactive Selection with multiple filters:
  • Search by name
  • Filter by Type 1 and Type 2
  • Filter by Generation (1-9)
  • Toggle Legendary Pokémon
• Turn-based Combat System with:
  • Type effectiveness calculations
  • Speed-based turn order
  • Damage formulas based on Attack/Defense stats
  • Real-time HP tracking with visual health bars
• Detailed Stats Modal showing all Pokémon attributes
• Clean, Responsive UI with type-based color coding
• Sound Effects for attacks and hits
• Pokémon Sprites loaded from PokeAPI

Technologies

This project showcases the power of PyScript - running Python directly in the browser via WebAssembly:

• PyScript - Python in the browser
• Pyodide - CPython compiled to WebAssembly
• Pandas - Data manipulation (running client-side!)
• HTML/CSS - User interface
• PokeAPI Sprites - Pokémon images

Why PyScript?

• Write web apps in pure Python - no JavaScript needed
• Use familiar Python libraries (pandas, numpy, etc.)
• No backend required - all processing happens client-side
• Zero build tools - just open in a browser
• Perfect for prototypes, educational projects, and data-driven demos

Project Structure

pyscript-pokemon-app/
│
├── index.html          # Main HTML structure + PyScript config
├── main.py             # UI logic, event handlers, rendering
├── game_logic.py       # Battle engine, Pokemon class, combat mechanics
├── pokemon.csv         # Complete Pokémon dataset (800+ entries)
├── style.css           # Styling and animations
└── README.md           # This file

Quick Start

Option 1: Open Locally

1. Clone or download this repository
2. Serve the files using any local web server:

# Using Python's built-in server
python -m http.server 8000

# Or using Node.js http-server
npx http-server

# Or using PHP
php -S localhost:8000

3. Open in browser: Navigate to http://localhost:8000
4. Wait for PyScript to load (first load may take ~5-15 seconds as Pyodide initializes)
5. Battle! Select two Pokémon and start battling

Option 2: Deploy to GitHub Pages

1. Push this repo to GitHub
2. Go to Settings → Pages
3. Select source branch → Save
4. Your app is live!

Option 3: Deploy to Netlify/Vercel

Simply drag and drop the project folder - it's all static files!

How to Play

1. Select Your Fighter: Click on a Pokémon card to select your fighter (blue border)
2. Select Your Opponent: Click another Pokémon to select your opponent (red border)
3. Use Filters (optional): Search by name, type, generation, or legendary status
4. View Stats: Click the "i" button on any card to see detailed stats
5. Start Battle: Click "START BATTLE" when both Pokémon are selected
6. Attack: Click "ATTACK" to execute a turn
   • Turn order is determined by Speed stat
   • Damage is calculated using Attack/Defense and type effectiveness
   • Watch HP bars update in real-time
7. Victory: Battle continues until one Pokémon faints
8. Play Again: Click "PLAY AGAIN" to return to selection

How It Works

Data Loading

import pandas as pd

# PyScript loads CSV directly in the browser!
df = pd.read_csv("pokemon.csv")

Battle Mechanics

The battle system implements:

• Type Effectiveness: Fire > Grass > Water > Fire, etc.
• Damage Formula:

  damage = ((attack / defense) * base_power * type_effectiveness) + random_factor

• Speed Priority: Faster Pokémon attacks first each turn
• HP Management: Battle ends when current_hp reaches 0

Python → DOM Interaction

from pyscript import document

# Create and manipulate DOM elements with Python
card = document.createElement("div")
card.innerHTML = f"<h3>{pokemon.name}</h3>"
grid.appendChild(card)

# Event handling in Python!
card.onclick = lambda e: select_pokemon(name)

Dataset

The pokemon.csv contains 800+ Pokémon with attributes:

• Name, Pokedex Number, Generation
• Types (Type 1, Type 2)
• Base Stats: HP, Attack, Defense, Sp. Attack, Sp. Defense, Speed
• Legendary status

Data Source: Compiled from various Pokémon databases

Features Deep Dive

Advanced Filtering

The app provides multi-dimensional filtering:

• Text Search: Real-time name filtering
• Type Filters: Separate filters for primary and secondary types
• Generation Filter: Focus on specific Pokémon generations
• Legendary Toggle: Filter for legendary Pokémon only

All filtering happens client-side using pandas operations.

Stats Modal

Click the info button (i) on any Pokémon to view:

• Full stat breakdown with visual bars
• Type combination
• Scaled stat bars (0-255 range)

Battle Log

Real-time battle commentary showing:

• Who attacks first (based on Speed)
• Attack type used
• Type effectiveness ("It's super effective!" / "Not very effective...")
• Damage dealt
• Current HP after each attack

Customization

Add More Pokémon

Update pokemon.csv with new entries following the same column structure.

Modify Battle Mechanics

Edit game_logic.py to:

• Adjust damage formulas
• Add new attack types
• Implement status effects
• Add abilities

Change Styling

Modify style.css to customize:

• Color schemes
• Type badge colors
• Animations and transitions
• Layout and responsiveness

Add Sound Effects

Replace audio sources in index.html (lines 203-204) with your own sound files.

Limitations

As a PyScript application, be aware of:

• Initial Load Time: 5-15 seconds for first load (Pyodide + dependencies)
• Browser Compatibility: Requires modern browsers with WebAssembly support
• Performance: Slower than native JavaScript for intensive operations
• Package Support: Only packages compiled to WebAssembly (most popular ones work)

Best Used For:

• Prototypes and demos
• Educational projects
• Data visualization tools
• Interactive dashboards
• Small-scale web apps

Not Recommended For:

• Production apps with high traffic
• Performance-critical applications
• Complex SPAs with routing

Development

Prerequisites

• Modern web browser (Chrome, Firefox, Safari, Edge)
• Local web server (optional, but recommended)
• No Python installation needed! (runs in browser)

File Modifications

• UI Changes: Edit index.html and style.css
• Logic Changes: Edit main.py and game_logic.py
• Data Changes: Edit pokemon.csv. Data from this filke was pulled directly from the PokeAPI. Overtime, more Pokemóns may be added. In this case, I might pull that data again and change the pokemon.csv here directly.

Changes will be reflected on page reload (no build step required).

Debugging

Use browser DevTools:

• Console: See Python print() outputs
• Network: Monitor file loading
• Elements: Inspect DOM generated by Python

Learning Resources

Want to learn more about PyScript?

• Official Docs: pyscript.net
• Examples: pyscript.com/@examples
• Community: PyScript Discord
• Pyodide: pyodide.org

Contributing

This is an educational project, but contributions are welcome!

Ideas for improvements:

• Implement special moves with different power levels
• Add status effects (burn, poison, paralysis)
• Implement abilities that modify stats or damage
• Add multiplayer support (WebSockets?)
• Create animations for attacks
• Add sound effects library
• Implement teams of 6 Pokémon
• Add save/load functionality (localStorage)

License

This project is open source and available for educational purposes.

Note: Pokémon is a trademark of Nintendo/Game Freak. This project is a fan-made educational tool and is not affiliated with or endorsed by Nintendo, Game Freak, or The Pokémon Company.

Pokémon sprites sourced from PokeAPI.

Acknowledgments

• PyScript Team at Anaconda for making Python in the browser possible
• Pyodide Developers for CPython → WebAssembly compilation
• PokeAPI for sprite images and data

---

Built with ❤️ and PyScript