https://github.com/pmariglia/foul-play
A Pokemon Showdown Battle AI
https://github.com/pmariglia/foul-play
ai asyncio pokemon pokemon-showdown pokemon-showdown-bot pokemonshowdown python python3 websockets
Last synced: 9 months ago
JSON representation
A Pokemon Showdown Battle AI
- Host: GitHub
- URL: https://github.com/pmariglia/foul-play
- Owner: pmariglia
- License: gpl-3.0
- Created: 2019-03-24T15:09:15.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2025-10-05T21:28:30.000Z (9 months ago)
- Last Synced: 2025-10-05T22:21:59.082Z (9 months ago)
- Topics: ai, asyncio, pokemon, pokemon-showdown, pokemon-showdown-bot, pokemonshowdown, python, python3, websockets
- Language: Python
- Homepage:
- Size: 6.24 MB
- Stars: 308
- Watchers: 14
- Forks: 196
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Foul Play 
A Pokémon battle-bot that can play battles on [Pokemon Showdown](https://pokemonshowdown.com/).
Foul Play can play single battles in all generations
though currently dynamax and z-moves are not supported.
## Python version
Requires Python 3.11+.
## Getting Started
### Configuration
Command-line arguments are used to configure Foul Play
use `python run.py --help` to see all options.
### Running Locally
**1. Clone**
Clone the repository with `git clone https://github.com/pmariglia/foul-play.git`
**2. Install Requirements**
Install the requirements with `pip install -r requirements.txt`.
Note: Requires Rust to be installed on your machine to build the engine.
**4. Run**
Run with `python run.py`
Here is a minimal example that plays a gen9randombattle on Pokemon Showdown:
```bash
python run.py \
--websocket-uri wss://sim3.psim.us/showdown/websocket \
--ps-username 'My Username' \
--ps-password sekret \
--bot-mode search_ladder \
--pokemon-format gen9randombattle
```
### Running with Docker
**1. Clone the repository**
`git clone https://github.com/pmariglia/foul-play.git`
**2. Build the Docker image**
Use the `Makefile` to build a Docker image
```shell
make docker
```
or for a specific generation:
```shell
make docker GEN=gen4
```
**3. Run the Docker Image**
```bash
docker run --rm --network host foul-play:latest \
--websocket-uri wss://sim3.psim.us/showdown/websocket \
--ps-username 'My Username' \
--ps-password sekret \
--bot-mode search_ladder \
--pokemon-format gen9randombattle
```
## Engine
This project uses [poke-engine](https://github.com/pmariglia/poke-engine) to search through battles.
See [the engine docs](https://poke-engine.readthedocs.io/en/latest/) for more information.
The engine must be built from source if installing locally so you must have rust installed on your machine.
### Re-Installing the Engine
It is common to want to re-install the engine for different generations of Pokémon.
`pip` will used cached .whl artifacts when installing packages
and cannot detect the `--config-settings` flag that was used to build the engine.
The following command will ensure that the engine is re-installed properly:
```shell
pip uninstall -y poke-engine && pip install -v --force-reinstall --no-cache-dir poke-engine --config-settings="build-args=--features poke-engine/ --no-default-features"
```
Or using the Makefile:
```shell
make poke_engine GEN=
```
For example, to re-install the engine for generation 4:
```shell
make poke_engine GEN=gen4
```