Settings

There are some very important settings. Some for the script to work properly. And Some are for development and debugging.

Settings for script function

Settings:setCompareDimension(boolean compareByWidth, int pixels):
This function is used to set the image matching (comparing) dimension.
            compareByWidth: If the application that we want to automate is scaled in width, set this to true. It's the normal case for most Apps.
            pixels: This value is the number of screen pixels when the image matching is performed. The value is width or height according to the value of compareByWidth.
            Return value: none

This is the secret that AnkuLua can work on different devices with the same script. Take the example of our first example. We capture the images from device with 960 on width. So we have the following code in our script.
Settings:setCompareDimension(true, 960)

If the device width to run the script is different, the captured screen will be first scaled to 960. Then the image matching is performed. Becuase all captured screen is scaled to our setting, the script works independent of running device.

There is one thing to note. The number of pixels is App usable screen size, not real screen size.
Device with navigation bar is one case that App usable screen size is different from real size.
In the following picture, App usable screen size is inside the yellow rectangle.




getAppUsableScreenSize()
getRealScreenSize()
Function getAppUsableScreenSize() is used to get the App usable screen size.
Function getRealScreenSize() is used to get the device screen real size.
local screen = getAppUsableScreenSize()
print(screen:getX()) -- the width of App usable screen
print(screen:getY()) -- the height of App usable screen
screen = getRealScreenSize()
print(screen:getX()) -- the width of device screen size
print(screen:getY()) -- the height of device screen size

setImmersiveMode(enable)
Some devices provide on-screen navigation bar.
Normally, the navigation bar could not be used by App.
In immersive mode, the navigation bar will disappear. And the original navigation bar area will be used by App.
If the App is in immersive mode, use this method. Otherwise, AnkuLua may not act as expected.
Reference: Google's explanation on Immersive

autoGameArea(enable)
Some devices have cutout (notch). Normally, games don't use the cutout areas. But those cutout areas exists in the AnkuLua screenshot. This will cause the scripts' wrong behavior.
Android P has formal API to support cutout. The cutout height could be got.
Therefore, if the user's device is with cutout, suggest to upgrade the device to Android P and above.
With autoGameArea(true) setting, AnkuLua can detect the area excluding cutout area.
Strongly suggest to set immersive first according to the game's behavior, then set autoGameArea(true).

getGameArea()
After setting setImmersiveMode() and autoGameArea(), we can use getGameArea() to get the AnkuLua used region.

Example:
The following is a figure of 2246x1080 device. The cutout height is 86.
The device is on landscape mode and the cutout is on left.
The table below is the different returned values of getGameArea() under different settings of setImmersiveMode() and autoGameArea().





setGameArea(Region region)
Set the game area manually.
Some games keep the same aspect ratio of gaming area under different devices, as for following figures.
For those games, we can use setGameArea() to include only the game area and excluding the black area on left and right.
We can then keep other parts of the script unchanged and make the script working on both devices.




Settings:setScriptDimension(boolean compareByWidth, int pixels):
This function is used to set device size that the script written on.
            compareByWidth: If the script application that we want to automate is scaled in width, set this to true. It's the normal case for most Apps.
            pixels: This value is the number of screen pixels when the script is written. The value is width or height according to the value of compareByWidth.
            Return value: none

This value is also referring to the App usable screen size.
When is this value used? One example is following code
click(Location(100,200))
Location(100,200) is an absolute value. And it need to be scaled on running device. This value, script dimension, and running device app usable screen size are used to decide the scaling value.

Is it possible that comparing dimension is different from script dimension? Yes.
Image matching speed is strongly related to the comparing dimension. Therefore, we can scale down the captured images and set the value accordingly. Then we can speed up the image matching process.


setImagePath(String path)
This function set the image path when AnkuLua try to load image files.
The default image path is the directory "image" under the starting script file. Use this function to set the path.


Settings:setROI(Region reg)
Set the interested(searching) region for the image searching not belong to any region.
If reg is nil, it's reset to whole screen.
existsClick("1.png") -- Search the full screen for 1.png

Settings:setROI(Region(100, 200, 300, 400))
existsClick("1.png") -- This is equal to Region(100,200,300,400):existsClick("1.png")

Settings:getROI()
Retun the region set by Settings:setROI().


Settings:set(String var, double value)
            var: one of AutoWaitTimeout or MinSimilarity

            value: when var is AutoWaitTimeout , this value is the default timeout seconds if the value is not provided in related functions, like wait().
                       when var is MinSimilarity
, this value is the default similarity value for S object or P object with assign similar value through similar().
            Return value: none
If those values are not set, the default AutoWaitTimeout  is 3 seconds. And the default MinSimilarity
is 0.7.


Settings:get(String var)
            var: one of AutoWaitTimeout or MinSimilarity

            Return value: the current AutoWaitTimeout or MinSimilarity value accordingly.
            
usePreviousSnap(boolean value)
            This function set to reuse previous captured screenshot (true) or not (false). The method's major usage is for speed. If you want to search some different images on the same screenshot, you can do 

wait("image1.png")
usePreviousSnap(true)
if (exists("image2.png") or exists("image3.png") then -- reuse previous screenshot
-- do some thing
end
usePreviousSnap(false) -- remember to set the value back to false


snapshot()
Thake a grey snapshot of current screen and set usePreviousSnap to true.
It could make the script more intuitive. For example, above usePreviousSnap script could be written as
snapshot()  -- A snapshot is taken. All the following image recognition will use this snapshot until usePreviousSnap(false)
wait("image1.png") -- no snapshot taken
if (exists("image2.png") or exists("image3.png") then -- no snapshot taken
-- do some thing
end
usePreviousSnap(false) -- remember to set the value back to false


snapshotColor()
Almost the same as snapshot(). The only difference is that the taken snapshot is color.
Only use the method if you want to getColor() at the same snapshot.


setAlternativeClick(boolean enable)
Some games are found with problem for the original click method.

Therefore, an alternative click method is introduced since version 3.2.0.

If  the original click method does not work for your games (Apps), use following function to enable the new method.

setAlternativeClick(true)


ImageCache
ImageCache class contains following functions to cache images and improve the script speed.
    ImageCache:setCheckEnable(boolean true):
        enable or disable image cache. Default is disabled.
    ImageCache:setUpdateEnable(boolean true):
        enable or disable updating image cache. You can disable the cache if the following searching images are not used often.
    ImageCache:setImageSizeLimit(int size):
        set the maximum image size in pixels to cache.
    ImageCache:setCacheNumber(int number):
        set the maximum number of images to cache.
        The cache is first in first out. Oldest images are pushed out if the number of images to be cached bigger than the number.


Settings for script development
Settings:snapSet(String var, boolean value)

This method is used to decide screen snap shot behavior and storing the captured images or not.
The captured images are saved in /sdcard/AnkuLua/captured_images
            var: one of OutputCaptureImg, OutputCropImg, OutputResizeImg or OutputRegImg

            value:   when var is OutputCaptureImg and set true, the captured image will be saved as "capture.png"
                        when var is OutputCropImg and set true, the captured image after cropping will be saved in folder "captured_images" as "crop.png". AnkuLua crops the captured image according to Immersive true (whole screen) or false (App usable screen)
                        when var is OutputResizeImg and set true, the cropped image after resizing will be stored in folder "captured_images" as "resize.png". AnkuLua resizes the image according user setting on setCompareDimension
                        when var is OutputRegImg and set true, if Region is used, the region image for matching will be saved  as "region.png".

            Return value: none

[Next]: Step-by-step guide for script development, using Mobizen
[Previous]: IntelliJ IDEA: The recommended editor
[Home]: AnkuLua Introduction