Proposal: Add Scripting / Macro Language Support for Advanced Scenarios

[Night-Traders-Dev]

Hi @Nain57 and community,

First, thank you for maintaining Klick’r. It’s already one of the most powerful and unique auto-clickers on Android, especially with its image detection, scenarios, and flexible action system.

I’d like to propose a new feature idea that could make Klick’r even more versatile: adding scripting / macro language support.

---

Motivation

Currently, Klick’r lets users build automation through triggers (image, timer, counter, broadcast) and actions (clicks, swipes, intents, system actions, etc.). This is already very capable, but some workflows remain difficult to express purely with the GUI.

Examples:

Conditionals like “if image A appears within 10s, click it, else if image B appears, go back”

Loops for repeated actions until a certain state is detected

Parameterized routines (reuse the same set of actions with different inputs)

State-based workflows that depend on past outcomes

Adding a scripting/macro layer would:

Enable more expressive logic (if/else, loops, variables, branching).

Allow reusable automation blocks instead of recreating similar sequences in multiple scenarios.

Support complex multi-step workflows with fallbacks and retries.

Provide better debugging and logging for advanced users.

---

Possible Design

Here’s one way this could work:

1. Script Action Node

Inside a scenario, allow inserting a “Run Script” action.

The script would have access to Klick’r’s API (image detection, click, swipe, delay, system actions, etc.).

2. Lightweight Script Engine

Could embed a small, well-known engine like Lua or Rhino (JavaScript).

Or implement a simple domain-specific language (DSL) tailored to automation.

3. Core API Ideas

image.exists("Name") → check if an image is currently visible.

image.waitFor("Name", timeout) → block until image appears or timeout expires.

click(x, y) / click(image) → simulate taps.

swipe(x1, y1, x2, y2, duration) → swipes.

delay(ms) → wait for a fixed time.

system.back() / system.home() → trigger Android navigation actions.

log("message") → send debug info to console.

Variables and counters available as global objects.

4. Error Handling

Scripts should be able to handle “image not found” or timeout gracefully.

Could support try/catch or simple fallback logic.

5. Sandboxing & Safety

Scripts should be sandboxed to avoid security risks.

Restrict access to sensitive APIs unless explicitly allowed.

---

Example Script Snippets

Example 1: Conditional Action

var start = image.waitFor("StartButton", 10000);
if (start.found) {
    click(start.x, start.y);
    var confirm = image.waitFor("Confirm", 5000);
    if (confirm.found) {
        click(confirm.x, confirm.y);
    } else {
        system.back();
    }
} else {
    log("StartButton not found within 10s");
}

Example 2: Loop Until Victory

local maxTries = 5
for i=1, maxTries do
    click(image.get("Play"))
    if image.waitFor("Victory", 15000).found then
        click(image.get("Victory"))
        break
    else
        click(image.get("Retry"))
        delay(2000)
    end
end

---

Benefits

Advanced users (testers, automation enthusiasts) can design more intelligent workflows.

Reusability: shareable scripts for common tasks (retry loops, conditional flows).

Future extensibility: community can contribute script libraries.

Keeps UI clean: casual users can still rely on GUI scenarios; scripting is optional.

---

Challenges

Learning curve: scripting may overwhelm non-technical users → solution: keep it optional.

Performance: need safeguards against infinite loops or high-frequency polling.

Debugging: must include logging and maybe a “dry run” mode.

Security: sandbox scripts, prevent malicious behavior when sharing.

---

Suggested Next Steps

1. Add a minimal script action node to scenarios.

2. Prototype a simple scripting API (click, delay, image.exists) to test feasibility.

3. Gather community feedback on preferred language (Lua, JS, or DSL).

4. Iterate with small examples before expanding to full scripting support.

---

Closing Thoughts

Adding scripting would elevate Klick’r from a powerful auto-clicker into a general-purpose mobile automation platform.

Would love to hear thoughts from the maintainer and community:

Would this fit Klick’r’s roadmap?

Which scripting approach seems most practical?

Any major concerns around performance, UX, or Android restrictions?

Thanks again for the great work on Klick’r!