Tutorials

OCR Text Recognition

OCR (Optical Character Recognition) reads text from your screen and compares it against your rules.

Alert Conditions for OCR

• String Contains — trigger when the recognized text includes your target word(s). Supports comma-separated multiple targets. Example: target Warning,Error triggers on either word.
• String Not Contains — trigger when the text does NOT contain your target.
• Value Equals — trigger when the number on screen exactly matches your target. Example: HP reaches 100.
• Value Not Equals — trigger when the number differs from target.
• Value Between — trigger when the number falls within a bracket range. Example: [20,80] triggers when the value is between 20 and 80 inclusive. Supports multiple ranges: [0,30],[70,100].
• Value Rising / Value Falling — trigger when the numeric trend moves consistently up or down over the last N samples. Each sample must be strictly greater (rising) or strictly less (falling) than the previous one. Configure Sample Count to control how many consecutive readings are required (default 10).
• Text Changed / Text Unchanged — trigger when the recognized text differs from previous readings, or stays the same over time. Also uses Sample Count.

Setting the Detection Area

The OCR engine works best when the overlay box tightly surrounds the text you want to read. Avoid including background graphics or UI borders — they add noise. For numeric readings (HP bars, prices), make the box as tight as possible around the number itself.

Image Detection

Image detection uses template matching to find specific icons, buttons, or UI elements on screen.

Adding Target Images

1. Take a screenshot of the element you want to detect — just the element itself, not the whole screen.
2. In Task Config, choose the Image task type, then click Add Image to select your screenshot files.
3. Adjust the Similarity threshold (0-100%). 90% is good for exact matches; lower values allow slight visual variations.

Alert Conditions

• Found (Any) — trigger when at least one target image is detected.
• Found (All) — trigger when every target image is found simultaneously.
• Not Found (Any) — trigger when at least one target image is missing.
• Not Found (All) — trigger when none of the target images are detected.

Color Detection

Color detection watches for specific color blocks appearing within the overlay region.

Adding Target Colors

1. Choose the Color task type.
2. Enter a hex color code like #FF0000 for red, and click Add.
3. Add multiple colors if you need to detect any of several conditions.

Block Size & Tolerance

• Block Width / Block Height — the minimum size of the color block. Set to 1×1 to detect a single pixel; increase for larger solid-color areas.
• Color detection is exact match only — it looks for the precise RGB value. For "close enough" matching, use Image Detection with a color swatch screenshot and lower similarity.

Alert Conditions

• Contains Any — trigger when any one of your target colors is found.
• Contains All — trigger when all target colors are found.
• Missing Any Color — trigger when at least one target color is not found.
• Missing All Colors — trigger when none of the target colors are found.

Change Detection

Change detection triggers when the pixels inside the overlay region change — or when they stay static.

How It Works

Screen Alert takes a screenshot of the region and compares it with the previous screenshot pixel by pixel. If the average pixel difference exceeds the tolerance, a change is detected.

• Tolerance — 0 means every pixel must be exactly identical (very sensitive). Higher values (up to 30) allow minor fluctuations like anti-aliasing or animated shadows. Start with 2-5 for most use cases.
• Image Changed — triggers when the region has changed since the last check.
• Image Static — triggers when the region has NOT changed (useful for detecting frozen applications or idle screens).

Click Tasks

Click tasks perform automated mouse clicks on a schedule — no detection condition required.

Configuring a Click Task

1. Set the task type to Click.
2. Define the Action Sequence — a list of click/hotkey actions with coordinates.
3. Set Exec Freq to control how often the sequence repeats.

Important Notes

• Only one click task can run at a time. Starting a second click task will prompt you to stop the first one.
• Press ESC at any time to immediately abort the current action sequence (useful if clicks go to the wrong place!).
• Click tasks use the Action Interval setting to control the delay between individual actions in the sequence (default 0.3s).

Setting Up Alerts

When a detection condition is met, Screen Alert can notify you through multiple channels.

Sound Alerts

Open the Alert Config for any task, choose a ringtone from the dropdown. Place your own .wav files in the ringtones/ folder and they'll appear in the list. The default is the system beep.

System Config → Ringtone Mode controls queue behavior: Queue plays alerts one after another; Ignore When Busy skips new alerts while a sound is already playing.

Telegram Push Alerts

1. First, bind your Telegram account during login (scan the QR code in the Telegram tab).
2. In the alert config, tick the checkbox next to your Telegram contact.
3. Now when conditions are met, you'll receive a Telegram message with the task name and match details.

Contact Frequency Limits

To prevent spam, Screen Alert enforces per-contact rate limits:

• Phone: 10 minutes between alerts
• Telegram: 5 minutes between alerts

If the same condition triggers repeatedly within the limit, only the first alert is sent. The log will show "frequency limit: skipping".

Screenshot on Alert

In the Advanced Config of a task, enable Upload Screenshot to attach a full-screen capture (with the detection region highlighted) to each Telegram alert.

Auto-Actions on Trigger

When a detection condition fires, you can automatically execute mouse clicks, double-clicks, right-clicks, hotkeys, and delays.

Building an Action Sequence

1. Open the Advanced Config (⚙️ rightmost column) for a task.
2. Scroll to Post-Trigger Actions.
3. Add actions one by one: choose the action type, set coordinates (absolute or relative), and click Add to Sequence.
4. Use the ↑↓ buttons to reorder, and ✕ to remove.

Coordinate Modes

• Absolute — coordinates are relative to the top-left of your screen. X=500, Y=300 clicks at that exact screen position.
• Relative — coordinates are relative to the detected target center. This only works for OCR and Image tasks where a target is found. X=100, Y=0 means "100 pixels right of the detected element".

Delay Action

Insert Delay actions between clicks to control timing. Values from 0.1s to 60s. This is especially useful when waiting for UI transitions between clicks.

ESC Abort

Hitting ESC during action execution immediately stops the sequence. This is your emergency brake.

Advanced: Regex & JS Conditions

For complex matching logic that goes beyond simple string comparisons.

Regex (Regular Expressions)

In the OCR task config, you can enter a regex pattern instead of using the basic target text + condition combo. The regex is matched against the full recognized text.

Examples:

• \d+ — matches any number in the recognized text.
• \d{2,5} — matches numbers with 2 to 5 digits.
• HP[: ]\s*(\d+) — matches "HP: 100" and captures the number.

JavaScript Custom Conditions

For ultimate flexibility, write a custom JavaScript function:

function exec(arr, cache) {
    // arr: array of recent OCR results (arr[0] = latest)
    // cache: persistent object across calls
    // return: false → no alert, true → alert, {x, y} → alert + action base point
    if (arr[0] === 'Critical') return true;
    return false;
}

The function receives the sampling array and a persistent cache object. Return true to trigger the alert, {x: 500, y: 300} to trigger with a specific action reference point, or false/null to skip.

Shifts & Scheduling

Control when tasks are active using the shift system.

How Shifts Work

Each task has a Shift setting:

• All Day — task runs 24/7 when enabled.
• Day Shift — runs during the day shift hours defined in System Config.
• Mid Shift — runs during the mid shift window.
• Night Shift — runs during the night shift window.

Configuring Shift Times

Open System Config (gear icon in the top bar) → Shift Config tab. Edit each shift's start and end time (24h format, e.g. 08:00 to 16:00).

Screen Alert checks the current time against shift definitions before running each task. If the task's shift window is not active, the task is skipped silently (no log spam).

Troubleshooting

OCR shows "condition not met" but the text is there

Check the log panel — it now shows the exact recognized text and matching condition. Common causes:

• The overlay box includes too much background (tighten it around the text).
• Spaces in the recognized text don't match your target. Screen Alert strips all whitespace before comparison for String Contains mode.
• The alert condition is not what you expect — switch between English and Chinese to verify the stored condition key.

High CPU usage

The adaptive thread pool auto-adjusts based on CPU load. If CPU stays high:

• Reduce the number of active tasks.
• Increase Detection Freq on less time-sensitive tasks.
• Switch log mode to "No Save" in System Config.

DPI Scaling Issues

Screen Alert adjusts overlay coordinates for Windows DPI scaling. If the overlay box is offset from the actual detection area, check that your display scaling (125%, 150%, etc.) matches across all monitors.

Telegram QR code not working

• Use your phone's camera app or browser to scan — not Telegram's built-in QR scanner.
• If the code expired, click Refresh QR in the login screen.
• If you've already started the bot before, manually send /start <bindCode> in the bot chat.

Click tasks interfering with each other

Only one click task can run at a time. Post-trigger actions also use the same global lock. If you need simultaneous clicks, consider using hotkey actions (which don't use the mouse lock) or combining actions into a single task.