osu!pilot is a smart and unique bot designed to play osu! with realistic, human-like movements. It works externally by reading beatmap files in real-time—just like a human player reads notes on the screen—to offer a truly unique gameplay simulation.
For more information, live demo, and more detailed feature breakdowns, please visit the official website:
⚠️ Important: Before starting, make sure your in-game keybinds for hitting notes are set toAandS. The bot uses these keys to play.
-
Launch the Bot
- Run the program (
python main.pyor the.exe). The bot's overlay will appear on your screen. - If it's your first time, a calibration window will pop up. Complete the simple reaction time test. On future launches, you can skip this step.
- Run the program (
-
Select a Beatmap in osu!
- Open osu! and choose any beatmap. When you are at the song selection screen, the bot's overlay will automatically update with the map's information.
-
Choose Your Options (Optional)
- Before starting the map, you can click the checkboxes on the overlay to enable mods like
HR,DT,NC, or theFlow Aimmovement style. -
Tip: If you can't click the checkboxes, press the
Windowskey to unfocus the osu! window, make your selections, then click back into the game.
- Before starting the map, you can click the checkboxes on the overlay to enable mods like
-
Sync and Play
- Start the beatmap in osu!. As soon as the very first hit circle begins to appear (when its approach circle shows up), press the
Qkey. - This single keypress synchronizes the bot, and it will immediately take over and start playing.
- Start the beatmap in osu!. As soon as the very first hit circle begins to appear (when its approach circle shows up), press the
-
Controlling the Bot
- To stop the bot mid-play, press the
Esckey. - To close the entire program, press
Ctrl + Page Down. - For a complete list of controls, please refer to the Hotkeys section.
- To stop the bot mid-play, press the
A quick reference for all available controls.
| Key Combination | Action |
|---|---|
Q |
Synchronizes and starts the bot when a map begins. |
Esc |
Immediately stops the bot during gameplay. |
Ctrl + Page Up |
Toggles the visibility of the GUI overlay. |
Ctrl + Page Down |
Safely shuts down the bot script. |
| Feature | Description |
|---|---|
| Mechanism | Works by reading .osu files. Does not read game memory or modify files. |
| Human-like Aim | A layered system with curved paths, natural jitter, and an optional "Flow Aim" mode for realistic movement. |
| Zero Setup Required | Auto-detects your Songs folder and saves your calibration. No manual config needed. |
| Mod Support | Supports HR, DT, and NC, which can be toggled directly from the overlay. |
| In-Game Overlay | Shows bot status, map info, and has toggles for mods and aim style. You can also drag it around. |
| Hotkey Control | Start, stop, and hide the overlay with simple hotkeys without leaving the game. |
The bot operates in a clear, sequential lifecycle:
| State | Description |
|---|---|
| IDLE | Waits for you to select a beatmap in osu!. It constantly scans the active window's title. |
| DETECT & PARSE | Once a beatmap is chosen, the title changes. The bot uses this title to find the exact .osu file in your Songs folder and parses all its data. |
| ARMED | The overlay updates with the beatmap info, and the bot is now "armed". It waits for you to press q to signal the start of the map. This keypress is crucial for synchronization. |
| EXECUTE | After syncing, the bot takes full control. It follows the parsed object data with precise timing, moving the cursor and pressing keys until the song ends or you press Esc. |
| RESET | Once the map is finished or stopped, the bot returns to the IDLE state, ready for the next map. |
Step 1: Prerequisites & Installation
Requirements:
- Python 3.8+
- Windows OS
Installation Commands:
- Clone this repository:
git clone https://github.com/Wakype/osu-pilot.git cd osu-pilot - Install the required packages from the
requirements.txtfile:pip install -r requirements.txt
Step 2: Running the Bot
That's it! There is no manual configuration.
- Run the main script from your terminal:
python main.py
- The Reaction Time Calibration will appear on the first launch. Follow the on-screen instructions. On subsequent launches, you can use the "Use Previous" button to skip this.
- The bot's overlay will now be visible. You can now launch and play osu!.
This project was created for educational purposes to explore concepts in automation, real-time file parsing, and human-like algorithm design.
Using this bot on official osu! servers is a direct violation of the game's terms of service. Doing so will result in a swift and permanent ban of your account. The developer assumes no responsibility for any misuse or consequences.
Use responsibly and at your own risk.