Skip to content
This repository has been archived by the owner on Oct 18, 2022. It is now read-only.

Latest commit

 

History

History
1681 lines (1247 loc) · 59.2 KB

en.md

File metadata and controls

1681 lines (1247 loc) · 59.2 KB

AutoTouch Documentation

Applicable for v5.0.6 and above

  • AutoTouch is a 'Macro' tool used to record and playback human-like inputs on an IOS device.
  • It is able simulate touch and key presses, through Lua scripting.
  • It has several extended functions to help you achieve automation.
  • It provides a Script Store to sell and buy scripts.
  • Requires a supported jailbroken device (jailbreaks on IOS 8 to IOS 12.1.2), uses Lua 5.3.5

Normal releases can be found at http://apt.autotouch.net. Beta releases can be found at http://beta.autotouch.net

Note: AutoTouch will also be referred to as 'AT' throughout this document.

AutoTouch Documentation Installation Usage How do I use Activator with AutoTouch? How do I record scripts? How do I play back a script? How do I set play settings for script? How do I take a screenshot? How do I start writing scripts? How do I use the "Function Helper" while writing scripts? How do I write and manage scripts on a computer? What is a package and how do I use it? How do I encrypt scripts? How do you sell scripts in Script Store? How do I download and buy scripts from Script Store? How do I buy a AutoTouch license? Scripting Basis Development Tools Coordinate, Size and Orientation System Extension Libraries Lua-cURL LuaSocket LuaSec luaSqlite3 LuaFileSystem Extension Functions touchDown(id, x, y) touchUp(id, x, y) Tap(x, y) touchMove(id, x, y) keyDown(keyType) keyUp(keyType) getColor(x, y) getColors(locations) findColor(color, count, region) findColors(colors, count, region) findImage(imagePath, count, fuzzy, ignoreColors, region) findImage2(targetImagePath, targetsToFind) screenshot(filePath, region) appRun(appIdentifier) appKill(appIdentifier) appState(appIdentifier) rootDir() usleep(microseconds) log(content) alert(message) toast(message, delay) vibrate() playAudio(audioFile, times) stopAudio() getOrientation() getScreenResolution() getSN() getVersion() intToRgb(intColor) rgbToInt(r, g, b) copyText(text) clipText() inputText(text) dialog(controls, enableRemember) clearDialogValues(script) openURL(urlString) isLicensed() Play a script Stop playing a script List files in directory Create a new directory Create a new file Delete a file Rename a file or directory Some Constants Types of physical keys Types of dialog controls Types of screen orientations

Installation

  • You can search and install AutoTouch in Cydia directly from the BigBoss repo.
  • You can also add the official repo: http://apt.autotouch.net to Cydia and install AutoTouch there.
  • There is also a beta repo: http://beta.autotouch.net which has in-progress builds that can be unstable but features are developed much faster

If you are experiencing issues with AutoTouch please first check for updates in Cydia and see if this remedies your issue(s).

Usage

How do I use Activator with AutoTouch? (depends on IOS compatibility)

  • By default the AutoTouch menu pops up when the volume down button is held. This default behavior can changed by installing Activator.

  • Add the official repo: http://rpetri.ch/repo/ to Cydia. Activator may not support your version of IOS properly, so make sure to check with others.

    (Jailbreaking discord is a suitable place to ask: https://discord.gg/bHdzaab)

  • Install Activator from that repo.

  • AutoTouch will automatically detect Activator and use it as the default control method. From there you can set what actions will bring up the AutoTouch control panel.

How do I record scripts?

  1. Bring up the AutoTouch control panel by using your chosen activation method

Default is to hold the volume down unless you changed it with the Activator tweak. Control Panel

  1. Press the "Record" button to start recording.

  2. All touch and key inputs will be recorded into a script.

  3. Hold on volume decrease button (or chosen Activator method) again to stop the recording.

  4. Then, there will be a Lua script named with create time in the script list. You can edit, rename or play it back.

Common state->Control panel: Hold volume button
Control panel->Recording: Click on 'Record'
Recording-->Common state: Hold volume down button again

How do I play back scripts?

  1. Use your chosen activation method to bring up the AutoTouch control panel.
  2. Click the script you want to run.
  3. The dialog for playback settings will pop up to determine the number of repeats, interval, and speed of the script. This can be bypassed by setting the script to "play directly" within the AutoTouch app itself

  1. Press the "Play" button on play settings dialog to play immediately.
  2. If you press the "Hold" button, it will enter the "Ready to play" status, which every time you quick press the volume down button, the script play back once based on the settings you provided it in the previous modal.
  3. Hold volume decrease button to forcibly stop the script playback, or quit the "Ready to play" status.
Common state->Control panel: Hold volume button
Control panel->Play settings: Select a script to play
Play settings->Ready to play state: Click the 'Hold' button
Ready to play state->Playing: Press volume button
Playing-->Ready to play state: Press volume button again
Play settings->Playing: Click the "Play" button
Playing-->Common state: Hold volume button

How do change 'play settings' for scripts?

  • You can set an Activator action to trigger a script directly.

  • Additionally you turn on "play directly" to skip the play settings dialog while playing.

Play Directly Panell

How do I take screenshots?

  1. Press “Snap” button on the AutoTouch control panel to take screenshot.
  2. The screenshot will be saved as 32-bit BMP image in the 'Screenshots' folder, which can be used to specify parameters of getColors, findColors or findImage and more in your scripts. AutoTouch needs image files to be in this format for most operations.

Alternatively you may also use the screenshots function to capture a screenshot via a script

How do I start writing scripts?

  • From within the AutoTouch app, press "+" button at the top right, choose “Create a script” to open the script editor.
  • Start writing Lua code!
  • Press "save" button to save the script.

How do I use the "Function Helper" while writing scripts?

  • There are "Extensions", "Indent" and "Statements" buttons on top of the keyboard in the script editor. You can conveniently insert extended functions, indent or common statement of Lua Language.
  • Press the "Extension" button to be presented with the extended functions list, click a function to insert into the script.
  • Press the "HELPER" button on the function list, it will help you to determine the coordinates, colors or key flags for the functions.
Function Help1 1 of 4
Function Help2 2 of 4
Function Help3 3 of 4
Function Help4 4 of 4

How do I write and manage scripts on a computer?

s
  • Turn on the Web Server in AutoTouch settings and visit the URL that appears just below,on you preferred browser. You can manage scripts remotely from there.
  • You can also turn on WebDAV Server and connect the told address with WebDAV client on computer.

What is a package and how do I use it?

  • You can create a package as sort of script project/folder that will contain different scripts, files and images etc. Packages must have a main.lua file which will be run first when executing it through AutoTouch. A package is like a zip file and also support encryption, they are named with .at extension i.e myFirstPackage.at.
  • Package can be encrypted to xxx.ate which is also execuate-able and can be released to Script Store.

How do I encrypt scripts?

  1. Tap accessory button of a package or script in the local script list, choose "Encrypt".
  2. Input the encryption password or leave it blank if you do not want one.
  3. Press "Confirm" to complete the encryption. A encrypted file with the same name but ended with .lua.e or .ate will be generated in the script list then.
  4. You can play the encrypted scripts, or release them to Script Store.

How do I sell scripts on the store?

  1. Visit https://autotouch.net/server/login.php from browser on computer.
  2. Complete the details required to create a new script.
  3. Create a detailed description and nice looking mobile suitable html page for the script, a YouTube video embeded within the page is preferred.
  4. Upload a encrypted script or package as a new version to this script.
  5. Wait for approval.
  6. You should setup the Digital Rights Management in the script by yourself, AutoTouch Script Store can not help you with that currently.

Note: low-effort/recorded scripts will not be accepted please make sure they add something unique!

How do I download and buy scripts from Script Store?

  • You can directly download scripts from the store within the AutoTouch app.
  • You need to contact the author to buy the decryption password. Take care with the transaction,all effort is made to ensure on high quality scripts are uploaded but AutoTouch cannot prevent an author from scamming you, so take care with the payment. Any abuse will lead to a ban from the platform.

How do I buy a AutoTouch license?

  1. Tap License on AutoTouch settings to enter the license management view.
  2. Read the instructions and do be aware that AutoTouch license has a ONE YEAR validity period!
  3. It will automatically activate current device after the payment if you use PayPal (If failed just follow the next step).
  4. You can query bought licenses with your PayPal ID email, or any activated device SN.
  5. You can activate another device with a license after you query it out.
  6. You can also "Activate Current Device" diretly with a license key bought from other devices.
  7. You should make sure it shows "License Downloaded" at top-right of the License view after it is activated.
  8. It allows only one time activation a day, you may do it again after 24 hours if you need.
License

Scripting

References and Tutorials

You can learn how to use Lua language from here:《Lua Official Reference Manual》

For further reading consider:

  • Programming in Lua - By purchasing these books your money goes straight to supporting the developers of Lua and if you purchase the e-book it comes as DRM free
  • Lua-wiki Tutorial - Moderate intro to lua, for people somewhat comfortable with programming concepts already
  • Lua Crash Course - Course that runs through everything at a very fast pace, you wont understand much at first, slightly technical
  • Tutorialspoint - Lua Course - Free, self contained Lua course for beginners, recommended. The content itself is a bit bland due to a lack of colors or pictures but stick with it
  • LÖVE - Lua game engine - LÖVE is an awesome framework you can use to make 2D games in Lua. It's free, open-source, and works on Windows, Mac OS X, Linux, Android and iOS.

Development Tools

ZeroBrane Studio is a lightweight free/pay what you want open-source Lua IDE with code completion, syntax highlighting, code analyzer, live coding, and debugging support for Lua 5.1, Lua 5.2, Lua 5.3, LuaJIT, and other Lua engines.

A user created a ZeroBrane plugin that integrates all AutoTouch functions, autocomplete and definitions lookup. Get it here

LuaStudio is a professional development environment for debugging Lua script in your applications. It's quite fast but is only based on Lua 5.2 whilst AutoTouch now uses Lua 5.3. The site periodically goes down, not recommended.

AutoMainPNG - JP/Eng (English is little hard to understand) paid scripting editor made specifically for AutoTouch. Costs money to unlock further features, pretty great idea for scripting noobs but needs clearer translation.

Coordinate, Size and Orientation System

AutoTouch uses pixel based Native Resolution as the coordinate and size system. Resolutions of different iOS devices are here however Apple has not updated it since 2017.

For example: The screen size of iPhone X is 1125 x 2436.

Origin point (0, 0) is always at the top left of the Application Interface, regardless of the device orientation. This concept is used in these functions:

  • Touch emulation:
    • touchDown,touchMove,touchUp,
  • Return color values of x, y cordinates:
    • getColor, getColors
  • Find specified color values:
    • findColor, findColors
  • Find a match to a specified image:
    • findImage, findImage2

Cordinates Example

Extension Libraries

AutoTouch has some extension libraries built in, while you can also add these libraries by yourself, just place.so files at /usr/local/lib/lua/5.3 and .lua files at /var/mobile/Library/AutoTouch/Library/LuaLibraries.

Warning: DO NOT use script filename same as the libraries’ name, such as lcurl, lfs, lsqlite3

Lua-cURL

cURL is a command-line tool for getting or sending data including files using URL syntax. It supports communicating with HTTP, HTTPS, FTPS, and many, many more.

AT implements Lua-cURL V3 for cURL support.

Documentation

Github project

Examples

-- HTTP Get
local curl = require('lcurl')
curl.easy{
    url = 'http://httpbin.org/get',
    httpheader = {
      "X-Test-Header1: Header-Data1",
      "X-Test-Header2: Header-Data2",
    },
    writefunction = alert -- use io.stderr:write()
  }
  :perform()
:close()

-- HTTP Post
curl.easy()
  :setopt_url('http://posttestserver.com/post.php')
  :setopt_writefunction(io.write)
  :setopt_httppost(curl.form() -- Lua-cURL guarantee that form will be alive
    :add_content("test_content", "some data", {
      "MyHeader: SomeValue"
    })
    :add_buffer("test_file", "filename", "text data", "text/plain", {
      "Description: my file description"
    })
    :add_file("test_file2", "BuildLog.htm", "application/octet-stream", {
      "Description: my file description"
    })
  )
  :perform()
:close()

LuaSocket

LuaSocket is a Lua extension library which supported TCP, UDP, SMTP, HTTP, FTP protocols. Learn how to use it from here](http://w3.impa.br/~diego/software/luasocket/introduction.html).

LuaSec

LuaSec is a binding for OpenSSL library to provide TLS/SSL communication. It takes an already established TCP connection and creates a secure session between the peers. Learn More

LuaSqlite3

LuaSQLite 3 is a thin wrapper around the public domain SQLite3 database engine. Learn More

Examples

local sqlite3 = require("lsqlite3")

local db = sqlite3.open_memory()

db:exec[[
  CREATE TABLE test (id INTEGER PRIMARY KEY, content);

  INSERT INTO test VALUES (NULL, 'Hello World');
  INSERT INTO test VALUES (NULL, 'Hello Lua');
  INSERT INTO test VALUES (NULL, 'Hello Sqlite3')
]]

for row in db:nrows("SELECT * FROM test") do
  log(row.content)
end

LuaFileSystem

LuaFileSystem is a Lua library developed to complement the set of functions related to file systems offered by the standard Lua distribution. It offers a portable way to access the underlying directory structure and file attributes.Learn More

Extension Functions

Extension functions are used to extend Lua language. With these the device can simulate most human inputs and also achieve automation. Some of these are: screenshot, color searching, color matching, and picture matching.

touchDown(id, x, y)

Presses a coordinate (x,y) on the screen.

Parameters

Parameter Type Specification
id Integer Finger ID. Used to mark a finger in single-touch or multi-touch.
x Float x-coordinate on the screen
y Float y-coordinate on the screen

Return None

Examples

-- Press by one finger at coordinate (100,200).
touchDown(0, 100, 200); 

-- Press by three fingers at three locations on the screen.
touchDown(0, 100, 200);
touchDown(1, 200, 300);
touchDown(2, 300, 400);

-- Implement a tap function
function tap(x, y)
    touchDown(0, x, y);
    usleep(16000);
    touchUp(0, x, y);
end

-- Tap at (100, 200)
tap(100, 200);

touchUp(id, x, y)

Lift the finger from coordinate (x,y)

Parameters

Parameter Type Specification
id Integer Finger ID. Used to mark a finger in single-touch or multi-touch.
x Float x-coordinate on the screen
y Float y-coordinate on the screen

Return None

Examples

-- Click the screen with one finger at coordinate (100,200).
touchDown(0, 100, 200);
usleep(16000);
touchUp(0, 100, 200);

-- Press by three fingers at three locations on the screen, move to new location, and then lift the finger.
touchDown(0, 100, 200);
touchDown(1, 200, 300);
touchDown(2, 300, 400);
usleep(16000);
touchMove(0, 150, 250);
touchMove(1, 250, 350);
touchMove(2, 350, 450);
usleep(16000);
touchUp(0, 150, 250);
touchUp(1, 250, 350);
touchUp(2, 350, 450);

tap(x, y)

Taps with a single finger on the specified coordinate.

Parameters

Parameter Type Specification
x Float x-coordinate on the screen
y Float y-coordinate on the screen

Return None

Note: Tap has far less control due to its simplicity and has no built in randomness. It is recommended to overwrite tap when used in games as it easily detected as the length of the 'finger press' will always be the same Examples

--Example 1: Quickly taps once on the screen
tap(300, 435);
usleep(20000);

--Example 2: Uses findColors (discussed later) to look for a particular app icon on the home screen, logs it then taps the resulting co-ordinates. These sorts of cases are where its okay to use the unmodified tap function. In games its too easy to detect
local result = findColors({{3380451,0,0}, {16777215,1,0}, {9160301,6,0}, {3380451,-2,0}, {14133291,6,45}, {16764976,8,49}, {14556453,35,82}, {228316,-7,76}}, 0, nil);;
for i, v in pairs(result) do
	log(string.format("Found the app at: x:%f, y:%f", v[1], v[2]));
	log(getColor(v[1], v[2]));
	tap(v[1], v[2]);
end

touchMove(id, x, y)

Move the finger to coordinate (x,y).

Parameters

Parameter Type Specification
id Integer Finger ID. is used to mark a finger in single-touch or multi-touch.
x Float x-coordinate on the screen
y Float y-coordinate on the screen

Return None

Examples

-- Press one finger at coordinate (100,200) and move the finger to coordinate (200,200).
touchDown(0, 100, 200);
usleep(16000);
touchMove(0, 200, 200);

-- Press three fingers at three locations on the screen and move to new location.
touchDown(0, 100, 200);
touchDown(1, 200, 300);
touchDown(2, 300, 400);
usleep(16000);
touchMove(0, 150, 250);
touchMove(1, 250, 350);
touchMove(2, 350, 450);

keyDown(keyType)

Simulate the pressing of physical key.

Parameters

Parameter Type Specification
keyType Integer Physical key identification. Now you can use these physical keys.

Return None

Examples

-- Simulate the pressing of Home Key.
keyDown(KEY_TYPE.HOME_BUTTON);

-- How to simulate a key pressing?
function keyPress(keyType)
    keyDown(keyType);
    usleep(10000);
    keyDown(keyUp);
end
keyPress(KEY_TYPE.HOME_BUTTON);

-- How to simulate a screen lock function?
function lockScreen()
    keyDown(KEY_TYPE.POWER_BUTTON);
    keyUp(KEY_TYPE.POWER_BUTTON);
end

keyUp(keyType)

Simulate the lifting of physical key.

Parameters

Parameter Type Specification
keyType Integer Physical key identification. Now you can use these physical keys.

Return None

Examples

-- Simulate the action of pressing and lifting Home Key.
keyDown(KEY_TYPE.HOME_BUTTON);
usleep(10000);
keyUp(KEY_TYPE.HOME_BUTTON);

getColor(x, y)

Get the color value of the pixel point at the specified coordinate.

Parameters

Parameter Type Specification
x Float x-coordinate on the screen
y Float y-coordinate on the screen

Return

Return Type Specification
color Integer Integer color value of the pixel point

Examples

local color = getColor(100, 200);
alert(string.format("Pixel color is :%d", color));
-- Pop up color: 16777215

getColors(locations)

Get the color values of the pixel points of the specified coordinates on current screen.

Parameters

Parameter Type Specification
locations table A group of coordinates specifying the points you want to return the color from i.e {{x1,y1},{x2,y2},{x3,y4}}

Return

Return Type Specification
colors table Colors found are returned in their corresponding order.

Examples

local result = getColors({{100, 200}, {200, 300}, {300, 400}});
for i, v in pairs(result) do
    log(string.format("Gotten color:%d", v));
end

findColor(color, count, region)

Search the coordinates of the pixel points matching the specified color on current screen.

Parameters

Parameter Type Specification
color Integer Matched color value.
count Integer The number refers to how many matched pixel points is required for a match. 0 is default setting, which requires all points match (slowest option). 1 refers to only the first matching pixel point is found. 2 refers to only the first two pixel points are found. The lower the number is (above zero), the faster the speed is.
region table You only search the result in the specified area. This area is the table type including four values {x, y, width, height}. The four values respectively represent the coordinate x, coordinate y, width, and height of the rectangular area. {100,100,200,200} is an example. If you do not want to specify the area, just input nil.

Return values

Return value Type Specification
locations table Coordinates of matched pixel points. For example: {{x1, y1}, {x2, y2}, ...}

Example

-- Example 1:
local result = findColor(0x0000ff, 2, nil);
for i, v in pairs(result) do
    log(string.format("Found pixel: x:%f, y:%f", v[1], v[2]));
end

-- Example 2:
local result = findColor(0x00ddff, 0, {100, 50, 200, 200});
for i, v in pairs(result) do
    log(string.format("Found pixel: x:%f, y:%f", v[1], v[2]));
end

-- Example 3:
local region = {100, 50, 200, 200};
local result = findColor(0x00ddff, 0, region);
for i, v in pairs(result) do
    log(string.format("Found pixel: x:%f, y:%f", v[1], v[2]));
end

Internal Implementation

function findColor(color, count, region)
    return findColors({{color,0,0}}, count, region);
end

findColors(colors, count, region)

Searches a region for specified colors and their position relative to the other colors matches. If a match is found it returns the coordinate of the matching first color.

This function has the search efficiency far beyond findImage. For example, you do not need to match the whole picture, only the anchor colors and their corresponding location.

You can specify the number of the results by count parameter. 0 refers to all, 1 refers to the first one, and 2 refers to the first tow. region parameter can specify the search area, which is the table type {x,y,width, height}. You only input nil if no data is specified. The more points you specify to match, the higher the accuracy.

This function can use the 'HELPER' tool in the 'Extension' menu. Select the anchors’ colors in a selected bmp and the tool will supply the corresponding location and color to the function’s parameter automatically.

In the below image, the table highlighted is the coordinate that will be returned upon a match.

Find Colors Example

Parameters

Parameter Type Specification
colors table Include color and their corresponding location, such as: {{0x00ddff,0,0}, {0x00eeff,10,10}, {0x0000ff,0,20}}. The inner tables includes 3 separate values: the 1st is the color value, the 2nd and 3rd are the x & y coordinates respectively. The corresponding location of the first color’s table is always (0,0) due to it being the origin point from which other coordinates are calculated. {0x00ddff,0,0} is an example. The anchor points are calculated relative to the first point.
count Integer The number refers to how many matched pixel points are required to be found before a match is declared. 0 is default setting, which requires all matching points to be found. 1 requires only 1 matching point to be found and so forth. The lower the count (above zero), the faster the script will resolve.
region table Specify the search region. This area is the table type that includes four values {x, y, width, height}. The four values represent the coordinate x, coordinate y, width, and height of the rectangular area. If you do not want to specify the area, just input nil.

Return values

Return value Type Specification
locations table The coordinate of the first color matched in the found rectangular area, including {{x1, y1}, {x2, y2}, ...}

Examples

-- Example 1:
local result = findColors({{0x00ddff,0,0}, {0x00eeff,10,10}, {0x0000ff,0,20}}, 2, nil);
for i, v in pairs(result) do
    log(string.format("Found rect at: x:%f, y:%f", v[1], v[2]));
end

-- Example 2:
local colors = {{0x00ddff,0,0}, {0x00eeff,10,10}, {0x0000ff,0,20}};
local result = findColors(colors, 0, nil);
for i, v in pairs(result) do
    log(string.format("Found rect at: x:%f, y:%f", v[1], v[2]));
end

-- Example 3:
local colors = {{0x00ddff,0,0}, {0x00eeff,10,10}, {0x0000ff,0,20}};
local region = {100, 50, 200, 200};
local result = findColors(colors, 0, region);
for i, v in pairs(result) do
    log(string.format("Found match at: x:%f, y:%f", v[1], v[2]));
    tap(v[1], v[2]);
end

findImage(imagePath, count, fuzzy, ignoreColors, region, debug) 

Searches the region specified for a match with the provided image and if a match is found returns the coordinate of the top left corner of the matched image

Find Image Example

Parameters

Parameter Type Specification Optional Default
targetImagePath String Relative path of the target image to match, for example: “Screenshots/gold.PNG”. Any valid format of images are supported. NO
count integer How many matches of the given image you would like to find on-screen. Pass nil if you just want to use the default value. YES 1
threshold float Searching precision, maximum value is 1 means every anchor point must match exactly, minimum value is 0.2 default is 0.9, usually 0.99 is good. Pass nil if you just want to use the default value. YES 0.9
region table You only search the result in the specified area. This area is the table type including four values {x, y, width, height}. The four values respectively represent the coordinate x, coordinate y, width, and height of the rectangular area. Pass nil if you just want to use the default value YES Whole screen
debug boolean If pass debug=true, it will produce a image ends with “-Debug.PNG” in same directory as the target image is, marked with matched areas. YES false

Return values

Return value Type Specification
locations table The array at the coordinate on the center of the matched area(s): {{x1, y1}, {x2, y2}, ...}

Examples

-- Example 1:
local result = findImage("Screenshots/Gold.PNG", 5, 0.99, nil, true)
for i, v in pairs(result) do
    log(string.format("Found rect at: x:%f, y:%f", v[1], v[2]));
end

-- Example 2:
local result = findImage("Screenshots/Gold.PNG", nil, nil, nil, true)
for i, v in pairs(result) do
    log(string.format("Found rect at: x:%f, y:%f", v[1], v[2]));
end

-- Example 3:
local result = findImage("Screenshots/Gold.PNG", 3)
for i, v in pairs(result) do
    log(string.format("Found rect at: x:%f, y:%f", v[1], v[2]));
end

-- Example 4:
local imagePath = "images/spirit.PNG";
local region = {100, 100, 300, 300};
local result = findImage(imagePath, 2, 0.98, region, true)
for i, v in pairs(result) do
    local x = v[1], y = v[2];

    log(string.format("Found rect at: x:%f, y:%f", x, y));
    
    -- Click the found location once.
    tap(x, y);
    usleep(16000);
end

findImage2(targetImagePath, targetsToFind)

Searches the entire screen for a match to the specified image, it is able to deal with most image size, orientation and color changes intelligently.

FindImage2 is a powerful successor to findImage allowing you to search for matches in very dynamic applications and games. However these features do come with a performance hit, in most cases it will be slower, so you should take care and only use when the powerful features are needed

Parameters

Parameter Type Specification
imagePath String The path of the picture, only the subfolders need to be specified if it sits somewhere within the AutoTouch directory. For example, images/script.bmp means /var/mobile/Library/AutoTouch/Scripts/images/spirit.bmp. You need not input the complete path.
Accepts only 32-bit .bmp & .png
targetsToFind (optional) Integer findImage2 handles matching differently. It will only determine a proper match, there is no 'fuzziness'. As such a new parameter called targetsToFind controls how many proper matches you want to return. For example: If there are 5 identical footballs on the screen, with the same image provided to the path and you have set targetsToFind= 5, then the function will return the coordinates of the 5 matches

Return values

Return value Type Specification
locations table The array will be at the center of the matching area: {{x1, y1}, {x2, y2}, ...}

screenshot(filePath, region) 

Take a screenshot for the whole screen or specified area and save as 32-bit BMP format at specified file path.

Parameters

Parameter Type Specification
filePath string The path of screenshot. From AutoTouch v3.1.1, you only input the location subordinated to AutoTouch file directory, namely, the path of “Local Script”. (you can get the path of the file directory by rootDir function). For example, “images/script.bmp” means “/var/mobile/Library/AutoTouch/Scripts/images/spirit.bmp”. You need not input the complete path.
region table Define the region to take the screenshot with. This area is a table type including four values {x, y, width, height}. {100,100,200,200} is an example. If you do not want to specify the area, just input nil.

Return values None

Examples

-- Take a screenshot of the whole screen and save in the specified location.
screenshot ("images/screenshot1.bmp", nil);

-- Take a screenshot of the specified area and save.        
screenshot ("images/screenshot2.bmp", {100, 100, 200, 200});

appRun(appIdentifier)

Run specified application.

Parameters

Parameter Type Specification
appIdentifier string Application identifier, including "com.apple.mobilesafari".

Return values None

Example

-- Run Safari
appRun("com.apple.mobilesafari");

appKill(appIdentifier)

Kills the specified application.

Parameters

Parameter Type Specification
appIdentifier string Application identifier, including "com.apple.mobilesafari".

Return values None

Example

-- Kill running Safari app
appKill("com.apple.mobilesafari");

appState(appIdentifier)

Get the running state of the specified application

Parameters

Parameter Type Specification
appIdentifier string Application identifier, including "com.apple.mobilesafari".

Return values

Return value Type Specification
state string State of Character string type: "NOT RUNNING", "ACTIVATED", "DEACTIVATED"。

Example

-- Get the state of Safari.
local state = appState("com.apple.mobilesafari");
alert(string.format("State of Safari: %s", state));
-- Pop up the state of Safari: "ACTIVATED"

rootDir()

Get the default directory address of the saved script. This is the default saving address of scripts and screenshots: "/var/mobile/Library/AutoTouch/Scripts/".

Parameters None

Return values

Return value Type Specification
dir string Default directory address of the saved script.

Examples

local dirPath = rootDir();
alert(dirPath);
-- Popup "/var/mobile/Library/AutoTouch/Scripts/"

usleep(microseconds) 

Sleep several microseconds (1/1000000)

Parameters

Parameter Type Specification
microseconds Integer The number of paused microseconds.

Return values None

Examples

-- Sleep 1 second.
usleep(1000000);

log(content)

Record log, can be seen in the log interface.

Parameters

Parameter Type Specification
content string The log content to be recorded.

Return values None

Examples

--Example 1:
log("play here...");

--Example 2: Formats dynamic data passed by functions into a string AutoTouch can log
log(string.format("Log test: x:%f, y:%f", v[1], v[2]));

alert(message)

Pop up the dialog box, that a user must manually dismiss by clicking "ok"

Parameters

Parameter Type Specification
message string Content to be showed.

Return values None

Examples

alert("Hello World!");

toast(message, delay) 

Show messages with the toast style. Suitable for when you need no interruptions and dont want to have to manually dismiss the message

Parameters

Parameter Type Specification
message string Content to be showed.
delay integer How long time to keep showing, default is 2 seconds.

Return values None

Examples

toast("Hello I'm a toast!", 5); -- Show message for 5 seconds.
toast("Hello again!"); -- Show message for 2 seconds.

vibrate() 

Vibrate once.

Parameters None

Return values None

Examples

-- Vibrate once.
vibrate();

playAudio(audioFile, times) 

Play audio document at specified location. Known to supports .mp3, .mp4 and .caf , probably supports more.

Parameters

Parameter Type Specification
audioFile string Absolute path of audio document.
times integer Number of repeated plays. 0 represents infinite repeat.

Return values None

Examples

-- Play audio infinitely.
playAudio("/var/audio.mp3", 0);

stopAudio() 

Stop playing audio.

Parameters None

Return values None

Examples

-- Stop playing audio.
stopAudio();

getOrientation() 

Gets orientation of the screen. Return the integer value. Please refer to the “Orientation Type of Screen” for specific correspondence relation.

Parameters None

Return values

Return value Type Specification
orientation Integer Screen orientation may be these values

Examples

local o = getOrientation();
alert(string.format("Screen orientation is : %d", 0))
-- Pop up the orientation 2 of the screen, and mark the reversed screen.

getScreenResolution()

Gets the current devices screen resolution.

Parameters None

Return values

Return value Type Specification
width Integer Width of screen resolution.
height Integer Height of screen resolution.

Examples

local w, h = getScreenResolution();
alert(string.format("Resolution of iPhone 6 Plus: width:%d, height:%d", w, h));
-- iPhone 6 Plus’s resolution width is 1242 and resolution height is 2208.

getSN()

 Get Serial Number of the device.

Parameters None

Return values

Return value Type Specification
SN string Serial Number of the device.

Examples

local sn = getSN();
alert(string.format("SN is : %s", sn));
-- Popup shows the SN of the device: C15NFK32TWD2

getVersion()

Get version of AutoTouch.

Parameters None

Return values

Return value Type Specification
version string Version of AutoTouch.

Examples

local version = getVersion();
alert(string.format("Current version of AutoTouch is : %s", version));
-- Pop up shows current version of AutoTouch: 3.5.3-4

intToRgb(intColor)

Transit integer color to independent values of R,G,B.

Parameters

Parameter Type Specification
intColor Integer Integer color value

Return values

Return value Type Specification
R Integer Red color value.
G Integer Green color value.
B Integer Blue color value.

Examples

local r, g, b = intToRgb(0x2b2b2b);
alert(string.format("R:%d, G:%d, B:%d", r, g, b));

rgbToInt(r, g, b)

Transit values of R,G,B to integer color value.

Parameters

Parameter Type Specification
R Integer Red color value.
G Integer Green color value.
B Integer Blue color value.

Return values

Return value Type Specification
intColor Integer Integer color value

Examples

local intColor = rgbToInt(200, 255, 100);
alert(string.format("Int type color: %d", intColor));

copyText(text)

Copy specified text to clipboard.

Parameters

Parameter Type Specification
text string Text to be copied.

Return values None

Examples

copyText("This is a copied text!");

clipText()

Get the text in the clipboard.

Parameters None

Return values

Return value Type Specification
text string Text copied in the clipboard.

Examples

local text = clipText();
alert(text);
-- Popup shows the text to be copied: "This is a copied text!";

inputText(text)

Pastes text to the input box selected now. You can delete a character backspace by inputText("\b").

Parameters

Parameter Type Specification
text string Text to be input.

Return values None

Examples

inputText("Let's input some text automatically without tapping the keyboard!");
--  Delete 3 character by inputing 3 backspaces.
inputText("\b\b\b");

dialog(controls, enableRemember)

Pop up self-defined dialog box to accept the user input. Please refer to the example for specific usage.

Parameters

Parameter Type Specification
controls table Array of self-defined controls. You can now use these dialog box controls
enableRemember boolean Whether to use the "remember user's input" function.

Return values None

Examples

--Dialog example

--Plain text label, used for the overall title of the dialog
local label = {type=CONTROLLER_TYPE.LABEL, text="AutoTouch Dialog Example"}

--Switch picker with the title as "Use skill combo?"
local developer2 = {type=CONTROLLER_TYPE.SWITCH, title="Use skill combo?", key="Skillcombo", value=0}

local unitPicker = {type=CONTROLLER_TYPE.PICKER, title="Unit", key="Unit", value="Unit1", options={"Unit1", "Unit3", "Unit3", "Unit4"}}

local collectLootSwitch = {type=CONTROLLER_TYPE.SWITCH, title="Collect loot", key="ADeveloper", value=1}


--Defines what to pass to the controls function, if not described here it will not appear
local controls = {label, developer2, unitPicker, collectLootSwitch}

local enableRemember = true;

-- Pop up the dialog box. After the popup, the script will suspend for user input until the user click “confirm” or “cancel”.
dialog(controls, enableRemember);

-- Then get the input value of user.
alert(string.format("Use skillcombo:%s, Unit choice:%s, Collect loot?:%d", developer2.value, unitPicker.value, collectLootSwitch.value))

3.png-115.9kB

clearDialogValues(script)

Clear the remembered values of the dialog created by the function dialog.

Parameters

Parameter Type Specification
script string script path. eg. there is a dialog.lua script in the scripts list, use it like this: clearDialogValues("dialog.lua");

Return values None

Examples

-- There is a dialog.lua script in the scripts list
clearDialogValues("dialog.lua");

openURL(urlString)

Open url, or open other apps’ url scheme. Look at this iOS App URL Scheme Names and example: Google Maps URL Scheme for iOS

Parameters

Parameter Type Specification
urlString string Target to open.

Return

None

Examples
openURL("https://autotouch.net")
openURL("prefs:root=General&path=About")
openURL("musics://")
openURL("itms-apps://itunes.apple.com")
openURL("tel://+1123456")
openURL("clashofclans://")

isLicensed()

Check if the current device is running licensed AutoTouch

Parameters

None

Return

Return Type Specification
license status boolean If current device is licensed it will return true else will return false 
Examples
if isLicensed() then
    alert("Your device is licensed by AutoTouch!");
end

HTTP APIs

Commands for controlling AutoTouch over Local Area Network (LAN), they use the same APIs as the Web Server that you can activate in AutoTouch Settings uses.

Play a script

GET /control/start_playing?path=/scriptPath

Parameters

Parameter Specification
path Script path.

Return

Successful:

{
    "status": "success"
}

Failed:

{
    "status": "fail",
    "info": ""
}

Examples:

HTTP GET http://192.168.1.99:8080/control/start_playing?path=/scriptPath

{
    "status": "fail",
    "info": "Script doesn't exist."
}

Stop playing a script

GET /control/stop_playing?path=/scriptPath

Parameters

Parameter Specification
path Script path.

Return

Successful:

{
    "status": "success"
}

Failed:

{
    "status": "fail",
    "info": ""
}

Example

HTTP GET http://192.168.1.99:8080/control/start_playing?path=/scriptPath

{
    "status": "fail",
    "info": "Script doesn't exist."
}

List files in Directory

GET /files?path=/Records

Parameters

Parameter Specification
path Directory path to list.

Return

{
    "files": [
        {
            "filePath": "",
            "fileSize": "",
            "iconName": ""
        },
        ...
    ]
}

Examples

HTTP GET http://192.168.1.99:8080/files?path=/Records
{    "files": [
        {
            "filePath": "/Records/2019-03-10: 12:00:00.lua",
            "fileSize": "12kb",
            "iconName": "script"
        },
        ...
    ]
}

Create a new directory

GET /file/newFolder?path=/Test

Parameters

Parameter Specification
path New Directory path to create.

Return

Successful:

{
    "status": "success"
}

Failed:

{
    "status": "fail",
    "info": ""
}
Examples
HTTP GET http://192.168.1.99:8080/file/newFolder?path=/Test
{
    "status": "success"
}

Create a new file

GET /file/new?path=/newFilePath

Parameters

Parameter Specification
path New file path to make.

Return

Successful:

{
    "status": "success"
}

Failed:

{
    "status": "fail",
    "info": ""
}

Examples:

HTTP GET http://192.168.1.99:8080/file/new?path=/newFilePath
{
    "status": "fail",
    "info": "Invalid file path"
}

Delete a file

GET /file/delete?path=/filePathToDelete

Parameters

Parameter Specification
path File path to delete.

Return

Successful:

{
    "status": "success"
}

Failed:

{
    "status": "fail",
    "info": ""
}

Examples:

HTTP GET http://192.168.1.99:8080/file/delete?path=/filePathToDelete
{
    "status": "fail",
    "info": "Invalid file path"
}

Rename a file or directory

GET /file/rename?path=/oldFilePath&newPath=newFilePath

Parameters

Parameter Specification
path Old path.
newPath New path.

Return

Successful:

{
    "status": "success"
}

Failed:

{
    "status": "fail",
    "info": ""
}

Examples:

HTTP GET http://192.168.1.99:8080/file/rename?path=/oldFilePath&newPath=newFilePath
{
    "status": "fail",
    "info": "Invalid file path"
}

Constants

Types of physical keys

Value Specification
KEY_TYPE.HOME_BUTTON Home Button
KEY_TYPE.VOLUME_DOWN_BUTTON Volume – Button
KEY_TYPE.VOLUME_UP_BUTTON Volume + Button
KEY_TYPE.POWER_BUTTON Power Button

Types of dialog controls

Value Specification
CONTROLLER_TYPE.LABEL Text label
CONTROLLER_TYPE.INPUT Input box
CONTROLLER_TYPE.PICKER Picker
CONTROLLER_TYPE.SWITCH Switch

Types of screen orientations

Value Specification
ORIENTATION_TYPE.UNKNOWN Unknown orientation. Practical value is 0.
ORIENTATION_TYPE.PORTRAIT Portrait screen. Home button is at the bottom. Practical value is 1.
ORIENTATION_TYPE.PORTRAIT_UPSIDE_DOWN Upside-down portrait screen. Home button on the top. Practical value is 2.
ORIENTATION_TYPE.LANDSCAPE_LEFT Landscape left screen. Home Key is in the left. Practical value is 3.
ORIENTATION_TYPE.LANDSCAPE_RIGHT Landscape right screen. Home key is in the right. Practical value is 4.