PokéBot Gen3 (libmgba) is a bot, written in Python that automatically shiny hunts in Pokémon Ruby, Sapphire, Emerald, FireRed and LeafGreen.

Initially created to complete a Prof. Oak and Living ✨Shiny✨ Dex Challenge in Pokémon Emerald, a 🔴24/7 livestream of the challenge can be found ongoing here.

Main Interface	Load Save State	Debugger
Shiny Notifications	Phase Stats	Milestones

• This is still in development, as such, functionality is subject to change without warning - always make sure you back up your profiles/<profile name>/ folder before updating your bot!
• Reach out in Discord #bot-support-libmgba❔ if you have any issues

The bot is frame perfect and can cheat by reading data from any point in memory. By default it will attempt to perform most actions as if a human were playing to make gameplay as representative as possible, some examples:

• Starter Pokémon are generated just 1 frame after confirming the starter selection, the bot will wait until the battle begins, and the starter Pokémon sprite is visible before resetting
• It's possible to peek inside un-hatched eggs to view stats and shininess as soon as they're received from the daycare, the bot will wait until the eggs are fully hatched before checking and logging
• These are intentional design decisions, bot cheats can be used to bypass them (in most cases)

• Running mGBA at unbound speeds, will cause very fast and bright flashing!
• Any unbounded video examples on this page will be hidden by default, and marked with ⚠ photosensitivity warning

• Windows (64-bit)
• Linux (64-bit)
  • Note: only tested and confirmed working on Ubuntu 23.04 and Debian 12

To download the latest bot from GitHub, go to the top of the page > click the green Code button > Download ZIP.

Alternatively, if you'd like to be able to easily pull the latest updates without re-downloading the entire ZIP:

• Install GitHub Desktop (you don't need an account)
• Click Clone a repository from the Internet...
• Use repository URL https://github.com/40Cakes/pokebot-gen3.git and choose a save location on your PC
• Click Clone
• Any time there's a new update, you can pull the latest changes by clicking Fetch origin, then Pull origin

• Python 3.12 (64-bit)
• Linux only: Install the following packages with apt or appropriate package manager: sudo apt install python3-tk libmgba0.10 portaudio19-dev
• Note: running the bot will automatically install required Python packages and download + extract libmgba - if you're using Python for any other projects, consider using a venv to isolate these packages from your base environment

• Windows Terminal - recommended for full 🌈colour🌈 and ✨emoji support✨ in the console output
• Notepad++ - recommended for syntax highlighting while editing .yml config files

• Place some official Pokémon .gba ROMs into the roms/ folder
• Double click pokebot.py or run python pokebot.py in a terminal and follow the on-screen steps to create and/or select a profile

The bot ships with the default mGBA input mapping, see profiles/keys.yml to view the default mapping, or customise them to your preference.

The bot will pause once a shiny is encountered. You must ensure you are able to escape battle 100% of the time, otherwise the bot will get stuck. Auto-catching and other features will be added in due time.

If you have a save from mGBA that you'd like to import and use with the bot, then you will need to import the save state.

• In mGBA, run a game and load into the save file
• File > Save State File... > Save
• Double click import.py or run python import.py in a terminal to launch the save importer tool
• Open the save state file you just saved
• A new bot profile will be created in the profiles/ folder and set up all required files
• If the importer tool detects files in the stats/ or profiles/ folders from old versions of the bot (from commit ec5d702, 7th October, 2023 or earlier), then they will be copied into your new profile

Variations of games, languages and revisions may have different memory offsets, there will be a table of supported/tested variations under each bot mode listed below.

• ✅ Supported (tested)
• 🟨 Supported (not tested)
• ❌ Not supported

ROM hacks will likely not work, and are ❌ not supported or planned to be supported!

The ROMs in the roms/ folder are checked and verified against a list of all known official gen3 game hashes. If you really want to test a ROM hack with the bot, you must add the SHA1 hash of the ROM to modules/Roms.py.

The SHA1 hash of a ROM can be calculated with any of the following methods:

• ROM Hasher
• Windows Powershell: Get-FileHash 'rom_name.gba' -Algorithm SHA1
• Linux: sha1sum 'rom_name.gba'

Please do not seek support or complain if you find that your ROM hack does not work with the bot.

• The bot mode can be changed at any time while the bot is running by using the menu on the UI
• manual mode is the default mode
• Press Tab to toggle between manual mode and a previously selected mode

Manual mode simply disables all bot inputs, allowing you to track encounters and stats on your own shiny hunts as you play the game normally.

Spin clockwise on a single tile, useful for Safari Zone and repel tricking as it doesn't count steps

Start the mode while in the overworld, in any patch of grass/water/cave.

Soft reset for starter Pokémon.

• For modes that use soft resets such as starters, the bot will track RNG to ensure a unique frame is hit after every reset, this is to prevent repeatedly generating an identical Pokémon, this will cause soft resets to take progressively longer over time
• If resets begin to take too long, it is recommended to start a new save file with a different TID to reset this delay or check out profiles/cheats.yml
• Note: Even though you set the trainer to face the desired PokéBall, it is still important to set the correct starter in the config! This option is used by the bot to track frames to ensure a unique starter is generated every time
• Note: For the time being, Johto starters will automatically enable the starters option in profiles/cheats.yml, the shininess of the starter is checked via memhacks as start menu navigation is WIP (in future, shininess will be checked via the party summary menu)

1. Select the starter in profiles/general.yml - Bulbasaur, Charmander or Squirtle
2. Face the desired PokéBall in Oak's lab, save the game (in-game, not a save state)
3. Start the bot

1. Select the starter in profiles/general.yml - Chikorita, Cyndaquil or Totodile
2. Face the desired PokéBall in Birch's lab, save the game (in-game, not a save state)
3. Start the bot

1. Select the starter in profiles/general.yml - Treecko, Torchic or Mudkip
2. Face the starters bag, and save the game (in-game, not a save state)
3. Start the bot

Start the mode while facing the water, with any fishing rod registered.

Bunny hop on the spot with the Acro Bike, useful for Safari Zone and repel tricking as it doesn't count steps.

Start the mode while in the overworld, in any patch of grass/cave, with the Acro Bike registered.

• Note: bunny_hop is ~10% slower encounters/h on average than spin mode

Configuration files are loaded and validated against a schema, once at bot launch. Any changes made while the bot is running will not take effect until the bot is stopped and restarted.

A lot of the config in .yml files is placeholder for future/planned features.

The bot stores all profile information, such as save games, screenshots, statistics, etc. in the profile profiles/<profile name>/) folder, which is automatically created once you create a new profile in the GUI.

Running multiple instances of the bot is as easy as starting the bot multiple times and loading a different profile each time. You should not run multiple instances of the bot with the same profile simultaneously!

Statistics are saved into a subfolder of your profile profiles/<profile name>/stats/.

The bot will first attempt to load individual config files from your profile folder (profiles/<profile name>/), if that folder does not exist or any of the configuration files are missing, it will load the default config file in the profiles/ folder. This allows you to selectively override specific config files on a per-profile basis.

Example:

├── /profiles
    │
    ├── /emerald-profile
    │     current_save.sav
    │     current_state.ss1
    │     discord.yml          <-- config loaded for 'emerald-profile'
    │     general.yml          <-- config loaded for 'emerald-profile'
    │
    ├── /firered-profile
    │     current_save.sav
    │     current_state.ss1
    │     general.yml          <-- config loaded for 'firered-profile'
    │
    │   catch_block.yml        <-- config loaded for all profiles
    │   cheats.yml             <-- config loaded for all profiles
    │   customcatchfilters.py  <-- config loaded for all profiles
    │   customhooks.py         <-- config loaded for all profiles
    │   discord.yml            <-- config loaded for all profiles except 'emerald-profile'
    │   general.yml            <-- config loaded for all profiles except 'emerald-profile' and 'firered-profile'
    │   logging.yml            <-- config loaded for all profiles
    │   obs.yml                <-- config loaded for all profiles

This file controls keyboard to GBA button mappings.

• For a full list of available key codes, see here or here (column .keysym)

• A button: X
• B button: Z
• D-Pad: Arrow keys (Up, Down, Left, Right)
• Start button: Enter
• Select button: Backspace
• Toggle manual bot mode on/off: Tab
• Toggle video output on/off: V
• Toggle audio output on/off: B
• Zoom window scaling in/out: +, -
• Create save state: Ctrl + S
• Load save state menu: Ctrl + L
• Reset emulator/reboot game: Ctrl + R
• Exit the bot and emulator: Ctrl + Q
• Emulator speed:
  • 1x speed: 1
  • 2x speed: 2
  • 3x speed: 3
  • 4x speed: 4
  • Unbound: 0 - ⚠ Photosensitivity warning: this will run the emulator as fast as possible!

block_list:
  - Poochyena
  - Pidgey
  - Rattata

• Set TEXT SPEED to FAST
• Set BATTLE SCENE to OFF
• Utilise repel tricks to boost encounter rates of target Pokémon
• Using bot_mode spin or bunny_hop and repels will become effectively infinite + steps won't be counted in Safari Zone
• Use a lead Pokémon with encounter rate boosting abilities, such as Illuminate
• Use a lead Pokémon with a short cry
• Use a lead Pokémon with a single character nickname
• Don't use a shiny lead Pokémon (shiny animation takes a few frames at the start of every battle)

The bot supports auto-starting a profile and can also be launched into a 'debug' mode which can aid bot development.

python pokebot.py my-profile          starts the 'my-profile' profile
python pokebot.py my-profile --debug  starts the 'my-profile' profile in debug mode
python pokebot.py --debug             starts the profile selection screen in debug mode

• mGBA
• libmgba-py

Other awesome PokéBot projects:

• PokéBot NDS

This project would not be possible without the decompiled symbol tables and other various data from the following projects:

• Pokémon Emerald decompilation (symbols)
• Pokémon Ruby and Sapphire decompilation (symbols)
• Pokémon FireRed and LeafGreen decompilation (symbols)
• PKHeX Plugin: MissingEventFlagsCheckerPlugin (event flags data)