Skip to content

Commit 6b1882d

Browse files
RobThePCGuyRobThePCGuy
committed
v2 Release
1 parent aafa153 commit 6b1882d

File tree

5 files changed

+519
-502
lines changed

5 files changed

+519
-502
lines changed

‎README.md‎

Lines changed: 204 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,208 @@
11
# BlueStacks Root GUI
22

3-
[![GitHub Repo Stars](https://img.shields.io/github/stars/RobThePCGuy/BlueStacks-Root-GUI?style=social)](https://github.com/RobThePCGuy/BlueStacks-Root-GUI)
4-
[![YouTube Video Views](https://img.shields.io/youtube/views/zpihBs3FtEc?style=social)](https://youtu.be/zpihBs3FtEc)
5-
[![Last Updated](https://img.shields.io/github/last-commit/RobThePCGuy/BlueStacks-Root-GUI)](https://github.com/RobThePCGuy/BlueStacks-Root-GUI/commits/main)
3+
[![GitHub Repo Stars](https://img.shields.io/github/stars/RobThePCGuy/BlueStacks-Root-GUI?style=social)](https://github.com/RobThePCGuy/BlueStacks-Root-GUI) [![YouTube Video Views](https://img.shields.io/youtube/views/zpihBs3FtEc?style=social)](https://youtu.be/zpihBs3FtEc) [![Last Updated](https://img.shields.io/github/last-commit/RobThePCGuy/BlueStacks-Root-GUI)](https://github.com/RobThePCGuy/BlueStacks-Root-GUI/commits/main)
4+
5+
---
6+
67
![GUI Screenshot](https://github.com/user-attachments/assets/10f965eb-e1cc-4d61-9b6f-0cbb484a4ef0)
78

8-
This tool allows you to toggle root access and enable read/write (R/W) permissions for your BlueStacks instances. It automatically detects both master and cloned instances, eliminating the need to manually edit configuration files as described in my original guide: **[Root BlueStacks with Kitsune Mask](https://github.com/RobThePCGuy/Root-Bluestacks-with-Kitsune-Mask/)**.
9-
10-
## ✨ Features
11-
12-
- **Auto-detection:** Quickly identifies BlueStacks instances from the Windows Registry.
13-
- **Root Toggle:** Enables or disables root access **(`Root: On/Off`)** in `bluestacks.conf`.
14-
- **Read/Write Permissions:** Easily sets filesystem permissions **(`R/W: On/Off`)** per instance.
15-
- **Dynamic Status Updates:** Real-time GUI updates reflect current root and R/W states.
16-
17-
## 📥 Installation
18-
19-
1. **Download** the latest executable (`.exe`) from the **[Releases](https://github.com/RobThePCGuy/BlueStacks-Root-GUI/releases)** page.
20-
2. **Run** the downloaded `.exe` file (portable—no formal installation needed).
21-
3. **Prerequisites:**
22-
**Fully Uninstall BlueStacks:**
23-
- Use the official tool to completely **[uninstall all previous BlueStacks installations](https://support.bluestacks.com/hc/en-us/articles/360057724751-How-to-uninstall-BlueStacks-5-BlueStacks-X-and-BlueStacks-Services-completely-from-your-PC)**.
24-
- Download the latest BlueStacks version from the official website: **[BlueStacks](https://www.bluestacks.com/)**.
25-
26-
## 🎯 Usage
27-
28-
1. Launch the downloaded `.exe` file.
29-
2. The GUI auto-detects and lists all available BlueStacks instances.
30-
3. Select the instances you wish to modify.
31-
4. Use provided toggles:
32-
- **Toggle Root** – Switch this **ON** only until you have installed Kitsune to **`/system`**.
33-
- **Toggle R/W** – This must be **ON** for the instance to remain rooted.
34-
5. Download the **[Kitsune Mask](https://github.com/1q23lyc45/KitsuneMagisk/releases)** apk file.
35-
6. Launch the instance from the Multi-Instance Manager and install the apk.
36-
7. You should see the Kitsune Mask application; click on it to run.
37-
8. Root using **Kitsune Mask**:
38-
- Once open, look to the top under the Kitsune Mask section and select the **Install** option.
39-
- At the top right, tap the **Next** link to proceed.
40-
- Select the **Direct Install to /system** option.
41-
42-
>[!NOTE]
43-
> If the **Direct Install to /system** option is missing, do not select **Direct Install**.
44-
>
45-
> Completely close and reopen the Kitsune Mask app. This usually resolves the issue.
46-
47-
9. Click Next and watch the install log for any errors.
48-
10. Allow Kitsune Mask to finish installing, then close the BlueStacks emulator.
49-
11. Use the provided toggles:
50-
- **Toggle Root** – Switch this **OFF** once the Kitsune Mask install has been completed.
51-
- **Toggle R/W** – This must be **ON** for the instance to remain rooted.
52-
12. Close the BlueStacks-Root-Gui.
53-
54-
## ⚠️ Troubleshooting
55-
56-
### Common Issues:
57-
- **Configuration not found:**
58-
**Fully Uninstall BlueStacks:**
59-
- Use the official tool to completely **[uninstall all previous BlueStacks installations](https://support.bluestacks.com/hc/en-us/articles/360057724751-How-to-uninstall-BlueStacks-5-BlueStacks-X-and-BlueStacks-Services-completely-from-your-PC)**.
60-
- Download the latest BlueStacks version from the official website: **[BlueStacks](https://www.bluestacks.com/)**.
61-
- **Permissions errors**: Run the GUI as an administrator.
62-
63-
## 👩‍💻 Development
64-
65-
### Getting Started:
66-
67-
**Clone the repo:**
68-
```bash
69-
git clone https://github.com/RobThePCGuy/BlueStacks-Root-GUI.git
70-
cd BlueStacks-Root-GUI
71-
```
72-
73-
**Install dependencies:**
74-
```bash
75-
pip install -r requirements.txt
76-
```
77-
78-
**Run the application:**
79-
```bash
80-
python main.py
81-
```
82-
83-
**Build executable:**
84-
```bash
85-
pyinstaller --onefile --windowed --icon=main.ico main.py
86-
```
87-
88-
The built executable will be located in the `dist/` folder.
89-
90-
## 🤝 Contributing
91-
92-
Contributions are highly encouraged! Please open issues or submit pull requests to enhance this project.
9+
BlueStacks Root GUI is a utility designed to toggle root access and enable read/write (R/W) permissions for your BlueStacks instances. It automatically detects both master and cloned instances—eliminating the need to manually edit configuration files as described in the original guide: **[Root BlueStacks with Kitsune Mask](https://github.com/RobThePCGuy/Root-Bluestacks-with-Kitsune-Mask/)**.
10+
11+
---
12+
13+
## Table of Contents
14+
15+
- [Features](#features)
16+
- [Prerequisites](#prerequisites)
17+
- [Installation & Download](#installation--download)
18+
- [Usage](#usage)
19+
- [Troubleshooting](#troubleshooting)
20+
- [Development](#development)
21+
- [Changelog](#changelog)
22+
- [Contributing](#contributing)
23+
- [License](#license)
24+
25+
---
26+
27+
## Features
28+
29+
- **Auto-Detection:**
30+
Quickly identifies BlueStacks instances using the Windows Registry.
31+
32+
- **Root Toggle:**
33+
Easily enable or disable root access by modifying `bluestacks.conf`.
34+
35+
- **Read/Write Permissions:**
36+
Toggle R/W mode per instance to control filesystem access.
37+
38+
- **Dynamic Status Updates:**
39+
Real-time GUI updates reflect the current state of root and R/W settings.
40+
41+
- **Improved Responsiveness:**
42+
Background operations via QThread ensure the UI remains responsive during lengthy tasks.
43+
44+
---
45+
46+
## Prerequisites
47+
48+
- **Operating System:**
49+
Windows 10 or later is recommended.
50+
51+
- **Python Version:**
52+
Python 3.7 or higher.
53+
54+
- **Administrator Rights:**
55+
Required for modifying registry keys and terminating BlueStacks processes.
56+
57+
- **Dependencies:**
58+
Refer to `requirements.txt` for a full list of dependencies.
59+
60+
---
61+
62+
## Installation & Download
63+
64+
### For End Users (Executable Download)
65+
66+
1. **Download the Latest Executable:**
67+
Visit the **[Releases](https://github.com/RobThePCGuy/BlueStacks-Root-GUI/releases)** page and download the latest `.exe` file.
68+
69+
2. **Run the Executable:**
70+
Simply run the downloaded `.exe` file. This version is portable—no formal installation is needed.
71+
72+
3. **Prerequisites before Running:**
73+
- **Fully Uninstall BlueStacks:**
74+
Use the official tool to completely **[uninstall all previous BlueStacks installations](https://support.bluestacks.com/hc/en-us/articles/360057724751-How-to-uninstall-BlueStacks-5-BlueStacks-X-and-BlueStacks-Services-completely-from-your-PC)**.
75+
- **Install the Latest BlueStacks:**
76+
Download the latest version from the **[BlueStacks website](https://www.bluestacks.com/)**.
77+
78+
### For Developers (Building from Source)
79+
80+
1. **Clone the Repository:**
81+
```bash
82+
git clone https://github.com/RobThePCGuy/BlueStacks-Root-GUI.git
83+
cd BlueStacks-Root-GUI
84+
```
85+
86+
2. **Install Dependencies:**
87+
```bash
88+
pip install -r requirements.txt
89+
```
90+
91+
3. **Run the Application:**
92+
```bash
93+
python main.py
94+
```
95+
96+
4. **Build the Executable (Optional):**
97+
```bash
98+
pyinstaller --onefile --windowed --icon=main.ico main.py
99+
```
100+
The built executable will be located in the `dist/` folder.
101+
102+
---
103+
104+
## Usage
105+
106+
1. **Launch the Application:**
107+
Open the executable (or run `python main.py` if building from source).
108+
109+
2. **Instance Detection:**
110+
The GUI will auto-detect and list all available BlueStacks instances.
111+
112+
3. **Select Instances:**
113+
Check the boxes next to the instances you wish to modify.
114+
115+
4. **Toggle Operations:**
116+
- **Toggle Root:**
117+
Click this button to enable root access. (Switch this **ON** only until Kitsune Mask is installed to `/system`.)
118+
- **Toggle R/W:**
119+
Click to switch the instance’s filesystem mode. (Keep this **ON** for the instance to remain rooted.)
120+
121+
5. **Install Kitsune Mask:**
122+
- Download the **[Kitsune Mask](https://github.com/1q23lyc45/KitsuneMagisk/releases)** APK.
123+
- Launch the instance from the Multi-Instance Manager and install the APK.
124+
- Open the Kitsune Mask app, click on **Install**, then **Next**, and select **Direct Install to /system**.
125+
> **Note:** If the **Direct Install to /system** option is missing. Simply close and reopen the Kitsune Mask app.
126+
127+
6. **Final Steps:**
128+
- Once Kitsune Mask has finished installing, you **must**:
129+
- Toggle **root** *off*.
130+
- Leave **R/W** on to keep the instance rooted.
131+
- Close the GUI when finished.
132+
133+
---
134+
135+
## Troubleshooting
136+
137+
### Common Issues
138+
139+
- **Configuration Not Found:**
140+
- **Solution:**
141+
Fully uninstall previous BlueStacks installations using the official tool, then reinstall the latest version from the [BlueStacks website](https://www.bluestacks.com/).
142+
143+
- **Permission Errors:**
144+
- **Solution:**
145+
Run the GUI as an administrator.
146+
147+
- **BlueStacks Not Detected:**
148+
- **Solution:**
149+
Ensure that the required registry keys (`UserDefinedDir` and `DataDir`) are present. If missing, reinstall BlueStacks.
150+
151+
---
152+
153+
## Development
154+
155+
### Getting Started
156+
157+
1. **Clone the Repository:**
158+
```bash
159+
git clone https://github.com/RobThePCGuy/BlueStacks-Root-GUI.git
160+
cd BlueStacks-Root-GUI
161+
```
162+
163+
2. **Install Dependencies:**
164+
```bash
165+
pip install -r requirements.txt
166+
```
167+
168+
3. **Run the Application:**
169+
```bash
170+
python main.py
171+
```
172+
173+
4. **Build the Executable:**
174+
```bash
175+
pyinstaller --onefile --windowed --icon=main.ico main.py
176+
```
177+
The built executable will be located in the `dist/` folder.
178+
179+
---
180+
181+
## Changelog
182+
183+
### v2.0.0 (Latest)
184+
- Refactored the GUI to use QThread for improved responsiveness.
185+
- Enhanced error handling and logging across all modules.
186+
- Updated configuration parsing and file modification logic.
187+
- Removed print statements in favor of consistent logging.
188+
- Updated README to include clear instructions for downloading the executable.
189+
190+
*(For a complete history, please review the commit log.)*
191+
192+
---
193+
194+
## Contributing
195+
196+
Contributions are highly encouraged! Please follow these guidelines:
197+
- Adhere to existing logging and error-handling practices.
198+
- Maintain consistent code style and structure.
199+
- Update tests and documentation as necessary.
200+
- Submit pull requests with a clear description of your changes.
201+
202+
For any questions or suggestions, please open an issue in the repository.
203+
204+
---
205+
206+
## License
207+
208+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

0 commit comments

Comments
 (0)