Mine Tool

Overview

Mine Tool is currently a Proof of Concept (PoC) Python script designed for partially automating the mining minigame in the Roblox game Mine. This tool utilizes image processing with OpenCV and GUI control with Tkinter to provide real-time visual debugging and automated mouse actions.

mine_tool_example_v1.0.0-alpha.3+poc.mp4

mine_tool_example_v1.0.0-alpha.3+poc_2.mp4

mine_tool_example_v1.0.0-alpha.2+poc.mp4

Setup Instructions

Requirements

• Python 3.x
• Python packages listed in requirements.txt

Running from Source

git clone https://github.com/AlinaWan/mine-tool.git
cd mine-tool

Install dependencies:

pip install -r requirements.txt

Run the application:

python app.py

Usage

Initial Setup (First Run)

1. Run the script once. It will automatically generate a config.ini file in the same directory.

2. Edit config.ini: Open config.ini in a text editor.

3. Define ROI (Selection Zone): Adjust ROI_X1, ROI_Y1, ROI_X2, ROI_Y2 to accurately encompass the entire area where the mini-game's curved bar and moving line appear. This is crucial for accurate detection. Use a screenshot tool to get these pixel coordinates.

4. Calibrate Colors: Adjust HEX_GREY and HEX_WHITE to match the exact hexadecimal colors of the moving grey line and the target white area in your game. Adjust COLOR_TOLERANCE to fine-tune how strictly these colors are matched.

5. Set Thresholds: Adjust MIDDLE_THRESHOLD for the precision required for the grey line to be considered "in the middle" of the white area.

6. Set Cooldown: Configure CLICK_COOLDOWN_DURATION to set a delay after a mouse release, preventing rapid re-clicks.

7. Set Prediction: If desired, enable/disable PREDICTION_ENABLED and adjust LOOKAHEAD_FACTOR and EXPONENTIAL_POWER to fine-tune how the script predicts the grey line's movement.

8. Save config.ini and re-run the script.

Example ROI Setup

An example ROI (Region of Interest) image is shown below. The default values are configured for:

• Screen resolution: 1920×1080
• Operating System: Windows 11
• Roblox running in windowed mode

Note

If your setup differs (different resolution, OS, or fullscreen/window mode), you must adjust the ROI coordinates in config.ini accordingly for accurate detection.

Start Mining

Once the script is running, manually click and hold your left mouse button on the desired in-game element (e.g., a block you want to mine) to initiate the mini-game.

The program will automatically release the left mouse button when the moving grey line intersects the target white area on the curved bar, completing the mini-game action.

Visual Debugging

The script will open several small debug windows that stay on top:

• Detected Elements (Live): Shows the active ROI with detected grey line, white area, and curved bar, along with their centroids and the line's rotation. This is your primary visual feedback.
• Grey Line Mask: A black and white view showing only the pixels detected as part of the grey line.
• White Area Mask: A black and white view showing only the pixels detected as part of the white area.
• Curved Bar Mask (Dark Area): A black and white view showing the detected curved bar's area.

Use these windows to verify that the script is accurately identifying the elements based on your config.ini settings.

Stop the Script

Press the Esc key on your keyboard at any time to gracefully stop the script and close all debug windows (or press Ctrl+C in the console window).

Configuration (config.ini)

This script uses a config.ini file to manage its settings, making it easy to adjust parameters without editing the Python code directly. If config.ini is not found, the script will automatically create one with default values in the same directory.

How to Edit config.ini

1. Run the script once: This will generate the config.ini file if it doesn't already exist.

2. Open config.ini: Use any text editor (like Notepad, VS Code, Sublime Text, etc.) to open the config.ini file in the same directory as your Python script.

3. Adjust Values: Modify the values to the right of the equals sign (=).

4. Save and Rerun: Save the config.ini file and then restart your Python script to apply the changes.

Configuration Variables Explained

[Detection] Section

ROI_X1, ROI_Y1, ROI_X2, ROI_Y2

• What they are: These four values define the Region of Interest (ROI) on your screen in pixel coordinates. This is the rectangular area the script will monitor for the game's mini-game elements.

• How to set:

  • ROI_X1: The X-coordinate (horizontal) of the top-left corner of your ROI.
  • ROI_Y1: The Y-coordinate (vertical) of the top-left corner of your ROI.
  • ROI_X2: The X-coordinate (horizontal) of the bottom-right corner of your ROI.
  • ROI_Y2: The Y-coordinate (vertical) of the bottom-right corner of your ROI.

• Effect: A precisely defined ROI improves performance and reduces false detections by focusing the image processing only on the relevant part of the screen.

• Tip: Use a screenshot tool (like Windows Snipping Tool, Greenshot, or macOS built-in screenshot tools) to easily get these pixel coordinates.

HEX_GREY

• What it is: The hexadecimal color code for the grey line you want to detect.
• How to set: Find the exact hex color of the grey line in your game. Tools like digital color pickers (often found in image editing software) can help you get this value (e.g., #485163).
• Effect: Determines which pixels are identified as part of the grey line.

HEX_WHITE

• What it is: The hexadecimal color code for the white area on the curved bar.
• How to set: Similar to HEX_GREY, find the exact hex color of the white area.
• Effect: Determines which pixels are identified as part of the white target area.

COLOR_TOLERANCE

• What it is: An integer value that defines how much variation in color is allowed when detecting HEX_GREY and HEX_WHITE.

• How to set:

  • A lower value (e.g., 5-10) means the script will only detect pixels that are very close to the exact HEX_GREY or HEX_WHITE color. This is good if colors are very consistent.
  • A higher value (e.g., 20-30 or more) allows for more variation, useful if lighting or game effects cause the colors to shift slightly.

• Effect: Directly impacts the accuracy of the grey line and white area detection. Too low, and it might miss the target; too high, and it might detect unintended elements.

• Tip: Use the debug masks (the Grey Line Mask and White Area Mask windows) to fine-tune this. When the masks accurately highlight only the target color, your tolerance is good.

MIDDLE_THRESHOLD

• What it is: An integer value (in pixels) that determines how close the center of the grey line must be to the center of the white area for the mouse button to be released.

• How to set:

  • A lower value (e.g., 5-10) means the grey line needs to be very precisely in the middle.
  • A higher value (e.g., 15-25) allows for a larger "hitbox" around the middle.

• Effect: Controls the precision required for the automated mouse release.

BAR_THICKNESS_PERCENTAGE

• What it is: A floating-point value that defines the thickness of the curved bar as a percentage of the ROI's size. For example, 0.15 means the bar is 15% as thick as the smaller of the ROI's width or height.

• How to set: Adjust this value to match the visual thickness of the curved bar in your game. If the bar seems thicker, increase the value (e.g., to 0.20); if it seems thinner, decrease it (e.g., to 0.10).

• Effect: This setting is used to generate the curved bar mask, which restricts the detection of the grey and white lines to within the bar's boundaries. A correct value ensures accurate detection.

WHITE_AREA_WIDTH_INCREASE

• What it is: An integer value that expands the detected white area mask using a morphological dilation operation.

• How to set:

  • A value of 0 means no expansion.
  • A positive value (e.g., 5) will make the detected white area larger, which can make it easier to find a match and be more tolerant of color variations or visual noise.

• Effect: A larger value creates a bigger "hitbox" for the white area, making the detection more robust. This is especially useful if the white area is not perfectly solid or if the COLOR_TOLERANCE is not high enough.

GREY_LINE_MIN_AREA

• What it is: An integer value representing the minimum number of pixels a detected grey contour must have to be considered a valid detection.

• How to set:

  • A lower value (e.g., 10) is suitable for detecting very thin lines or small sections of a line.
  • A higher value (e.g., 50) is for detecting larger, more solid shapes.

• Effect: Since the grey line is often very thin, this value ensures the script doesn't miss small, valid detections while ignoring random noise. When detection is restricted to the curved bar's mask, the line's visible area decreases, making a lower minimum area necessary.

[Automation] Section

CLICK_COOLDOWN_DURATION

• What it is: A floating-point value representing the time (in seconds) that the script will wait after releasing the mouse button before it can release it again.
• How to set: If set to 0.5, the script will release the mouse, then wait for 0.5 seconds without releasing the mouse again, before becoming ready for another release. Adjust based on the timing needed in your mini-game.
• Effect: Prevents rapid, unintended multiple clicks and allows for a "rest" period. During this cooldown, the visual debugging windows will continue to update, as the core processing loop is not blocked.

PREDICTION_ENABLED

• What it is: A boolean value (True or False) that acts as a toggle for the velocity-based prediction system.

• How to set:

  • Set to True to enable the script to predict the future position of the grey line based on its velocity.
  • Set to False to disable prediction. The script will use the logic of releasing the mouse only when the grey line is physically within the MIDDLE_THRESHOLD.

• Effect: Allows you to switch between a reactive (non-predictive) and a proactive (predictive) approach to mouse releases.

LOOKAHEAD_FACTOR

• What it is: A floating-point value that scales how far into the future the script predicts the grey line's position. This factor is a key multiplier for the velocity.

• How to set:

  • A larger value (e.g., 0.20) makes the script release the mouse earlier, which is useful for faster-moving grey lines or to compensate for system latency.
  • A smaller value (e.g., 0.05) makes the script release the mouse later, closer to the white area.

• Effect: Directly controls the aggressiveness of the prediction. A higher value means the script "looks ahead" further, while a lower value means it waits until the grey line is closer to the target.

EXPONENTIAL_POWER

• What it is: A floating-point value that defines the exponent used to calculate the prediction offset. A value greater than 1.0 introduces an exponential relationship between velocity and prediction.

• How to set:

  • A value of 1.0 means the prediction is linear (the prediction offset is directly proportional to velocity).
  • A value like 1.5 or 2.0 will make the prediction offset increase dramatically with higher velocities, while having a minimal effect on slower movements.

• Effect: Allows you to fine-tune the sensitivity of the prediction system. It makes the script more responsive to sudden, fast movements while remaining stable during slow movements.

Notes

• This tool detects elements based on their colors using the reference colors provided in config.ini. Adjust the color tolerance for best results depending on your screen and lighting.
• The script requires you to manually click and hold the mouse button to start the mini-game. It will only automate the release action.
• The debug windows are designed to stay on top, but extreme system resource usage or certain full-screen exclusive applications might still cause them to hide or flicker.

Troubleshooting

• Nothing is being detected at all: Increase the COLOR_TOLERANCE slider in config.ini. The app might be too strict in matching colors, especially if your screen has unusual brightness or color settings.

• Wrong elements are being detected or multiple parts of the same element are detected separately: Decrease the COLOR_TOLERANCE in config.ini. It's likely the app is being too lenient and is matching different colors as the same element. You might also need to refine your ROI to exclude irrelevant parts of the screen.

End Notes

Mine Tool is a Proof of Concept project. Its functionality is limited to automating the mouse release based on visual cues. It is not intended for complex automation and may require manual adjustments for different game interfaces or system environments.

License

Mine Tool and this repository are licensed under the Mozilla Public License 2.0.