Advanced Methods

AnkuLua provide some special methods for special situation and usage.

zoom(pt1StartX, pt1StartY, pt1EndX, pt1EndY, pt2StartX, pt2StartY, pt2EndX, pt2EndY, step)
It means one finger moving from (pt1StartX, pt1StartY) to (pt1EndX, pt1EndY) while the other from (pt2StartX, pt2StartY) to (pt2EndX, pt2EndY) in specified steps.
For example, the following code will zoom out the screen

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

zoom(50, 350, 330, 350, 1200, 350, 350, 350, 300)


continueClick(x, y, xRandom, yRandom, times)
This function will tap on the range from (x, y) to (x + xRandom, y + yRandom) for the specified times.
Normally, click method is not fast.
If you really want to click on some region REALLY FAST and repeatedly, use continueClick method.

local p = find("target.png")

continueClick(p:getX(), p:getY(), 1, 1, 100)
For example, refer to Tap Titans Click

continueClick(PSMRL, times [,timeout])
Method continueClick also support PSRML objects and timeout parameters. There is no return value.
continueClick could be called direct or from Region object.
timeout is in seconds with precision up to milliseconds. 1.003 means 1 second and 3 milliseconds.

The timing of continueClick could be set by
setContinueClickTiming(downMs, intervalMs)

int downMs: click down milliseconds
int intervalMs: interval milliseconds between clicks

continueMultiTouch(table of PSMRL, times [,timeout])

This method is used to simulate multi touch. It will click the objects of the PSMRL table. Each object will be click times times.
If the table objects are PS (Pattern or String), then each of them will be searched for timeout seconds.
If timeout value not given, the default searching time is taken.
continueMultiTouch could not be called by Region.
The timing of continueMultiTouch is also set by setContinueClickTiming.

-- example for calculator plus
png7 = find("7.png")
loc1 = find("1.png"):getTarget()
list = {Pattern("6.png"), png7, "8.png", loc1}
continueMultiTouch(list, 2)
-- the result is 67816781
longClick(PSMRL [,seconds])
stopLongClick()
Method longClick will press the target as long as user want. If duration seconds provide, the target will be pressed for specified time.
If no seconds parameter, the longClick will last until next touch command or stopLongClick().

longClick("target.png", 2) -- target will be clicked for 2 seconds
longClick("target.png") -- target will be clicked and the click last

-- do anything except touch related methods
--
stopLongClick() -- now the click on target is released

longClick("target.png") -- target will be clicked and the click last
click("target2.png") -- click on target is reatarget2 is clicked

numberOCR( region,  imagePrefix)
numberOCR method will do basic number OCR on region reg.
The fonts of those number are imagePregix0.png, imagePrefix1.png ... imagePrefix9.png
If there is no number in the region, an exception will be thrown.
Refer to Heroes Charge: Booty Cave.
You can see the usage in line 15 
local p = numberOCR(r,"power")And the font images are power0.png, power1.png ... power9.png in sub-folder image.

numberOCRNoFindException(region, imagePrefix)
Exception not throwing exception, this method does the same thing as numberOCR.
This method returns two values. The first one is still the recognized number. The second one is the boolean value of success (true).

charOCR( region,  charTable)
charOCR method will do basic character OCR on region reg.
The script should provide a table with images and the corresponding characters.
If there is no character in the region, an exception will be thrown.
Please refer to the following example.
local charTable = { {target = "a.png", char = "a"},
                   {target = "A.png", char = "A"},
                   {target = "b.png", char = "b"},
                   {target = "B.png", char = "B"},
} -- add as many as you want
string = charOCR(reg, charTable)
charOCRNoFindException(region, imagePrefix)
Exception not throwing exception, this method does the same thing as charOCR.
This method returns two values. The first one is still the recognized string.
If no string found, the first return value will be empty string.
The second one is the boolean value of success (true).


getColor(PSMRL [, seconds])
This function will return 3 value (R, G, B) of the target location.
For better efficiency, AnkuLua transforms the images to grayscale before doing recognition. 
Therefore, it's hard for AnkuLua to recognize the image is color or not.
And in some games, the button is just in grey to mean other condition.
In this case, users can use this function to check the image is color or not.

r, g, b = getColor("target.png")
if (r == b and r == g) then -- it's grayscale

getTouchEvent()
Wait users to touch the scree. Then return the result. getTouchEvent() return following three values.
action(string): The action judged by AnkuLua. It could be one of  "click", "longClick", "swipe" and "dragDrop".
location(Location (Table)): If the action is "click" or "longClick", return the touched location. If "swipe" or "dragDrop", returns the table of starting and end locations.
touchList (Table): The table of detailed touch data. Inside the table, each element is with data {touchType, time, locaiton}
    touchType: Integer 1, 2 or 3 represents down, up and move respectively.
    time: the time the detailed touch happening. It's counted from the down event.
    location: the location
Because AnkuLua only do some simple judgement, the script could use touchList to make more complicated response.
Note: When getTouchEvent() running, the screen touch is intercepted. The running game or app under will not receive the touch. Therefore, the script should handle the case.

To inform users that the screen is touchable, getTouchEvent() will cover the screen with a translucent color. The color can be set with  setTouchEventStyle(color). Here the color format is ARGB.

   action, locTable, touchTable = getTouchEvent()
   print (action)

   if (action == "click" or action == "longClick") then
       print (locTable)
   else
       print (locTable[1])
       print (locTable[2])
   end

   for i, t in ipairs(touchTable) do
       print (string.format("%s: %fs, %s", t[1], t[2], t[3]:toString()))
   end



playMusic(file, loop)
Play the file for single (loop = false) or in loop (loop = true). This method is in pro version only.
Put the music file under "music" folder. Don't need the path in "file".
playMusic("music.mp3", false)

stopMusic()
Stop the music played. This method is in pro version only.

vibrate(seconds)
Vibrate the device for the specified amount of time. This method is in pro version only.

setVolumeDetect(boolean)
Enable or disable the volume detection according to the boolean value. Methods isVolumeUp() and isVolumeDown() only reflect the volume changing when detection enable. If disabled, isVolumeUp() and isVolumeDown() always return false.

isVolumeUp() and isVolumeDown()
Check if the volume changed (including music and ring volume). This method is in pro version only.
Note: For some devices, the first press of volume keys just show the current volume and no volume is changed. Therefore, you need to press it again to take effect.

setVolumeDetect(true)
while (true) do
   if (isVolumeUp()) then toast("Volume up") end
   if (isVolumeDown()) then toast("Volume down") end
end


Timer
With object timer, users can know the time consumed in some period.
Following methods are provided,
set()
Reset the timer.
Return value: the time (in seconds) from timer constructed or previous set.

check()
Return value: the time (in seconds) from timer constructed or previous set.

t = Timer()
wait(1)
print(t:check())
wait(1.2)
print(t:check())
wait(1.3)
print(t:set())
wait(1.5)
print(t:check())


To run something after running script 30 minutes,
timer = Timer() -- at the beginning of the script

-- in the script kernel routine
if (timer:check() > 30*60) then
 scriptExit(the script run more than 30 minutes) -- or change to anything you want
end


setScanInterval(seconds), setScanRate(frequency), getScanInterval(), getScanRate()
Set the scan interval or rate. Interval is the inverse of frequency.
For scanning every 4 seconds, you can use either one of following
setScanInterval(4)
setScanRate(1/4)getScanInterval() and getScanRate() return the corresponding values.
Note: These scan related functions are time-limited features in trial version.

setBrightness(value), getBrightness()

set and get the screen brightness. value should be integer between 0 and 255.
Note: The setBrightness function is time-limited features in trial version.

getNetworkTime()
Return the value (long int) from network time server.
Refer to following site for the meaning of network time.
www.lua.org/pil/22.1.html
Note that in lua the network time is in the unit of second, but the getNetworkTime() is in the unit of millisecond.

You can use following script to transfer the network time to local time
local temp = os.date("*t", getNetworkTime() / 1000)
print (temp.year)
print (temp.month)
print (temp.day)
print (temp.hour)


scriptExit(String message)
Exit the script immediately with message shown in result dialog.

setStopMessage(String message)
Show the message when script stopped, no matter by normal exiting, manual stopped, scriptExit() or exception.
The newer value will overwrite previous one.
It could be used for showing the script final result.
For example, following script will only show "Win 2, lose 0".

setStopMessage("Win 1, lose 0")
......
setStopMessage("Win 2, lose 0")
scriptExit("Exit")


chargerConnected()
Return the status of charger connected (true) or not (false)

batteryLevel()
Return the level of battery in percent (1~100).

isEmulator()
Return the status of if the device is platform (true) or not (false)

typeOf(variable)
Because the lua type() method is override with the string input method.
If still needing a method to check variable type, please use typeOf()
Or change type() to lua original usage with following codes. The string input method will be changed to keyin()
keyin = type
type = typeOf

startApp(String packageName)
killApp(String packageName)
Start or kill App with package name packageName.
Package name is the string after id in google play app's link.
For example, the url link of AnkuLua trial is
play.google.com/store/apps/details?id=com.appautomatic.ankulua.trial
And the package name is com.appautomatic.ankulua.trial

killApp() works on daemon and root, but not accessory.
You can use keyevent(187) (app switch) and swipe() to kill app on accessory.

Note: The startApp function is time-limited features in trial version.


unzip(String fileName[, String directory [, String encoding])
unzip the file fileName to directory. If encoding provided, the file name will be in the encoding format.
directory: the unzip directory. If directory not provided, it will be unzipped to the directory of the executing script.
We suggest use only English file names in the zip file. Or you can use encoding to assign the encoding of the file names.

isRecoveredFromKilled()
Check if AnkuLua was killed by Android and rerun the script automatically. If yes, return true, otherwise false.
If this happens, dialogShow() and dialogShowFullScreen() will not show the dialog.
The previous values are used.

setRecoveredFromKilled(Boolean enable)
Force the script as the state of AnkuLua killed by Android and rerun the script automatically.
It could be used to test the script under such condition. It's because hard to reproduce the condition.

halfCompareDimension()()
Check if the script runs under half comparing dimension. If yes, return true.
The half comparing dimension is set in AnkuLua settings.

---

Network related methods

setHttpTimeout(Int seconds)
Set the http timeout in seconds. Set this value bigger if the server response is slow.

Note: For following network methods to work, users need to enable network methods in settings.

httpGet(String url)
httpGet() will return the string from the url.

result = httpGet("http://google.com") -- always add the http in urlNote: always add the http or https in url

httpPost(String url, Table param)
httpPost() will communication with website in Post
The key-value parameters should be created in table.
For the difference between Get and Post, please google.

params = {param1="Parameter1", param2="This is parameter 2" }
result = httpPost("http://httpbin.org/post", params)
print (result)


httpDownload(String url, String fileName)
httpDownload() will download the file in url and save to assigned fileName.

httpDownload("https://www.google.com.tw/images/branding/googlelogo/2x/googlelogo_color_120x44dp.png", "/sdcard/google.png")


openUrl(String url)
openUrl() will open the url with browser (default Chrome).
Note: openUrl() will ask the user whether to visit the url or not. Then the script will stop.

sendEmail(String subject, String message)
sendEmail() will send email to the recipient in settings
Please set the corresponding settings in AnkuLua settings before using this function.


sendEmail("Subject", "Message")

Note: 
* Please google the parameters for your email server.

Gmail users:
* If you turn on 2-step verification, please apply the app password first.
support.google.com/mail/answer/185833
* If you didn't enable 2-step verification, you need to enable less secure app access.

myaccount.google.com/lesssecureapps



setExceptionEmail(String subject, String message)
setExceptionEmail() will send email if exception occurs and the script stops.
The email message will also include the dialog message.
As sendEmail(), please set the corresponding settings in AnkuLua settings.

setExceptionEmail("Subject", "Message")




setRewardAccount(String rewardAccount)
The setRewardAccount() function is used to set up a reward system where 1/10th of the execution time is given as a license reward to the specified account when running scripts with AnkuLua Pro2.

The following conditions must be met for the reward to occur:

1. The app running the script must not be a trial version of AnkuLua.
2. The reward account must be different from the account running the script.
3. The reward account must have available licenses. If the reward account has multiple unexpired licenses, AnkuLua's server will automatically extend the license that is closest to expiring.

setRewardAccount("abc@gmail.com") -- change abc@gmail.com to your account




[Next]: Compile and Encrypt Scripts
[Previous]: User Interface Methods
[Home]: AnkuLua Introduction