AnkuLua Helper - VSCode Extension

Enhanced Lua 5.1.5 support for AnkuLua development in Visual Studio Code

🌟 Overview

AnkuLua Helper is a comprehensive VSCode extension that provides complete IDE support for AnkuLua - an Android automation framework based on Lua 5.1.5. This extension brings professional development tools to AnkuLua scripting with syntax highlighting, intelligent autocomplete, hover documentation, and code snippets.

✨ Features

🎨 Syntax Highlighting

• Full Lua 5.1.5 syntax highlighting with AnkuLua-specific patterns
• Support for all AnkuLua objects (Pattern, Region, Location, Match)
• Highlighting for AnkuLua-specific functions and constants

🔍 Intelligent Autocomplete

• Complete API autocompletion for all AnkuLua functions
• Context-aware suggestions for objects and methods
• Parameter hints and function signatures

📚 Documentation on Hover

• Rich hover information for all AnkuLua functions
• Parameter descriptions and usage examples
• Return value documentation

⚡ Code Snippets

• Ready-to-use code templates for common patterns
• Function templates with proper parameter placeholders

🛠️ Configuration

• Customizable settings for different projects
• Support for multiple screen resolutions
• Configurable linting and validation

📦 Installation

1. Install from VSCode Marketplace

   # Open VSCode and search for "AnkuLua Helper"
   # Or visit: https://marketplace.visualstudio.com/items?itemName=kakuzu.ankulua-helper
   

2. Install from VSIX (for developers)

   # Clone the repository
   git clone https://github.com/spectral-root/ankulua-helper.git
   cd ankulua-helper
   
   # Install dependencies
   npm install
   
   # Compile the extension
   npm run compile
   
   # Package the extension
   npm run package
   
   # Install in VSCode
   code --install-extension ankulua-helper-0.1.0.vsix
   

🚀 Quick Start

1. Create a new Lua file (.lua extension)

2. Start typing AnkuLua code - you'll get full IntelliSense support

3. Configure your screen dimensions in VSCode settings:

   {
     "ankulua.path": "/path/to/your/scripts",
     "ankulua.enableLint": true
   }
   

4. Example script with full IDE support:

   -- Settings (always set these first!)
   Settings:setCompareDimension(true, 1280)
   Settings:setScriptDimension(true, 1280)
   
   -- Your AnkuLua automation code here
   click("button.png")
   wait("loading.png", 10)
   
   if exists("success.png", 5) then
       toast("✅ Success!")
   end
   

📚 Complete AnkuLua API Reference

This extension provides full IntelliSense support for the complete AnkuLua API. Below is the comprehensive reference:

🔷 Core Objects

1. Location - Coordinate System

-- Create coordinates
loc = Location(x, y)

-- Location methods
x = loc:getX()
y = loc:getY()
offsetLoc = loc:offset(dx, dy)
expandedLoc = loc:grow(pixels)
typeName = typeOf(loc)  -- Returns "Location"

2. Pattern - Enhanced Image Matching

-- Basic pattern
pat = Pattern("image.png")

-- Advanced pattern configuration
pat:similar(0.8)           -- Set similarity threshold (0.0-0.99)
pat:targetOffset(10, 20)   -- Click offset from match center
pat:mask("mask.png")       -- Use mask for variable backgrounds
pat:color()                -- Force color matching
pat:gray()                 -- Force grayscale matching

-- Pattern information
offset = pat:getTargetOffset()  -- Returns Location
filename = pat:getFileName()    -- Returns string
isColor = pat:isColor()         -- Returns boolean

3. Region - Screen Area Definition

-- Define screen areas for faster searching
region = Region(x, y, width, height)

-- Region methods
center = region:getCenter()      -- Returns Location
lastMatch = region:getLastMatch() -- Returns Match
x = region:getX()
y = region:getY()
w = region:getW()
h = region:getH()
newRegion = region:offset(dx, dy)

-- Search within region
region:click("button.png")
region:find("target.png")
region:exists("image.png", 5)
region:wait("image.png", 10)

4. Match - Successful Find Result

-- Result of successful find operation
match = find("target.png")
score = match:getScore()     -- Similarity score (0.0-1.0)
center = match:getCenter()   -- Center Location
target = match:getTarget()   -- Target Location

-- Match extends Region, so all Region methods work
match:highlight(3)           -- Highlight for 3 seconds

---

🔷 Basic Methods (Sikuli Compatible)

Search & Click Operations

-- click(PSMRL) - Pattern/String/Match/Region/Location
click("button.png")
click(Pattern("btn.png"):similar(0.9))
click(Location(100, 200))
click(match)

-- find(PS) - Returns Match or throws exception
match = find("target.png")

-- findAll(PS) - Returns table of matches
matches = findAll("coin.png")
for i, m in ipairs(matches) do
    click(m)
end

-- wait(PS, seconds) - Wait until found
match = wait("loading.png", 30)

-- exists(PS, seconds) - Check existence without exception
if exists("button.png", 5) then
    click("button.png")
end

-- waitVanish(PS, seconds) - Wait until disappears
waitVanish("loading.png", 30)

Enhanced Click Methods

-- waitClick(PSMRL, seconds) - Wait and click, throws on timeout
match = waitClick("button.png", 10)

-- existsClick(PSMRL, seconds) - Click if found, no exception
if existsClick("optional.png", 5) then
    print("Clicked optional button")
end

-- doubleClick(PSMRL)
doubleClick("icon.png")
doubleClick(Location(500, 300))

Drag & Drop Operations

-- dragDrop(source, target)
dragDrop("item.png", "slot.png")
dragDrop(Location(100, 200), Location(300, 400))

-- Configure drag timing (critical for some games)
setDragDropTiming(downMs, upMs)      -- Press/release duration
setDragDropStepCount(steps)          -- Number of movement steps
setDragDropStepInterval(ms)          -- Delay between steps

-- Example: slower drag for precision
setDragDropTiming(500, 500)  -- 500ms press and release
setDragDropStepCount(50)     -- 50 movement steps
setDragDropStepInterval(10)  -- 10ms between steps
dragDrop("card.png", "deck.png")

Text Input & Control

-- type([target,] text) - Type text
type("Hello World")              -- At current focus
type("field.png", "username")    -- Click field first

-- For UTF-8 input in root/daemon mode:
setClipboard("你好")              -- Set clipboard
keyevent(279)                    -- KEYCODE_PASTE

-- Keyboard shortcuts
keyevent(4)     -- KEYCODE_BACK
keyevent(3)     -- KEYCODE_HOME
keyevent(187)   -- KEYCODE_APP_SWITCH
keyevent(26)    -- KEYCODE_POWER
keyevent(24)    -- KEYCODE_VOLUME_UP
keyevent(25)    -- KEYCODE_VOLUME_DOWN

Highlighting & Visual Feedback

-- Highlight regions/matches
region:highlight("Label", 5)     -- 5 seconds with text
match:highlight()                -- Default duration
match:highlightOff()             -- Remove highlight
match:highlightUpdate("New text")

-- Customize highlight style
setHighlightStyle(0x80FF0000, true)    -- Semi-transparent red, filled
setHighlightTextStyle(0xFF000000, 0xFFFFFFFF, 20)  -- Black bg, white text, size 20

---

🔷 AnkuLua-Specific Methods

Advanced Touch & Gestures

-- Multi-touch gestures
touchDown(Location(100, 200))
touchMove(Location(200, 300))
touchUp(Location(200, 300))

-- Batch touch actions
setManualTouchParameter(5, 1)  -- maxDistance=5, insertWait=1ms
actionList = {
    {action = "touchDown", target = Location(100, 300)},
    {action = "wait", target = 0.2},
    {action = "touchMove", target = Location(400, 300)},
    {action = "touchUp", target = Location(400, 300)}
}
manualTouch(actionList)

-- Zoom gestures
zoom(p1StartX, p1StartY, p1EndX, p1EndY,
     p2StartX, p2StartY, p2EndX, p2EndY, steps)

-- Long click
longClick("button.png", 2)        -- Hold for 2 seconds
longClick("button.png")           -- Hold until stopLongClick()
stopLongClick()

-- Continuous clicking
continueClick(x, y, xRandom, yRandom, times)
continueClick("button.png", 10)  -- Pattern-based
setContinueClickTiming(50, 100)  -- 50ms down, 100ms interval

-- Multi-touch
list = {Pattern("btn1.png"), "btn2.png", Location(100, 200)}
continueMultiTouch(list, 3)      -- Each target clicked 3 times

Screen Capture & Image Operations

-- Save region/match as image
match = find("target.png")
match:save("captured.png")           -- Grayscale
match:saveColor("captured_color.png") -- Color

region = Region(100, 100, 200, 200)
region:save("region_capture.png")

OCR (Optical Character Recognition)

-- Number OCR (requires digit0.png to digit9.png)
region = Region(100, 100, 200, 50)
number = numberOCR(region, "digit")
number, success = numberOCRNoFindException(region, "digit")

-- Character OCR
charTable = {
    {target = "a.png", char = "a"},
    {target = "b.png", char = "b"},
    {target = "1.png", char = "1"}
}
text = charOCR(region, charTable)
text, success = charOCRNoFindException(region, charTable)

Color Detection

-- getColor(PSMRL) - Returns R, G, B values
r, g, b = getColor("pixel.png")
r, g, b = getColor(Location(500, 300))

-- Color-based logic
if g > 150 and r < 100 and b < 100 then
    print("Green pixel detected")
elseif r == g and r == b then
    print("Grayscale pixel")
end

---

🔷 Settings & Configuration

Dimension Management (Critical!)

-- ⚠️ CRITICAL: Always set these at script start!
Settings:setCompareDimension(true, 1280)  -- Match images at 1280 width
Settings:setScriptDimension(true, 1280)   -- Script coordinates at 1280 width

-- For different device resolutions:
-- 720p, 1080p, 1440p, etc.

Image Path Management

-- Default: searches in scriptPath() .. "image/"
click("button.png")  -- Looks for: scriptPath() .. "image/button.png"

-- Custom image folder:
setImagePath(scriptPath() .. "assets/")
click("button.png")  -- Now looks for: scriptPath() .. "assets/button.png"

-- Shared images folder:
setImagePath("/sdcard/AnkuLua/shared_images/")

Performance & Quality Settings

-- Similarity threshold (global)
Settings:set("MinSimilarity", 0.8)

-- Action timing
Settings:set("ActionDelay", 1.0)  -- Delay between actions (seconds)

-- Alternative click method (for some games)
setAlternativeClick(true)

-- Scan rate
setScanInterval(0.5)    -- Check every 0.5 seconds
setScanRate(2)         -- 2 checks per second

-- Snapshot management
usePreviousSnap(true)   -- Reuse snapshots for speed
snapshot()              -- Take new snapshot
usePreviousSnap(false)

-- Image cache
ImageCache:setCheckEnable(true)
ImageCache:setUpdateEnable(true)
ImageCache:setImageSizeLimit(2000000)  -- 2MB limit
ImageCache:setCacheNumber(50)          -- Cache up to 50 images

Screen & Game Area

-- Immersive mode (hide navigation bars)
setImmersiveMode(true)

-- Auto-detect game area (for games with black bars)
autoGameArea()

-- Manual game area definition
setGameArea(x, y, width, height)

-- Get current game area
x, y, w, h = getGameArea()

-- Screen dimensions
width, height = getAppUsableScreenSize()  -- Usable area
width, height = getRealScreenSize()       -- Real screen size

---

🔷 Device Information & Control

Device Information

-- AnkuLua version and device info
version = getVersion()
androidVersion = getAndroidVersion()  -- API level
language = getLanguage()              -- "en", "zh", "pt", etc.
country = getCountry()                -- "US", "CN", "BR", etc.
scriptDir = scriptPath()              -- Current script directory

-- Device identifiers (Pro features)
deviceID = getDeviceID()
imei = getIMEI()
simSerial = getIMSI()
wifiMac = getWiFiMAC()
macAddr = getMacAddr()
userID = getUserID()  -- Pro2 only

-- Device state
isCharging = chargerConnected()
battery = batteryLevel()        -- 1-100
isEmu = isEmulator()

-- Recovery state
isRecovered = isRecoveredFromKilled()
setRecoveredFromKilled(false)

User Interface & Dialogs

-- Toast messages
toast("Hello World!")
toast("Progress: " .. progress .. "%")

-- Dialogs (important: always use newRow() for good layout!)
dialogInit()
addTextView("Select options:")
newRow()  -- Critical for proper layout!
addEditText("username", "Enter username")
addEditPassword("password", "")
addCheckBox("remember", "Remember me", true)

-- Radio buttons
newRow()
addRadioGroup("difficulty", 1)  -- defaultIndex
addRadioButton("Easy", 0)
addRadioButton("Normal", 1)
addRadioButton("Hard", 2)

-- Spinner (dropdown)
options = {"Option 1", "Option 2", "Option 3"}
addSpinner("choice", options, "Option 2")

-- Show dialog
dialogShow("My Dialog Title")
dialogShowFullScreen("Settings")

-- Persistent preferences
preferencePutString("username", "player123")
preferencePutNumber("highscore", 1000)
preferencePutBoolean("soundEnabled", true)

username = preferenceGetString("username", "guest")
highscore = preferenceGetNumber("highscore", 0)
soundEnabled = preferenceGetBoolean("soundEnabled", true)

App Control

-- Launch and manage apps
startApp("com.example.game")
killApp("com.example.game")  -- daemon/root only

-- Find package names from Google Play URLs:
-- https://play.google.com/store/apps/details?id=PACKAGE_NAME

---

🔷 Network & Connectivity

-- ⚠️ Must be enabled in AnkuLua settings first!

-- HTTP requests
setHttpTimeout(30)  -- 30 seconds timeout

response = httpGet("https://api.example.com/data")
if response then
    print(response)
end

-- POST requests
params = {
    username = "player",
    score = "1000"
}
response = httpPost("https://api.example.com/submit", params)

-- File downloads
httpDownload("https://example.com/image.png", "/sdcard/Download/image.png")

-- Open URLs (pauses script)
openUrl("https://example.com")

-- Email (requires Gmail setup)
sendEmail("Subject", "Message body")
setExceptionEmail("Error Report", "An error occurred")

-- Reward account (Pro2)
setRewardAccount("email@example.com")

---

🔷 Timing & Control

-- Timer objects
timer = Timer()
wait(2)
elapsed = timer:check()      -- Time since creation/set
timer:set()                  -- Reset timer

-- Network time
networkTimeMs = getNetworkTime()
dateTable = os.date("*t", networkTimeMs / 1000)

-- Script control
scriptExit("Finished successfully")
setStopMessage("Final stats: 10 wins, 2 losses")

-- Load external scripts
dofile(scriptPath() .. "helper.lua")
require("mylib")  -- Needs proper package.path setup

---

🔷 Utilities & Helpers

-- Type checking (AnkuLua's enhanced type function)
-- Save Lua's type function first:
inputText = type
type = typeOf  -- Use AnkuLua's typeOf

-- Then check types:
t = typeOf(Location(100, 200))  -- Returns "Location"
t = typeOf(Pattern("img.png"))  -- Returns "Pattern"
t = typeOf(Region(0, 0, 100, 100))  -- Returns "Region"
t = typeOf(match)               -- Returns "Match"

-- Restore Lua's type:
luaType = inputText

⚙️ Configuration

VSCode Settings

{
  "ankulua.path": "/path/to/your/ankulua/scripts",
  "ankulua.enableLint": true,
  "ankulua.customSettings": {
    "defaultResolution": 1280,
    "imagePath": "image/",
    "similarityThreshold": 0.8
  }
}

AnkuLua Script Settings

Always configure these at the start of your scripts:

-- Required settings for proper operation
Settings:setCompareDimension(true, 1280)  -- Set your target resolution
Settings:setScriptDimension(true, 1280)   -- Match your script coordinates
setImmersiveMode(true)                     -- Hide navigation bars if needed

-- Optional performance settings
Settings:set("MinSimilarity", 0.8)         -- Similarity threshold
Settings:set("ActionDelay", 1.0)           -- Delay between actions
usePreviousSnap(true)                      -- For faster consecutive searches

🎯 Complete Code Examples

Example 1: Login Automation

-- ========== Settings ================
Settings:setCompareDimension(true, 1280)
Settings:setScriptDimension(true, 1280)
setImmersiveMode(true)

-- ========== Main Program ================
-- Wait for login screen
waitClick("login_button.png", 30)

-- Fill credentials
click("username_field.png")
wait(0.5)
type("player123")

click("password_field.png")
wait(0.5)
type("mypassword")

-- Submit
click("submit_button.png")

-- Wait for success
wait("home_icon.png", 30)
toast("✅ Login successful!")

Example 2: Resource Collection with Error Handling

-- ========== Settings ================
Settings:setCompareDimension(true, 1280)
Settings:setScriptDimension(true, 1280)

-- ========== Main Loop ================
collected = 0
maxCollections = 50
timer = Timer()

while collected < maxCollections do
    -- Check for timeout (30 minutes)
    if timer:check() > 1800 then
        scriptExit("30 minute limit reached")
    end

    -- Look for resources (with error handling)
    resources = findAllNoFindException("resource.png")

    if resources then
        for i, resource in ipairs(resources) do
            click(resource)
            wait(0.5)

            -- Click collect if available (safe click)
            if existsClick("collect.png", 2) then
                collected = collected + 1
                toast("📦 Collected: " .. collected .. "/" .. maxCollections)
            end
        end
    end

    wait(5)  -- Wait before next scan
end

setStopMessage("✅ Collected " .. collected .. " resources")

Example 3: Advanced Battle Automation

-- ========== Settings ================
Settings:setCompareDimension(true, 1280)
Settings:setScriptDimension(true, 1280)

-- ========== Configuration Dialog ================
dialogInit()
addTextView("🎮 Battle Configuration")
newRow()
addEditNumber("troopCount", 10)
addCheckBox("useSpells", "Use spells", true)
addSpinner("difficulty", {"Easy", "Normal", "Hard"}, "Normal")
dialogShow("Battle Settings")

-- ========== Main Program ================
-- Select and deploy troops
if existsClick("troop_icon.png", 5) then
    toast("⚔️ Deploying troops...")

    for i = 1, troopCount do
        local x = math.random(200, 1080)
        local y = math.random(300, 600)
        click(Location(x, y))
        wait(0.3)
    end

    -- Use spells if enabled
    if useSpells then
        wait(2)
        if existsClick("spell_icon.png", 5) then
            click(Location(640, 400))  -- Center
            toast("✨ Spell cast!")
        end
    end

    -- Wait for battle completion
    waitVanish("battle_indicator.png", 180)
    toast("🏆 Battle completed!")
else
    toast("❌ Troop selection failed")
end

🔧 Development

Building from Source

# Clone the repository
git clone https://github.com/spectral-root/ankulua-helper.git
cd ankulua-helper

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Watch for changes (development)
npm run watch

# Package for distribution
npm run package

Project Structure

ankulua-helper/
├── src/
│   ├── api/
│   │   └── ankuluaAPI.ts       # Complete API definitions
│   ├── providers/
│   │   ├── completionProvider.ts  # Autocomplete logic
│   │   ├── hoverProvider.ts       # Hover documentation
│   │   └── signatureHelpProvider.ts
│   └── extension.ts            # Main extension entry point
├── syntaxes/
│   └── lua.tmLanguage.json     # Lua syntax highlighting
├── snippets/
│   └── ankulua.json           # Code snippets (to be created)
├── AnkuLua.png                # Project logo
├── package.json              # Extension manifest
└── README.md                 # This file

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Report Issues: Use GitHub Issues for bug reports and feature requests
2. Submit Pull Requests: Fork the repository and submit PRs
3. Improve Documentation: Help expand the API documentation
4. Add Snippets: Create useful code templates for the community

Development Guidelines

• Ensure all code follows TypeScript best practices
• Add proper JSDoc comments for all public APIs
• Test changes with different VSCode versions
• Update documentation for any API changes

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• AnkuLua Team for creating the amazing automation framework
• VSCode Team for the excellent extension API
• Community Contributors for their valuable feedback and improvements

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@example.com

---