Skip to content

Your First Script

Jump to bottom
Claude edited this page Oct 16, 2026 · 3 revisions

Your First Script

Scripts are written on a computer in VS Code and run on the phone over Wi-Fi. This page goes from installing the extension to a script that opens Android Settings and taps something it recognizes on screen. Details of each step are in the extension README; the API is in docs/lua-api.md (in Traditional Chinese).

The extension follows VS Code's display language (English or Traditional Chinese); the labels below are the English ones.

What a script is

A script is a folder on the phone containing main.lua, optionally script.json (name, description, and the virtual display it wants), and any template images it uses.

1. Install the extension

You need VS Code 1.90 or later (or an editor that uses Open VSX, such as VSCodium or Cursor) and a phone on the same Wi-Fi network. Search for MoonClicker in the Extensions view and install MoonClicker Script Workbench; it updates automatically.

The extension and the app must share the same first two version numbers (for example, extension 0.5.x with app 0.5.x).

2. Turn on Script Workbench on the phone

  1. In MoonClicker, go to Settings → About and tap the version number seven times to unlock Developer options.
  2. Open Settings → Developer options, turn on Script Workbench, and tap Start Pairing Mode. A six-digit PIN appears, valid for five minutes.

On Android 17, also grant Local Network Permission under Settings → Permissions & System Features, or VS Code can't connect.

3. Connect

  1. In VS Code, open the MoonClicker Scripts view in the activity bar and click Connect to Device.
  2. Pick your phone from the list. If it isn't found, choose Enter IP:port manually and type the server address shown under Script Workbench on the phone.
  3. Enter the PIN.
  4. The first time, VS Code asks for a local folder to keep this phone's scripts in. Choose an empty folder; it opens in the current window. Each script on the phone becomes a subfolder, and changes sync both ways while connected.

4. Create a script

Click New Script in the view's title bar and enter a name such as hello (lowercase letters, digits, ., _, -). Its main.lua opens.

Give it a virtual display so it runs in the background: open hello/script.json and make it

{
  "uniqueId": "hello",
  "name": "Hello",
  "display": { "width": 720, "height": 1280 }
}

Then write main.lua:

log("hello from MoonClicker")
app.launch("com.android.settings")
sleep(2000)

5. Run it

With main.lua focused, press F5. VS Code saves, syncs, and runs the script on the phone: it creates the virtual display and opens Settings there. Logs appear in VS Code's Output panel under MoonClicker Script Log. Shift+F5 stops a running script; if several are running, VS Code asks which one.

Scripts on different displays can run at the same time, each with its own notification, logs, and data. A display runs one script at a time, so running another script on a busy display reports which script is using it.

6. Recognize something on screen

  1. Open the Workbench panel from the view's title bar. It shows the virtual display live; switch to it if another display is selected.
  2. In 1 · Capture, click Capture now. Then in 2 · Build templates, drag a box around something in Settings, such as the search icon, pick hello as the script, enter search as the template name, and click Save template. The image is saved as search.png in the script folder and syncs back to your computer.
  3. Replace sleep(2000) with:
local hit = vision.wait("search.png", 5000)
if hit then
    log("found at", hit.cx, hit.cy)
    input.tap(hit.cx, hit.cy)
else
    log("not found")
end
  1. Press F5 again. The script waits up to five seconds for the icon and taps it.

To find text instead of an image, use vision.wait({ text = "Search" }) after downloading the OCR component (Run the Example, step 1). The Workbench panel can test both templates and OCR against the live screen before you write the code. Example Walkthrough shows a larger script.

Home

English

正體中文

Clone this wiki locally