|
1 | 1 | # BlueStacks Root GUI |
2 | 2 |
|
3 | | - |
| 3 | + |
4 | 4 |
|
5 | | ->[!IMPORTANT] |
6 | | -> This is an **unofficial modification**. It is not supported by the BlueStacks team, nor should you blame me or them if your dishwasher blows up. Work **IN** Progress: only use if you are crazy! |
7 | | -> As always, I am happy to accept help. |
| 5 | +> [!IMPORTANT] |
| 6 | +> This is an unofficial modification for the BlueStacks Android emulator. If you encounter any issues, please open a GitHub issue. |
| 7 | +> |
| 8 | +> *As of January 9, 2025, this tool works as expected. However, it's important to note that this method is not compatible with Nougat instances. This README will be updated if that changes.* |
8 | 9 |
|
9 | | -This is an AIO application designed to simplify the configuration part of my original tutorial on how to [root BlueStacks](https://github.com/RobThePCGuy/Root-Bluestacks-with-Kitsune-Mask/) with Kitsune Mask. For manual work, use the original repo. This tool will allow you to toggle root access and read/write (R/W) modes for BlueStacks instances. It provides an intuitive interface for managing these settings without manually editing configuration files. It will not automatically download BlueStacks or Magisk, nor will it install either... yet. |
| 10 | +This GUI streamlines the configuration process outlined in my guide to [rooting BlueStacks](https://github.com/RobThePCGuy/Root-Bluestacks-with-Kitsune-Mask/). While it simplifies certain steps, **both repositories** are still required for complete rooting because the linked repository contains the core rooting process. This tool lets you toggle root access and enable read/write permissions for the filesystem within the `bluestacks.conf` file of selected BlueStacks instances, providing a user-friendly alternative to manual editing. |
10 | 11 |
|
11 | 12 | ## Features |
12 | 13 |
|
13 | | -- Reads Windows Registry to auto-detect the right directories and lists them individually for you to pick. |
14 | | -- Toggles root access (`Root: On/Off`) for individual instances. |
15 | | -- Toggles file system read/write access (`R/W: On/Off`) for individual instances. |
16 | | -- Updates the current status of root and R/W modes dynamically in the GUI. |
| 14 | +- Automatically detects BlueStacks instances via the Windows Registry and displays them for selection. |
| 15 | +- Toggles root access (`Root: On/Off`) in `bluestacks.conf` for selected instances. |
| 16 | +- Toggles read/write (`R/W: On/Off`) filesystem permissions for selected instances. |
| 17 | +- Dynamically updates the displayed root and R/W status in the GUI. |
17 | 18 |
|
18 | | -## Installation |
19 | | - |
20 | | -1. **Download the Executable**: |
21 | | - - Download the latest `.exe` file from the [Releases](https://github.com/RobThePCGuy/BlueStacks-Root-GUI/releases) section. |
22 | | - |
23 | | -2. **Run the app**: |
24 | | - - Double-click the `.exe` file to open the GUI. |
25 | | - - No installation is required. |
26 | | - |
27 | | -3. **Requirements**: |
28 | | - - Ensure BlueStacks is installed on your system. |
29 | | - - The app detects BlueStacks configuration and instance files automatically. |
| 19 | +### Roadmap |
| 20 | +- Download the latest version of BlueStacks |
| 21 | +- Download the latest version of Magisk Delta |
| 22 | +- Integrate ADB-based rooting directly within the GUI. |
30 | 23 |
|
31 | | ---- |
32 | | - |
33 | | -## Usage Instructions |
34 | | - |
35 | | -1. Open the app by running the `.exe` file. |
36 | | -2. The app will automatically detect available BlueStacks instances and display them in the GUI. |
37 | | -3. Select an instance by checking its corresponding checkbox. |
38 | | -4. Use the following buttons: |
39 | | - - **Toggle Root**: Toggles root access (`On`/`Off`) for the selected instance. |
40 | | - - **Toggle R/W**: Toggles read/write mode (`On`/`Off`) for the selected instance. |
41 | | -5. Observe the status updates (`Root: On/Off` and `R/W: On/Off`) next to each instance. |
42 | | -6. Once you have installed Kitsune Mask and completed the direct install to the system partition part of my other tutorial, you can untoggle Root and leave the R/W checked. |
43 | | -7. Close the app when finished. |
44 | | - |
45 | | ---- |
| 24 | +## Installation |
46 | 25 |
|
47 | | -## Requirements |
| 26 | +1. **Download:** Get the latest `.exe` release from the [Releases](https://github.com/RobThePCGuy/BlueStacks-Root-GUI/releases) page. |
| 27 | +2. **Run:** Double-click the downloaded `.exe` file. The application is portable and requires no formal installation. |
| 28 | +3. **Prerequisites:** |
| 29 | + - BlueStacks must already be installed. |
| 30 | + - Refer to my main rooting guide ([Root BlueStacks](https://github.com/RobThePCGuy/Root-Bluestacks-with-Kitsune-Mask/)) to complete the rooting process. |
48 | 31 |
|
49 | | -- **BlueStacks**: The app is designed to work with BlueStacks Android Emulator. |
50 | | -- **Windows**: This app runs on Windows systems. |
| 32 | +## Usage |
51 | 33 |
|
52 | | ---- |
| 34 | +1. Run the `.exe` file. |
| 35 | +2. The GUI will automatically detect and list available BlueStacks instances. |
| 36 | +3. Select the instance(s) you want to modify. |
| 37 | +4. Use the buttons: |
| 38 | + - **Toggle Root:** Enables or disables root access. |
| 39 | + - **Toggle R/W:** Enables or disables read/write permissions. |
| 40 | +5. The GUI displays the current `Root` and `R/W` status for each instance. |
| 41 | +6. After installing Kitsune Mask and completing the system partition installation steps described in the linked tutorial, you can **disable `Root` while leaving `R/W` enabled** if desired. |
| 42 | +7. Close the application when finished. |
53 | 43 |
|
54 | 44 | ## Troubleshooting |
55 | 45 |
|
56 | | -### Common Issues |
| 46 | +**Common Issues:** |
57 | 47 |
|
58 | | -1. **Error: Configuration file not found**: |
59 | | - - Ensure BlueStacks is installed and running. |
60 | | - - Verify that the `bluestacks.conf` file exists in the expected directory. |
61 | | - |
62 | | -2. **Status not updating**: |
63 | | - - Restart the app to refresh instance detection. |
64 | | - - Ensure the `.bstk` files are not locked by another process. |
65 | | - |
66 | | -3. **Permissions error**: |
67 | | - - Run the app as an administrator to ensure it can modify the necessary files. |
68 | | - |
69 | | ---- |
| 48 | +- **"Configuration file not found":** Ensure that BlueStacks is installed. Confirm that the `bluestacks.conf` file exists in the correct directory (the GUI should handle this automatically). If the problem persists, open a GitHub issue. |
| 49 | +- **Status not updating:** Restart the application. Ensure BlueStacks is not running (it could be locking the `.bstk` files). |
| 50 | +- **Permissions error:** Run the application as an administrator. |
70 | 51 |
|
71 | 52 | ## Development |
72 | 53 |
|
73 | | -### For Developers |
| 54 | +**For Developers:** |
74 | 55 |
|
75 | | -1. Clone the repository: |
| 56 | +1. **Clone:** |
76 | 57 | ```bash |
77 | 58 | git clone https://github.com/RobThePCGuy/BlueStacks-Root-GUI.git |
78 | 59 | cd BlueStacks-Root-GUI |
79 | 60 | ``` |
80 | | - |
81 | | -2. Install dependencies: |
| 61 | +2. **Dependencies:** |
82 | 62 | ```bash |
83 | 63 | pip install -r requirements.txt |
84 | 64 | ``` |
85 | | - |
86 | | -3. Run the app: |
| 65 | +3. **Run:** |
87 | 66 | ```bash |
88 | 67 | python main.py |
89 | 68 | ``` |
90 | | - |
91 | | -4. Build the `.exe` file: |
| 69 | +4. **Build (exe):** |
92 | 70 | ```bash |
93 | 71 | pyinstaller --onefile --windowed --icon=main.ico main.py |
94 | 72 | ``` |
| 73 | + The output file will be located inside the `dist/` folder. |
95 | 74 |
|
96 | | ---- |
97 | | - |
98 | | -## Contributions |
| 75 | +## Contributing |
99 | 76 |
|
100 | | -Contributions are welcome! Feel free to open an issue or submit a pull request. |
| 77 | +Contributions are welcome! Please open an issue or submit a pull request. |
0 commit comments