English | Português (Brasil)

BPSR Fishing Bot

An automated and open-source fishing bot built in Python. It uses image detection to identify on-screen events and interact with a game's fishing minigame, automating the entire process.

---

Table of Contents

• Features
• Quick Start Guide
  • Prerequisites
  • Installation
  • How to Run
• Known Issues and Solutions
• Configuration
• For Developers
  • Architecture
  • Project Structure
• Future Plans

---

Features

• Fully Automated Fishing: Casts the line, detects a bite, and starts the minigame.
• Smart Minigame Player: Autonomously plays the fishing minigame, moving left and right as needed.
• Automatic Rod Swapping: Detects when the fishing rod breaks and replaces it with a new one, allowing for uninterrupted fishing sessions.
• Hotkey Control: Easily start, pause, resume, and stop the bot using hotkeys ('7' and '8' keys).
• Flexible Configuration: Allows for easy adjustment of detection precision, regions of interest (ROI), and wait times through dedicated configuration files.
• Robust Architecture: Built with a state machine and solid design principles, making the code easy to understand and extend.

---

Quick Start Guide

1. Prerequisites

• Python 3.8+
• The game configured to run in full-screen mode at 1920x1080 resolution.

2. Installation

1. Clone this repository:

   git clone https://github.com/your-username/BPSR-Fishing-Bot.git
   cd BPSR-Fishing-Bot

2. Install the dependencies from requirements.txt:

   pip install -r requirements.txt

3. How to Run

1. Open the game and make sure it is visible on the screen.
2. Be at a fishing location. Either stand on an interactable fishing spot or already in the fishing UI.
3. Run the bot from the project's root folder:

   python main.py

4. The bot will be ready. Press 7 key to start/pause and 8 key in-game or in the terminal to stop the bot at any time.

---

Known Issues and Solutions

This section lists common issues you might encounter and how to solve them.

The detection of an item (e.g., broken rod, fish bite) stops working

• Symptom: The bot stops reacting to a specific event that used to work, such as not swapping a broken rod or not detecting a bite.
• Likely Cause: The game may have received a minor visual update, changing the appearance of the icon or image the bot is looking for.
• Solution:
  1. Take a new screenshot of the failed image (e.g., the broken rod icon).
  2. Replace the corresponding template file in the src/fishbot/assets/templates/ folder.
  3. If the problem persists, try adjusting the precision value in the src/fishbot/config/detection_config.py file. Lowering the value (e.g., from 0.8 to 0.7) can help compensate for minor visual differences.

Character won't resume fishing after a timeout state

• Symptom: Something unexpected occurred (like fish escaped) and the bot has escaped the fishing UI and won't start again.
• Cause: When the bot escapes it tries to re-enter the fishing UI by interacting with the fishing spot. Because some spots move the player after interacting with the fishing spot, the bot idly tries to interact when nothing is there. Bot also does not support a search to find the nearest one.
• Solution: Move your character over to an interactable fishing spot to resume the bot.

---

Configuration

The bot's behavior can be adjusted through the files located in src/fishbot/config/.

screen_config.py

Defines the screen capture area.

• monitor_width, monitor_height: The game's screen resolution (default: 1920x1080).
• monitor_x, monitor_y: Coordinates of the top-left corner of the monitor where the game is running. For the primary monitor, keep this as (0, 0).

detection_config.py

Controls image detection.

• precision: The minimum confidence (from 0.0 to 1.0) for a template to be considered a match.
• templates: Maps event names to their corresponding image files in src/fishbot/assets/templates/.
• rois (Regions of Interest): Defines rectangles (x, y, width, height) to limit the search area for each template, increasing performance and accuracy.

bot_config.py

General bot settings.

• state_timeouts: Maximum time the bot can remain in each state before resetting.
• target_fps: Target frames per second for screen captures (0 for unlimited).
• default_delay: Default delays between actions.
• casting_delay: Delay right before casting a bait.

---

For Developers

Architecture

The bot uses a Finite State Machine (FSM) to manage its workflow. The logic is divided as follows:

• main.py: The entry point that initializes and runs the bot.
• src/fishbot/core/state/: Contains the state machine logic.
  • state_machine.py: Manages the current state and transitions.
  • impl/: Houses the classes for each concrete state (CheckingRodState, PlayingMinigameState, etc.), where each implements a single responsibility.
• src/fishbot/core/game/: Modules that interact directly with the game.
  • detector.py: Responsible for screen capture and template detection using mss and OpenCV.
  • controller.py: Simulates keyboard and mouse inputs.
• src/fishbot/utils/: Utility modules, such as the logger function.

Project Structure

BPSR-Fishing-Bot/
├── src/
│   └── fishbot/
│       ├── assets/         # Images (templates) for detection
│       ├── config/         # Bot configuration files
│       ├── core/
│       │   ├── game/       # Game interaction modules (Detector, Controller)
│       │   └── state/      # State Machine Logic
│       ├── ui/             # (Reserved for a future GUI)
│       └── utils/          # Utility modules
├── .gitignore
├── main.py                 # Application entry point
├── README.md
└── requirements.txt

Future Plans

• Graphical user interface (GUI) for easier configuration.
• Hotkey system to start/stop the bot.
• Improve resilience to unexpected in-game events.

---

Feel free to open an issue or submit a pull request!