Foul Play

A Pokémon battle-bot that can play battles on Pokemon Showdown.

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:

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

make docker

or for a specific generation:

make docker GEN=gen4

3. Run the Docker Image

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 to search through battles. See the engine docs 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:

pip uninstall -y poke-engine && pip install -v --force-reinstall --no-cache-dir poke-engine --config-settings="build-args=--features poke-engine/<GENERATION> --no-default-features"

Or using the Makefile:

make poke_engine GEN=<generation>

For example, to re-install the engine for generation 4:

make poke_engine GEN=gen4