触动精灵脚本开发手册

脚本开发相关工具

       工欲善其事，必先利其器，在学习触动精灵脚本编写前我们需要下载安装一些辅助工具来完成脚本编写，包含但不限于以下工具：

触动精灵 iOS

使用教程：https://www.zybuluo.com/miniknife/note/307627
官方源地址：http://apt.touchsprite.com
测试源地址：http://apt-test.touchsprite.com
脚本存放路径：/var/mobile/Media/TouchSprite/lua
默认资源路径：/var/mobile/Media/TouchSprite/res
脚本日志路径：/var/mobile/Media/TouchSprite/log
配置文件路径：/var/mobile/Media/TouchSprite/config

注意事项

• 有些函数不支持低版本触动精灵，请仔细阅读函数说明并尽量保持触动精灵客户端为最新版。
• 测试版为不稳定版本，为避免不必要的麻烦，请勿大规模安装。
• 测试版和正式版的 Bundle ID 不同，不能跨源覆盖安装或直接升级，请卸载之后再安装另一个源的版本。

脚本编辑器：TouchSprite Studio

支持函数自动补全、函数提示、关键字高亮、文件传送、远程运行、自动缩进等常用功能，已内置所有至最新 2.3.6 版本触动精灵扩展函数，推荐使用。
下载地址：http://www.touchsprite.com/tools
使用手册：https://www.zybuluo.com/miniknife/note/123055
视频教程：https://www.zybuluo.com/lisaisacat/note/324664#编辑器与抓色器的使用

抓色器：TSColorPicker

一个趁手的抓色器可以让你的脚本开发过程变的轻松愉快，在此强烈推荐由苏泽制作的触动抓色器，快捷抓点、一键生成代码、远程抓屏，让你如虎添翼。具体使用方法请阅读压缩包内附带的说明（远程抓屏功能需使用触动精灵iOS v2.1.5 以上版本）。
下载地址：http://www.touchsprite.com/tools
使用手册：https://www.zybuluo.com/havonz/note/94681
视频教程：https://www.zybuluo.com/lisaisacat/note/324664#编辑器与抓色器的使用

已兼容的模拟器

猩猩模拟器、海马玩模拟器、夜神模拟器、逍遥模拟器、51 模拟器、雷电模拟器
模拟器使用教程：https://www.zybuluo.com/miniknife/note/443336
从系统兼容和资源占用角度考虑，推荐使用猩猩模拟器。

点击触摸

函数：touchDown、touchUp、touchMove 触摸点击、滑动

函数名称：触摸按下、抬起、移动

函数功能：通过按下、抬起、移动动作发送触摸事件。

函数方法

touchDown(整数型 index, 整数型 x, 整数型 y);
touchMove(整数型 index, 整数型 x, 整数型 y);
touchUp(整数型 index, 整数型 x, 整数型 y);
返回值：无

脚本实例：
快速划动

touchDown(150, 550);    --在坐标 (150, 550)按下
mSleep(30);
touchMove(150, 600);    --移动到坐标 (150, 600)，注意一次滑动的坐标间隔不要太大，不宜超过50像素
mSleep(30);
touchUp(150, 600);  --在坐标 (150, 600) 抬起

连续划动

touchDown(150, 550);    --在坐标 (150, 550) 按下
for i = 0, 400, 10 do   --使用for循环从起始点连续横向移动到终止点
    touchMove(150 + i, 550); 
    mSleep(10);     --延迟
end
touchUp(150 + 200, 550);    --在坐标 (350, 550) 抬起

多点触控

touchDown(1, 200, 400);             --手指 1 在坐标 (200, 400) 按下
touchDown(2, 300, 500);             --手指 2 在坐标 (300, 500) 按下
mSleep(50);
for i = 1, 100, 1 do                --使用 for 循环使两只手指同时分离
    touchMove(1, 200 - i, 400 - i); 
    touchMove(2, 300 + i, 500 + i);
    mSleep(10);
end
touchUp(1, 200 - 100, 400 - 100);   --抬起手指1
touchUp(2, 300 + 100, 500 + 100);   --抬起手指2

封装一个点击函数

function click(x, y)
    touchDown(x, y)
    mSleep(30)
    touchUp(x, y)
end
click(100, 200) --点击坐标 100，200 位置

方形渐开线

init(1)
mSleep(1000)
local x = 1010 --起始坐标x
local y = 698  --起始坐标y
local v = 30   --两点间距离
touchDown(x, y)
mSleep(100)
for var = 1,20 do
    j = 0
    k = v
    for _i = 1,2 do
        for i = 1,10 do
            x = x + j
            y = y + k
            touchMove(x, y)
            mSleep(20)
        end
        j = v
        k = 0
    end
    v = v * (-1.05)
end
touchUp(x, y)

圆形渐开线

init(1)
mSleep(1000)
local x0 = 1010 --起始坐标x
local y0 = 698  --起始坐标y
local rr = 20 --设置递增半径 
local l = 10 --设置点间距 
local p = 0 --初始化角度  
local r = 30 --设置首圈半径
local rn = 10 --设置圈数
touchDown(x0, y0)
mSleep(100)
for var = 1,rn do
    while p < math.pi * 2 do
        x = x0 + r * math.cos(p) 
        y = y0 - r * math.sin(p) 
        touchMove(x, y)
        mSleep(10)
        p = p + l/r
    end
    p = 0
    r = r + rr 
end
touchUp(x0, y0)

注意事项：

1. 需要注意的是在使用 touchDown、touchMove、touchUp 函数时，中间一定要插入一定的延时，建议大于 20 毫秒，否则可能会出现点击无效等异常情况。
2. 使用滑动函数时，新手常犯的错误就是两点之间滑动距离过大，请注意touchDown、touchMove 的坐标间隔不宜超过 50 像素。
3. 非多点触控可省略手指 id
4. 新手使用点击、随机点击、直线或角度滑动等相关函数请参考函数扩展库
5. 在部分安卓应用程序中的HTML5页面中，出现脚本能够点击，但点击没有后续反应的问题。此问题目前可以通过以下写法来解决：
   os.execute("input mouse tap x y")，其中 x y 为坐标值

名词解析：

1. 手指序号，用于多点触控的支持。标记多只手指，来分别控制它们的移动。
2. 屏幕坐标，横坐标为 x，纵坐标为 y，单位为像素。例如，iPhone 4 与 iPhone 4S 的屏幕分辨率 为 640 * 960，则其最大横坐标为 640，最大纵坐标为 960。
3. for 循环是 Lua 基本语法，属于循环控制。

函数：catchTouchPoint 获取用户点击坐标

函数名称：获取用户点击坐标

函数功能：调用该函数后，触动精灵将等待用户完成一次或多次屏幕点击，并返回点击的坐标。

函数方法

x,y = catchTouchPoint();
返回值：整数型 x，y
ret = catchTouchPoint(touchCount);
返回值：table类型 ret

脚本实例：

dialog("一秒后接收用户一次点击", 0);
mSleep(1000);
x,y = catchTouchPoint(); 
dialog("x:"..x.." y:"..y, 0);

--获取多个点击坐标
ialog("一秒后接收用户三次点击", 0);
mSleep(1000);
local ret = catchTouchPoint(3);
for i = 1, #ret do  
    dialog("第"..i.."次点击的位置:"..i..",x="..ret[i].x..",y="..ret[i].y);
end

注意事项：

1. 部分安卓模拟器不支持该函数。
2. 此函数将阻止脚本继续运行, 一直等待用户完成屏幕点击。
3. 此函数获取到的坐标为竖屏坐标，横屏情况请自行转换。
4. 本函数有较小的延迟，连续点击时，请勿点击过快。
5. 在 iOS 引擎版本 v2.2.4 以上中可接收多个点击坐标并以 table 形式返回。

图色类及屏幕相关

函数：init 初始化

函数名称：初始化

函数功能：脚本运行前必须调用，以设置设备方向及坐标系。

函数方法

init(整数型 rotate);
返回值：无
|参数|类型|说明|
|:----:|:----:|:----：|
|bid|文本型|选填，目标程序的Bundle ID，当填写“0”时，自动使用当前运行的应用|
|Rotate|整数型|必填，屏幕方向，0 - iOS：竖屏；安卓：初始方向， 1 - iOS：Home键在右边；安卓：初始方向向左旋转90°， 2 - iOS：Home键在左边；安卓：初始方向向右旋转90°|

脚本实例：

init(0)                 -- iOS 设备以 Home 键在下方时的屏幕左上角为坐标系原点(0,0)，iOS 7 以上系统有效；安卓设备以当前屏幕默认截图方向进行初始化

init(1);                    --iOS 设备以当前应用 Home 键在右边初始化，即以 Home 键在右侧时的横屏左上角为屏幕坐标原点(0,0)；安卓设备以屏幕默认截图方向向左旋转90°进行初始化

注意事项：

1. 安卓系统不同设备初始的截图方向有所不同，编写脚本前请用截图函数确认设备的默认方向。
2. iOS6 系统如果填写 bid 参数的话，请在使用 runApp 函数之后再使用此函数，才能获取到正确的当前应用坐标系。
3. 此函数可在脚本运行过程中多次调用已改变屏幕方向。
4. 如在脚本中未指定屏幕方向，系统将默认为竖屏或初始方向。

参考资料：

Bundle ID 的获取方法
1. 在触动精灵客户端的 更多 -> 应用ID查询 中能查看到应用程序的 Bundle ID；
2. iOS 使用 iFile、PP助手等软件可查看应用文件夹下的 Info.plist，其中的 CFBundleIdentifier 即为该应用的 Bundle ID。
3. 使用 frontAppBid 函数，前台运行要获取 Bundle ID 的应用，运行此函数并用 diolag、toast、nLog 函数显示返回值。

函数：getDeviceOrient 获取手机、应用屏幕方向（仅支持 iOS）

函数名称：获取手机、应用屏幕方向

函数功能：用于获取当前手机方向和应用方向

支持版本：引擎版本 iOS v2.3.9 以上,Android 暂不支持

函数方法：

orient = getDeviceOrient()
返回值：整数型 orient.app,orient.dev

脚本实例：

local orient = getDeviceOrient()
dialog("屏幕方向：" .. orient.dev .. "\n应用方向：" .. orient.app, 0)

注意事项：

屏幕方向,0-3,和 init 方向一致
该函数获取时间长，不建议频繁调用，否则可能会影响脚本效率

函数：setDeviceOrient 设置屏幕方向（仅支持 iOS）

函数名称：设置屏幕方向

函数功能：设置当前脚本运行时的屏幕方向。

支持版本：引擎版本 iOS v2.3.4 以上,Android 暂不支持

函数方法

setDeviceOrient(整数型 rotate);
返回值：无

函数：getScreenSize 获取屏幕分辨率

函数名称：获取屏幕分辨率，取分辨率

函数功能：用于获取设备屏幕的分辨率，用来判断坐标系的使用。

函数方法

width,height = getScreenSize();
返回值：整数型 width,height

脚本实例：
根据分辨率判断脚本是否适配

width, height = getScreenSize();
if width == 640 and height == 1136 then         --iPhone SE, 5, 5S, iPod touch 5
dialog("iPhone SE, 5, 5S, iPod touch 5")
elseif width == 640 and height == 960 then      --iPhone 4,4S, iPod touch 4
dialog("iPhone 4,4S, iPod touch 4")
elseif width == 320 and height == 480 then      --iPhone 非高分屏
dialog("iPhone 非高分屏")
elseif width == 768 and height == 1024 then     --iPad 1,2, mini 1
dialog("iPad 1,2, mini 1")
elseif width == 1536 and height == 2048 then    --iPad 3,4,5, mini 2
dialog("iPad 3,4,5, mini 2")
elseif width == 1080 and height == 1920 then
dialog("小米 4,华为荣耀 6p 等")
elseif width == 720 and height == 1280 then
dialog("红米 note2 等")
elseif width == 768 and height == 1280 then
dialog("魅蓝等")
elseif width == 800 and height == 1280 then
dialog("三星 N5100 等")
elseif width == 480 and height == 800 then
dialog("酷派 8017-T00 等")
end

注意事项：

1. 统一为 iOS 竖屏（Home 键在下方时）、安卓初始方向屏幕的宽度和高度。
2. 部分安卓设备存在无法获取到屏幕分辨率的问题，需要在脚本中判断如果返回值小于0则指定一个固定的宽高。

函数：setScreenScale 坐标缩放

函数名称：坐标缩放

函数功能：用于对屏幕坐标进行缩放，可直接影响点击、取色、找色函数中的坐标参数。

支持版本：引擎版本 iOS v2.2.7,Android v1.2.8 以上

函数方法

setScreenScale(逻辑型 flag, 数值型 width, 数值型 height);
返回值：无

脚本实例：

setScreenScale(true, 750, 1334)  --以750,1334分辨率为基准坐标进行缩放
--[[
    当此函数打开时，将影响点击、取色、单点模糊找色函数
    ]]
setScreenScale(false) --关闭缩放

注意事项：

1. 当此函数打开时，受影响的函数为点击和单点找色函数：touchDown touchUp touchMove getColor getColorRGB findColorInRegionFuzzy snapwot
2. 多点找色函数不受此函数影响
3. 当两个设备宽高比相差较大时，此函数转换后的效果较差

函数：keepScreen 保持屏幕

函数名称：保持屏幕，保持图像

函数功能：在脚本中保持当前屏幕内容不变，多次调用取色、找色、截图、找图等函数时，直接调用保持的内容。该函数为优化类函数，能够为大量的静态图像处理函数提供性能优化。

函数方法

keepScreen(逻辑型 flag);
返回值：无

脚本实例：
遍历屏幕区块

keepScreen(true);   --打开保持屏幕,当参数为 true 时启用屏幕保持，运行到该函数时内存中的屏幕图像保持在这一时刻
for k = 1, 640, 10 do
    for j = 1, 960, 10 do
        --格式化为十六进制文本
        color = string.format("%X", getColor(k, j));
        --输出到本地日志
        nLog("("..k..", "..j..") Color: "..color..".");
    end
end
keepScreen(false);   --关闭保持屏幕，当参数为 false 时关闭屏幕保持，释放内存中的屏幕图像，以备下一次继续保持。 

注意事项：

1. 据不完全统计，与不使用该函数相比，使用此函数会使普通屏上脚本取色速率提升 100 倍，高分屏上脚本取色速率提升 50 倍。在执行大量静态图像操作时，请务必使用该函数优化脚本性能。
2. 该函数一般用于画面变动节奏较慢，但需要根据大量取色、找色来完成计算和操作的脚本中，例如"天天爱消除"、"天天星连萌"这样的游戏。

名词解析：

1. 静态图像处理，指可在某一状态下屏幕内容保持到内存（不影响显示），对其进行进一步的 多次分析。否则，每次使用图像类函数，都将截取一次屏幕内容。
2. 保持开关，逻辑型只有两种属性：true 为真，false 为假。

注意事项：

1. 当使用 keepScreen(true); 时启用屏幕保持，运行到该函数时内存中的屏幕图像保持在这一时刻。
2. 当使用 keepScreen(false); 时关闭屏幕保持，释放内存中的屏幕图像，以备下一次继续保持。

函数：getColor、getColorRGB 获取屏幕某点颜色值

函数名称：获取颜色、获取颜色RGB 、取色

函数功能：获取某一点的颜色值（RGB）、颜色 R,G,B 值。

函数方法

color = getColor(整数型x, 整数型y);
返回值 1 整型 color
color_r, color_g, color_b = getColorRGB(整数型 x, 整数型 y);
返回值 2 整型 color_r, color_g, color_b

脚本实例：
如果某点符合某颜色则点击

color = getColor(100, 100);    --获取(100,100)的颜色值，赋值给color变量
if color == 0xffffff then      --如果该点的颜色值等于0xffffff
    touchDown(100, 100);    --那么点击该点
    mSleep(30);
    touchUp(100, 100);
end

--亦可写作

if getColor(100, 100) == 0xffffff then 
   touchDown(100, 100);
   mSleep(30);
   touchUp(100, 100);
end

如果某点的颜色与某颜色相似则点击

r,g,b = getColorRGB(100,100);    --获取(100, 100)的颜色值，赋值给color变量
if r > 200 and g < 150 then      --如果红色强度大于  200，绿色强度小于 150
    touchDown(100,100);      --那么点击该点
    mSleep(30);
    touchUp(100,100);
end

封装一个单点模糊比色函数

function isColor(x,y,c,s)   --封装函数，函数名 isColor
    local fl,abs = math.floor,math.abs
    s = fl(0xff*(100-s)*0.01)
    local r,g,b = fl(c/0x10000),fl(c%0x10000/0x100),fl(c%0x100)
    local rr,gg,bb = getColorRGB(x,y)
    if abs(r-rr)<s and abs(g-gg)<s and abs(b-bb)<s then
        return true
    end
end
--下面为函数用法
if isColor(963,  961, 0x7b593f,90) then --90 为模糊值，值越大要求的精确度越高
    touchDown(963, 961)
    mSleep(50)
    touchUp(963, 961)
end

多点模糊比色
在实际游戏脚本制作中，很多界面单靠 1 个点不容易进行准确的判断，这里封装一个配合TABLE使用的多点模糊比色函数来实现精确判断：

function multiColor(array,s)
    s = math.floor(0xff*(100-s)*0.01)
    keepScreen(true)
    for var = 1, #array do
        local lr,lg,lb = getColorRGB(array[var][1],array[var][2])
        local r = math.floor(array[var][3]/0x10000)
        local g = math.floor(array[var][3]%0x10000/0x100)
        local b = math.floor(array[var][3]%0x100)
        if math.abs(lr-r) > s or math.abs(lg-g) > s or math.abs(lb-b) > s then
            keepScreen(false)
            return false
        end
    end
    keepScreen(false)
    return true
end
--用法
g_t_Table = {
    { 1962,   52, 0xefdccf},
    { 2150,   50, 0xefd8d0},
    { 1964,   76, 0xe9d1c5},
    { 2152,   74, 0xefdcd1},
    { 2122,   62, 0xf1ddd1},
    { 2146, 1080, 0x893824},
    { 1840, 1082, 0x593724},
}
if multiColor(g_t_Table,90) then
    touchDown(100,100)
    mSleep(50)
    touchUp(100,100)
end

名词解析：

1. 参数 s 为模糊度，范围 0 - 100，一般使用90即可。
2. 实例中的 TABLE 格式可使用触动精灵抓色器生成。

注意事项：

1. getColor 与 getColorRGB 的作用是一样的，只不过前者返回单变量，后者返回 R, G, B 三变量。
2. 如直接使用例子中的代码进行测试，请在全部代码之前，加入 2 ~ 3 秒延迟；或者使用循环语句。 因为脚本开始运行时，会出现音量提示遮盖在前台，影响获取颜色。
3. 特别注意，getColor函数获得的颜色值十六进制文本中，实际顺序为 RGB。
4. 新手找色可使用触动精灵函数扩展库中的比色和多点找色函数，更加简单方便。

参考资料 如何获取屏幕上某点的颜色

1. 在你想在设备上截图，iOS 同时按下电源键和 Home 键，安卓为 电源键 和 音量键-即可进行截图（此时屏幕会闪一下）。
2. 使用触动精灵抓色器（http://www.touchsprite.com/tools）可方便的获取所需坐标点的颜色信息，推荐使用。
   常见颜色表：http://www.114la.com/other/rgb.htm

名词解析

1. R,G,B值，即代表红(Red)、绿(Green)、蓝(Blue)三个通道的颜色强度。
2. 整型，指的是可以用十、十六、八进制指定的数据类型。使用十六进制符号，必须加上 0x。
3. 赋值是 Lua 基本语法，操作符为"="（一个等号）。
4. 等于是 Lua 基本语法，属于条件控制，操作符为"=="（两个等号）。新手常常将等于写作赋值，从而导致编译出现错误。

函数：findColorInRegionFuzzy 区域模糊找色

函数名称：区域找色、模糊找色、区域模糊找色

函数功能：在指定区域中，寻找符合指定颜色的坐标，支持模糊查找。

函数方法

x, y = findColorInRegionFuzzy(整型 color, 整数型 degree, 整数型 x1, 整数型 y1, 整数型 x2, 整数型 y2);
返回值：整数型 x, y

脚本实例：
1.精确寻找指定区域中，指定颜色的坐标，并按下
--寻找符合条件的点

x, y = findColorInRegionFuzzy(0x112233, 100, 50, 50, 300, 300); 
if x ~= -1 and y ~= -1 then  --如果在指定区域找到某点符合条件
    touchDown(x, y);         --那么单击该点
    mSleep(30);
    touchUp(x, y);
else                         --如果找不到符合条件的点
    dialog("未找到符合条件的坐标！",0);
end

2.模糊查找指定区域中，尽可能接近指定颜色的点，并按下

for deg = 100, 1, -1 do           --使用 for 循环不断降低精确度
    x, y = findColorInRegionFuzzy(0xffffff, deg, 50, 50, 300, 300); 
    if x ~= -1 and y ~= -1 then   --如果在指定区域找到某点符合条件
        nLog("在模糊度:"..deg.."下找到一个相似的颜色,坐标:"..x..":"..y)
        touchDown(x, y);          --那么单击该点
        mSleep(30)
        touchUp(x, y);
        break;                    --并跳出循环
    end
end

注意事项：

1. 未找到则返回 (-1, -1) ，所以找到时 x, y 均不等于 -1，~= 为不等于操作符，是 Lua 基本语法， 属于逻辑控制。
2. 通过不断降低模糊查找精确度的方法在指定区域查找到的不一定是最接近指定颜色的点，该代码应用过程中，建议使用"保持屏幕"减少性能损耗，参见"保持屏幕"一章。

函数：findImageInRegionFuzzy 区域模糊找图

函数名称：区域找图、模糊找图、区域模糊找图

函数功能：在指定区域中，寻找指定的图案，返回其左上角顶点坐标，支持模糊查找。

支持版本：引擎版本 iOS v1.0,Android v2.1.0以上

函数方法

x, y = findImageInRegionFuzzy(文本型 picpath, 整数型 degree, 整数型 x1, 整数型 y1, 整数型 x2, 整数型 y2, 整型 alpha, 整数型 type);
返回值：整数型 x, y

脚本实例：
精确寻找指定区域中，指定图片的位置

--寻找符合条件的图片（假设图片的背景颜色为白色）
x, y = findImageInRegionFuzzy("test_alpha.png", 90, 0, 0, 320, 480, 0xffffff);
if x ~= -1 and y ~= -1 then        --如果在指定区域找到某图片符合条件
    touchDown(x, y);            --那么单击该图片
    mSleep(30)
    touchUp(x, y);
else                               --如果找不到符合条件的图片
    dialog("未找到符合条件的坐标！",0);
end

注意事项：

1. 以下找图几种 type 方式：
   type为空-RGB找图，适用于静态画面，找图速度快，兼容性一般
type为1-二值化找图，适用于所有画面，找图速度慢，兼容性好
type为2-二值化找图，适用于静态画面，找图速度快，兼容性好
2. Android 仅支持png格式图片。
3. iOS 默认图片路径为 /var/mobile/Media/TouchSprite/res,Android 为/mnt/sdcard/TouchSprite/res（参数中无需填写完整路径），自建目录请填写相对路径。
4. 忽略的颜色值指将要寻找的图片的背景颜色，即在屏幕画面上不匹配寻找对象的背景颜色。
5. 若该函数找图不理想可使用findImage 高级区域找图，几种找图方式可配合使用。
6. 参数 type 为 1 需引擎版本 iOS v2.3.6-7 以上支持，type为 2 需要引擎版本 iOS v2.3.7 以上支持。

函数：findMultiColorInRegionFuzzy 区域多点找色

函数名称：多点找色，区域多点找色

函数功能：在指定区域，根据颜色以及其周边点的颜色，寻找符合条件的点的坐标，支持模糊查找。

函数方法

x, y = findMultiColorInRegionFuzzy(整型color,文本型posandcolor, 整数型degree, 整数型x1,整数型y1,整数型x2,整数型y2);
返回值：整数型 x, y

进阶指导：

当我们使用“区域模糊找色”函数时，常常会因为屏幕上有大量符合指定颜色的点而找不到 需要的坐标。该函数通过在寻找到一个符合指定颜色color的坐标后，进一步确认其周边点坐标的方式，来确定准确目标。例如，现在我们在图像上找到了我们需要的一个按钮，这个按钮的图案是不变的，但是它的整体位置却会在整个屏幕上变化，现在我们想要在脚本运行时得到其坐标。
我们首先找到一个点：
这个点的颜色为 0x181F85，坐标为 (268, 802)。
记录下来，接着找这个按钮上的另外一个点：
这个点的颜色为 0x00BBFE，坐标为 (297, 803)，相对于第一个点的坐标为 (29, 1)。 记录下来，接着找这个按钮上的第三个点和第四个点。
第三个点的颜色为 0x0B6BBE，坐标为 (371, 798)，相对于第一个点的坐标为 (103, -4)。
第四个点的颜色为 0x150972，坐标为 (333, 811)，相对于第一个点的坐标为 (65, 9)。
现在我们找到了需要的三个点：

现在我们可以把它写成多点找色的格式了：

--多点找色
--在屏幕上以左上角坐标 (0,0) 和右下角坐标 (639, 959)确定的区域（即全屏）范围内寻找符合偏移范围和颜色的3个坐标点
x, y = findMultiColorInRegionFuzzy(0x181F85, "29|1|0x00BBFE,103|-4| 0x0B6BBE,65|9|0x150972", 100, 0, 0, 639, 959); 
dialog(x..","..y, 0)
--另外一种偏色模式，引擎版本 iOS v2.4.1以上支持
--main为参照点0xffffff的偏色，list为周边点的偏色，如果想对每一个周边点单独偏色，在每一个偏色后面加上偏色值即可，如 "0|0|0x1ac819|0x202020"
x, y = findMultiColorInRegionFuzzy(0xffffff,"0|0|0x1ac819,-4|-208|0x18cb76,3|58|0x21cc79", 90, x, y, x0, y0,  { main = 0x101010, list = 0x202020 } )
dialog(x..","..y, 0)

那么返回的(x, y)就应该是(268,802)了。即使这个按钮平移了，这个点的坐标变了，也可以寻找到其准确位置。

注意事项：

1. posandcolor 参数中的坐标为相对坐标。
2. 多点找色的代码可直接用触动精灵取色工具生成，其使用方法参见图文教程。
3. 颜色值的十六进制文本中，其顺序为RGB。
4. 相对于第一个点的坐标，即用这个点的横坐标、纵坐标分别减去第一个点的横坐标、纵坐标，可以为负数。
5. 使用此函数时精度参数设置过低，会导致性能大幅下降。
6. 引擎版本 iOS v2.3.6 以上要求包括基准点在内的所有参照点都必须在查找范围之内。

函数：findMultiColorInRegionFuzzyExt 高级区域多点找色

函数名称：高级多点找色，高级区域多点找色

函数功能：在指定区域，根据颜色以及其周边点的颜色，寻找所有符合条件的点的坐标，支持模糊查找。

支持版本：引擎版本 iOS v1.0,Android v1.2.8 以上

函数方法

point = findMultiColorInRegionFuzzyExt(整型color,文本型posandcolor, 整数型degree, 整数型x1,整数型y1,整数型x2,整数型y2);
返回值：table类型 point

返回的 table 为以下形式：

table = {
    {x = 100,y = 110},
    {x = 200,y = 210},
    {x = 300,y = 310},
    ...
}

脚本实例：

point = findMultiColorInRegionFuzzyExt( 0xcf0000, "-37|3|0x942814,-38|20|0xeba62d,1|54|0xf2b054,28|22|0x8a5707", 90, 97, 220, 903, 701)
if #point ~= 0 then  --如返回的table不为空（至少找到一个符合条件的点）
    for var = 1,#point do
        nLog(point[var].x..":"..point[var].y)
    end
end
--另外一种偏色模式，引擎版本 iOS v2.4.1以上支持
--main为参照点0xffffff的偏色，list为周边点的偏色，如果想对每一个周边点单独偏色，在每一个偏色后面加上偏色值即可，如 "0|0|0x1ac819|0x202020"
point = findMultiColorInRegionFuzzyExt(0xffffff,"0|0|0x1ac819,-4|-208|0x18cb76,3|58|0x21cc79", 90, x, y, x0, y0,  { main = 0x101010, list = 0x202020 } )
if #point ~= 0 then  --如返回的table不为空（至少找到一个符合条件的点）
    for var = 1,#point do
        nLog(point[var].x..":"..point[var].y)
    end
end

注意事项：

1. 引擎版本 iOS v 2.3.6 以上版本中要求包括基准点在内的所有参照点都必须在查找范围之内。

函数：findImage 高级区域找图（仅支持 iOS）

函数名称：区域找图、高级区域找图

函数功能：在指定区域中，寻找指定的图案，返回其左上角顶点坐标。

支持版本：引擎版本 iOS v2.3.0 以上

函数方法

x, y = findImage(文本型 picpath, 整数型 x1, 整数型 y1, 整数型 x2, 整数型 y2, 整数型 alpha);
返回值：整数型 x, y

脚本实例：
1.精确寻找指定区域中，指定图片的位置
--寻找符合条件的图片

snapshot('test.png',1,1,55,55)     --截图到资源文件夹
x, y = findImage("test.png", 0, 0, 120, 480);--在（0,0）到（120,480）寻找刚刚截图的图片
if x ~= -1 and y ~= -1 then        --如果在指定区域找到某图片符合条件
    toast(x..y);                   --显示坐标
else                               --如果找不到符合条件的图片
    toast('没有找到图片!');        
end

注意事项：

1. 此函数推荐与snapshot 截图函数配合使用，成功率较高。
2. 匹配精度建议每次加减1000000，此参数值越低匹配精度越高
3. 默认图片路径为 /var/mobile/Media/TouchSprite/res（参数中无需填写完整路径），自建目录请填写相对路径。
4. 若该函数找图不理想可使用findimageinregionfuzzy模糊区域找图，几种找图方式可配合使用。

函数：snapshot 截图

函数名称：截图

函数功能：截取屏幕中指定区域的图像并生成指定格式的图片文件

函数方法

snapshot(文本型 picname, 整数型 x1,整数型y1, 整数型 x2, 整数型 y2, 数字型 quality);
返回值：无

脚本实例：
iOS 示例

snapshot("test.png", 0, 0, 639, 1135); --以test命名进行截图

--全屏截图（iPhone 5, 5S），并以当前日期为文件名保存

current_time = os.date("%Y-%m-%d", os.time());
snapshot(current_time..".png", 0, 0, 639, 1135); --以时间戳命名进行截图
snapshot(current_time..".jpg", 0, 0, 639, 1135, 0.5); --使用jpg格式截图，并设置图片质量为0.5

Android 示例
--全屏截图（以小米 4 为例），并以当前日期为文件名保存

current_time = os.date("%Y-%m-%d", os.time()); --以时间戳命名进行截图
w,h = getScreenSize();
-- 右下角顶点坐标最大为 (宽度最大值-1, 高度最大值-1)
snapshot(current_time..".png", 0, 0, w-1, h-1); 

注意事项：

1. Android 系统保存图片只支持png格式，不可以设置质量;iOS 系统保存图片的格式可为 bmp, jpg, png，因为 png 是 iOS 中最常见的格式，所以推荐选择 png。
2. 截图时，如使用全屏截图，右下角顶点坐标最大为 ((宽度最大值-1, 高度最大值-1)，否则 iOS 系统会出现越界错误，安卓系统截出的图会是纯白色的。
3. 默认图片路径请使用 userPath 函数获取，具体使用方法请参阅 对应章节，自建目录请填写相对路径，文件相同将会被覆盖
4. 本文 iOS 实例中 os.date 与 os.time 为 Lua 基本库函数，请查阅附录 Lua 操作系统函数库。
5. ".." 为字符串连接操作符，可以将字符串变量、常量连接在一起。
6. 本文 iOS 实例中 640 * 1136 为 iPhone 5, 5S 等设备的分辨率，实际使用中请根据运行设备替换为对应值。
7. quality 参数仅在引擎版本高于 iOS v2.0.9 时方可使用。
8. 当引擎版本高于 iOS v2.2.5-1,Android v2.0.5 时，四个坐标参数省略，默认截取全屏图像。

函数：imageOperMerge 图片合并（仅支持 iOS）

函数名称：图片合并

函数功能：将几张图片合并生成一张新图片。

支持版本：引擎版本 iOS v2.3.4 以上

函数方法

flag = imageOperMerge(Table型 pictb, 文本型 path, 整数型 type, 数字型 quality);

返回值：整数型 flag

脚本实例：

snapshot("1.png",100,100,200,200)   --截取屏幕上左上角坐标为 (100,100),右下角坐标为 (200,200) 区域，宽高皆为 100 像素的图片，图片名为 1.png
snapshot("2.png",100,200,200,300)   --截取屏幕上左上角坐标为 (100,200),右下角坐标为 (200,300) 区域，宽高皆为 100 像素的图片，图片名为 2.png
snapshot("3.png",100,300,200,400)   --截取屏幕上左上角坐标为 (100,300),右下角坐标为 (200,400) 区域，宽高皆为 100 像素的图片，图片名为 3.png
imageOperMerge({"1.png","2.png","3.png"},"4.jpg",0,0.5)   --将上面截取的三张图片合成为一张并命名为 4.jpg

注意事项：

1. iOS 系统默认图片路径为 /var/mobile/Media/TouchSprite/res，自建目录请填写相对路径
2. 当脚本要上传到帮你玩、企业版和小精灵平台时，请使用 userPath 函数代替 /res 之前的目录使之自动获取。

开发辅助类

函数：initLog、wLog、closeLog 日志函数

函数名称：初始化日志、写日志、关闭日志

函数功能：配置日志输出地址与方式、写出或发送日志、关闭日志输出连接。

函数方法

initLog(文本型 name, 整数型 flag);
wLog(文本型 name, 文本型 contents);
closeLog(文本型 name);
返回值：无

输出方式

0 - 输出到文件名
1 - 输出到带时间戳的文件名
2 - 异步发送到服务器
3 - 同步发送到服务器

脚本实例：
1.写到本地日志

initLog("test", 0);                 --初始化日志 test.log，把 0 换成 1 即生成形似 test_1397679553.log 的日志文件 
wLog("test","[DATE] Test_1 OK!!!"); --写入日志,日志内容：当前时间 Test_1 OK!!!
mSleep(500);                        --间隔时间 500 毫秒
wLog("test","[DATE] Test_2 OK!!!");
closeLog("test");                   --关闭日志

2.发送服务器日志

initLog("192.168.1.1", 2);                  --初始化日志，并以异步方式发送；把 2 换成 3  即为同步发送
wLog("192.168.1.1", "[DATE] Test OK!!!");   --将日志发送到 192.168.1.1
closeLog("192.168.1.1");                    --关闭服务器连接

3.多日志记录

initLog("test_1", 0);                  --初始化日志test_1.log
initLog("test_2", 0);                  --初始化日志test_2.log
wLog("test_1","[DATE] Test_1 OK!!!"); 
mSleep(500);
wLog("test_2","[DATE] Test_2 OK!!!"); 
closeLog("test_1");
closeLog("test_2");

注意事项

1. flag参数设置为 2 和 3，需要引擎版本 iOS v1.7.0,Android v1.0 及以上版本支持，并需要配合触动精灵日志服务端 使用，要求设备与运行服务端的PC处于同一网段。
2. 该函数支持多日志记录，即可以定义并初始化多个日志用于分类存放。
3. 此函数一般用于脚本开发阶段，若脚本开发完成，只需注释掉initLog即可。
4. 日志的编码为 UTF-8，请使用支持 UTF-8 编码的编辑器查看。

函数：sysLog 系统日志

函数名称：系统日志

函数功能：输出系统日志 NSLog

函数方法

sysLog(文本型 contents);
返回值：无

-- 打开命令行 切换到adb文件目录下 输入 adb logcat -s touchsprite 
sysLog("start")
os_type = getOSType()
if os_type == "android" then
    sysLog("Android")
else
    sysLog("iOS")
end
sysLog("end")

注意事项：

1. 该函数将日志输出到系统级日志中，iOS 系统请使用 iTools 或 XCode 查看，Android 系统使用adb工具查看，过滤标识为 touchsprite。
2. 当使用同步消息传送时，脚本需等待日志已经到达服务端才继续执行下面的指令。
3. 当使用异步消息传送时，调用者在发送消息以后可以不用等待响应，可以接着处理其他任务。 即发送日志无需等待发送完成即可继续执行。
4. 注释的操作符形式为 --...... 或 --[[......]] ，可将用于说明的代码写入脚本以便开发时理解。

函数：nLog 远程日志

函数名称：远程日志

函数功能：输出日志到触动精灵 IDE 编辑器（TS Studio）

支持版本：引擎版本 iOS v2.1.6，Android v1.3.0 以

函数方法

nLog(文本型 contents);
返回值：无

脚本实例：

for var = 1,50 do
    nLog("[DATE]"..var);--在编辑器的日志输入界面查看
    mSleep(100);
end

注意事项：

1. 该函数需要脚本编辑器 v1.0.3 以上支持。
2. 此函数仅作为调试用途，由触动精灵脚本编辑器发起的脚本运行将会接收到 nLog 回传信息，其他方式运行的脚本将不会触发 nLog 函数。
3. 使用该函数无需设置日志接收端 IP 地址。
4. 请在编辑器的日志输出面板查看该函数返回的日志信息。
5. 当脚本中频繁使用此函数时，由于日志是异步发送的，如果编辑器接收到的日志内容没有按照顺序显示，是正常现象。此问题可以通过在 nLog 之间插入toast 函数解决。

脚本控制

函数：mSleep 延时

函数名称：等待延迟,延时

函数功能：发送系统等待事件。

函数方法

mSleep(整数型interval);
返回值：无

脚本实例：
1.延迟1秒和1分钟

mSleep(1000);       --延迟1秒钟
mSleep(60 * 1000)   --此函数不适合用于长时间的精确计时，如长时间的精确计时请使用 os.time

2.按住 3 秒不松手

touchDown(200, 300);    --按下
mSleep(3000);           --延迟 3 秒
touchUp(200, 300);      --抬起

注意事项：

1. 延迟函数的使用与各类函数的使用息息相关，尤其是触摸类函数。脚本一般是用来模拟人在界面上的操作，因此要考虑人在各种情况下的延迟、界面加载时的响应时间。
2. 延迟间隔不可过短，当 interval <= 50 ms 时，延迟精确度大幅下降，当 interval <= 16 ms 时，实际延迟约在16 ms左右。
3. 请勿将此函数用于长时间的精确计时。
4. 1 秒 (s) = 1000 毫秒 (ms)。

函数：lua_exit 退出脚本

函数名称：退出脚本、结束函数

函数功能：直接终止脚本。

函数方法

lua_exit();
返回值：无

脚本实例：
弹出许可协议，若不同意则退出脚本

ret = dialogRet("许可协议\n协议内容", "同意", "不同意", 0, 0);
if ret == 0 then    --如果按下"同意"按钮
    toast("您选择了同意")
else 
     toast("您选择了不同意，脚本退出运行")
    lua_exit();     --否则退出脚本
end

注意事项：

1. 需要注意的是调用该函数时，脚本并非立即终止执行，脚本将会在你调用此函数之后的下一行结束，如果不希望出现此情况可以在调用函数之后加入一行无意义代码即可。

函数：lua_restart 重载脚本

函数名称：重新加载运行脚本

支持版本：iOS 引擎版本 v2.2.1，Android v1.1.9 以上

函数方法

lua_restart();
返回值：无

脚本实例：

dialog("重载脚本", 0)
lua_restart()
dialog("执行不到这里", 0)

注意事项：

1. 此函数作用相当于停止脚本后重新运行脚本。

函数：luaExitIfCall 来电暂停

函数名称：来电暂停

函数功能：设置电话拨入时停止脚本运行的标识。

支持版本：iOS 引擎版本 v1.0，Android v2.0.9 以上

函数方法

luaExitIfCall(逻辑型 flag);
返回值：无

脚本实例：

luaExitIfCall(true); --当有电话拨入时，检查来电暂停状态标识，若为 true，则立即终止脚本；若为 false，则继续运行脚本[此处输入链接的描述][21]
init(0);

注意事项：

1. 该函数在脚本中可使用多次，以调整配置。
2. 当有电话拨入时，检查来电暂停状态标识，若为 true，则立即终止脚本；若为 false，则继续运行脚本。
3. 引擎版本 iOS v2.2.4 以上版本将停止改为暂停。

函数：checkScriptAuth 脚本授权

函数名称：脚本授权

函数功能：获取脚本的格式类型、授权状态和脚本 ID

支持版本：iOS 引擎版本 v2.2.6,Android v2.0.3 及以上；帮你玩 iOS v1.0.1 以上

函数方法

tsp = checkScriptAuth();
返回值：Table型 tsp

脚本实例：

tsp = checkScriptAuth()
nLog(tsp.type)      --输出脚本类型  lua  tsp p4u

tsp = checkScriptAuth()
nLog(tsp.id)      --输出tspid号，脚本必须为tsp否则返回空值

tsp = checkScriptAuth()
if tsp.auth == 2 then --试用字段 iOS 只支持 v2.4.1,Android v2.2.4 以上版本
    dialog("脚本状态：试用中")
elseif tsp.auth == 1 then
    dialog("脚本状态：已激活")
else
    dialog("脚本状态：未激活")
end

系统相关

函数：dialog 提示框

函数名称：对话框，弹窗，提示框

函数功能：弹出提示信息。

函数方法

dialog(文本型 text, 整数型 time);
返回值：无

脚本实例：
1.欢迎使用

dialog("欢迎使用触动精灵！", 5); --Android 系统在部分设备上需要在系统设置里开启悬浮窗权限方可正常使用此函数
mSleep(1000);
dialog("本脚本仅供演示对话框的用法。\n提示信息可以换行。",0);

注意事项：

1. time 参数时间一般在 2 秒以上，否则出现时间太短看不清楚。
2. 该函数仅供呈现提示信息给用户，不可接收返回值。
3. 该函数所产生的提示窗口显示的时候会影响当前屏幕取色，请在合理的位置使用该函数。
4. 关于转义字符：\r\n 为换行，请查阅 Lua 转义字符表。
5. 在引擎版本 iOS v2.2.4 以上版本中，time 参数可省略，如省略将按 0 处理。
6. 安卓系统在部分设备上需要在系统设置里开启悬浮窗权限方可正常使用此函数。

函数：toast 提示

函数名称：HUD 提示,吐司提示

函数功能：在屏幕底部以悬浮层形式显示字符串信息

支持版本：iOS 引擎版本 v2.2.4 以上

函数方法

toast(文本型 text, 整数型 time);
返回值：无

脚本实例：
1.欢迎使用

toast("欢迎使用触动精灵！"); 
mSleep(3000);-- 建议 toast 函数后面添加 3 秒间隔否则可能显示错误
toast("本脚本仅供演示toast函数效果。\n提示信息可以换行。");

注意事项：

1. 该函数所产生的提示信息将以HUD形式显示在屏幕上，该函数所产生的提示信息可能会影响当前屏幕的找色，请合理使用。

函数：dialogRet 带按钮的对话框

函数名称：带按钮的对话框

函数功能：弹出提示信息，并提供 1 ~ 3 个按钮给用户选择。

函数方法

choice = dialogRet(文本型 text, 文本型 cbtn, 文本型 btn1, 文本型 btn2, 整数型 time);
返回值：整数型 choice

脚本实例：
1.选择性别（双选）

choice = dialogRet("请选择您的性别：", "男", "女", "", 0);

2.选择性别（三选）

choice = dialogRet("请选择您的性别：", "男", "女", "人妖", 0);
if choice == 0 then      --男
    dialog("你好，帅哥。",0);
    mSleep(1000);
elseif choice == 1 then  --女
    dialog("你好，美女",0);
    mSleep(1000);
else                     --人妖
    dialog("人妖不允许使用该脚本。",0);
    mSleep(1000);
    lua_exit();          --退出脚本
end

3.请阅读许可协议

dialogRet("这里是许可协议或广告，强制阅读 30 秒不可消除。", "", "", "", 30);

注意事项：

1. 请勿将三个按钮都设置为空，再将 time 参数设置为 0，这样将造成出现无法消失也没有按钮的 对话框，造成设备无法进行其它操作，只能重启（已在 2.3.6 版本中修复）。
2. 值得一提的是，cbtn 总是对话框的最右边或者最下面的按钮。
3. 参数中的 0 是数字，不是文本 "0"。
4. 当 time 参数不为 0 并且用户没有选择，超时将返回 3。

函数：dialogInput 参数对话框（仅支持 iOS）

函数名称：参数对话框

函数功能：弹出提示信息，并提供 1 ~ 2 个编辑框给用户输入。

函数方法

text_a = dialogInput(文本型 title,文本型 format,文本型 btn);
返回值 1 文本型 text_a 返回用户输入的文本
text_a,text_b = dialogInput(文本型title,文本型format,文本型 btn);
返回值 2 文本型 text_a, text_b 返回用户输入的文本

脚本实例：
1.输入姓名

::getInfo:: --设置跳转标签
text_a = dialogInput("请输入您的姓名", "在这里输入姓名", "确认");
mSleep(1000);

2.输入姓名和年龄

::getInfo:: --设置跳转标签
text_a, text_b = dialogInput("请选择您的姓名和年龄", "在这里输入姓名#在这里输入年龄", "确认");
text_b = tonumber(text_b)                                   --年龄转化成数字类型
mSleep(1000);
if text_b ~= nil and text_a ~= "" then                      --均已填写
    dialog("你好，"..text_b.." 岁的 "..text_a.." 。", 5);
    mSleep(1000);
elseif text_a ~= "" then                                    --只填写了姓名
    dialog("你好， "..text_a..",忘记年龄了？ 请输入年龄。", 5);
    goto getInfo
    mSleep(1000);
else                                                        --均未填写
    dialog("请填写您的信息！", 5);
    mSleep(1000);
    goto getInfo;                                           --返回重新填写
end

注意事项：

1. 一般来说，使用该函数都要对用户输入的数据进行一定的检查，例如要求非空、长度不得少于。
2. 使用双编辑框时，函数返回的两个字符串顺序与 format 中的顺序相反，请注意。
3. 由于对话框事件需要响应时间，所以建议每次使用对话框，均应使用延迟。

名词解析：

1. goto 是 Lua 基本语法，设置标签，然后使用 goto 函数跳转到代码的指定位置向下执行。该函数请谨慎使用，因为大量的跳转会造成代码编写的混乱。

函数：getNetTime 获取网络时间

函数名称：获取网络时间

函数功能：从互联网上获取时间信息，返回从1970年1月1日到当前状态的秒数。

函数方法

time = getNetTime();
返回值：整数型 time

脚本实例：
获取网络时间 & 格式化网络时间

time = getNetTime();        
time_year = os.date("%Y",time)          --格式化 time 值获取年份
toast(time_year)
mSleep(3000)
time_M = os.date("%m",time)             --格式化 time 值获取月份
toast(time_M)
mSleep(3000)
time_D = os.date("%d",time)             --格式化 time 值获取日
toast(time_D)
mSleep(3000)
toast(os.date("%Y年%m月%d日",time))        --连起来可以写成这样
mSleep(3000)
toast(os.date("%Y年%m月%d日%H点%M分%S秒",time))       --或这样

获取网络时间并判断脚本过期

origin = 1404439947;                            --代表北京时间 2014/7/4 10:12:27
origin_text = os.date("%Y/%m/%d %X", origin);   --格式化时间 
current = getNetTime();                         --获取网络时间 
current_text = os.date("%Y/%m/%d %X", current); --格式化时间 
if origin >= current then
    dialog("脚本尚未过期！", 5);
else
    dialog("脚本已经过期！\n脚本使用期限："..origin_text.."\n当前时间："..current_text, 5); 
    lua_exit();
end

注意事项：

1. 该函数需要网络支持，且根据网络状况有所延迟。
2. 当无法正确获取的时候该函数返回0。

函数：addContactToAB 添加联系人

函数名称：添加联系人

函数功能：添加联系人到通讯录

支持版本：引擎版本 iOS v2.3.6，Android v2.0.5 以上

函数方法

addContactToAB({文本型 lastname,文本型 firstname,文本型 mobile});
返回值：无

脚本实例：

addAB = {
    {lastname="小",firstname="明",mobile="10080"},
    {lastname="小",firstname="红",mobile="10010"},
    {lastname="小",firstname="白",mobile="10000"}
}
for _,v in ipairs(addAB) do
    addContactToAB(v)
end

脚本实例：添加 100 个号码到手机通讯录

addAB = {}
f = 1
for k = 1860996268,1860996368 ,1 do
    addAB[f] = {lastname,firstname,mobile}      --通过 f 的值按顺序创建表格
    addAB[f].lastname = tostring(k)             --生成姓
    addAB[f].firstname = tostring(k)            --生成名
    addAB[f].mobile = tostring(k)               --生成电话号码
    f = f + 1
end
for _,v in ipairs(addAB) do
    addContactToAB(v)                           --添加到联系人
end

注意事项：

1. 批量导入数据量过大的时候，导入过程会比较长。

函数：removeAllContactsFromAB 清空通讯录

函数名称：清空通讯录

函数功能：删除通讯录所有联系人

支持版本：引擎版本 iOS v2.3.6，Android v2.0.5 以上

函数方法

removeAllContactsFromAB();
返回值：无

UTF-8 编码

模块说明

本模块提供了对 UTF-8 编码的基础支持。 所有的函数都放在表 utf8 中。
除非另有说明， 当一个函数需要一个字节位置的参数时， 都假定这个位置要么从字节序列的开始计算， 要么从字符串长度加一的位置算。 和字符串库一样，负的索引从字符串末尾计起。

函数：utf8.char 整数序列转换字符串

函数名称：整数序列转换字符串

函数功能：接收零或多个整数， 将每个整数转换成对应的 UTF-8 字节序列，并返回这些序列连接到一起的字符串。

函数方法

str = utf8.char (number_1,number_2...)

函数用例：

str = utf8.char(35302,21160,31934,28789) 
dialog(str, time)

扩展：

• utf8.charpattern字符串用于精确匹配到一个 UTF-8 字节序列的模式
  详情参照这里：http://www.runoob.com/manual/lua53doc/manual.html#6.4.1

函数：utf8.codes 获取字符编码

函数名称：获取字符编码

函数功能：返回字符串中每个字符的编码

函数方法

for index,code in utf8.codes(str) do
--body
end

函数用例：

str = "触动精灵"
for index,code in utf8.codes(str) do 
    dialog(string.format("%s的unicode编码为\\u%0x",index,code),time)
end 

注意事项：

• 返回字符位置按字节数计算。
• 如果处理到一个不合法的字节序列，将抛出一个错误。

函数：utf8.codepoint 获取指定位置字符编码

函数名称：获取指定位置字符编码

函数功能：获取指定位置字符编码，以整数形式返回

函数方法

strcode = utf8.codepoint (str , i , j)

函数用例：

local str = "触动精灵"
strcode = utf8.codepoint (str)
dialog(strcode, time) 

注意事项：

• 如果处理到一个不合法的字节序列，将抛出一个错误。

函数：utf8.len 统计字符个数

函数名称：统计字符个数

函数功能：统计指定位置的字符个数

函数方法

length = utf8.len (str , i , j)

函数用例：

local str = "触动精灵"
length = utf8.len (str)
dialog(length, time)

注意事项：

• 如果处理到一个不合法的字节序列， 返回第一个不合法字节的位置。

函数：utf8.offset 获取字符位置

函数名称：获取字符位置

函数功能：返回字符串中的第n个字符的开始位置

函数方法

start_num = utf8.offset (str , n , i)

函数用例：

local str = "触动精灵"
start_num = utf8.offset (str , 2)
dialog(start_num, time)

注意事项：

• 返回字符位置按字节数计算。
• n 为负数则取在位置 i 前的字符。 当 n 是非负数时，默认的 i 是 1， 否则默认为字符串的长度加一。
• 如果处理到一个不合法的字节序列，将抛出一个错误。

文字输入及按键模拟

函数：inputText 输入字符串

函数名称：输入字符串

函数功能：向输入框中输入文本

函数方法

inputText(文本型string);
返回值：无

脚本实例：
输入欢迎文本并发送

touchDown(150,150);       --点击输入框获取焦点（假设输入框坐标已知）
mSleep(30)
touchUp(150,150);
mSleep(1000);             --延迟 1 秒以便获取焦点,注意某些应用不获取焦点无法输入
for var = 1,15 do
    inputText("\b")       --删除输入框中的文字（假设输入框中已存在文字）
end
inputText("Welcome.#ENTER#"); --在输入框中输入字符串"Welcome."并回车;此函数在某些应用中无效，如支付宝、密码输入框等位置，甚至可能会导致目标应用闪退

注意事项：

1. 使用该函数前，必须先点击输入框获取焦点（指使当前的输入光标停留在某一输入框中）
2. 控制字符包括 \b、\n、\r、#ENTER#,如果设备系统版本为 iOS 7，\r无法使用，使用\b需安装引擎版本 iOS v1.6.9 及以上
3. 仅在 iOS 7 上可使用"#ENTER#"作为回车，相当于点击虚拟键盘上的 "Done"
4. 需要注意的是，并不是所有输入框都可以使用此功能，如支付宝、密码输入框等位置，甚至可能会导致目标应用闪退
5. 该函数不支持第三方输入法(指百度输入法、搜狗输入法等)，iOS 系统请切换到系统内置输入法，安卓系统在使用该函数时，将自动切换至触动精灵输入法
6. 模拟器不能输入的话，需要修改设置,修改教程:http://bbs.touchsprite.com/thread-5203-1-1.html
7. 对于弹出的窗口，需要先初始化再使用该函数，例如 App Store登录窗口(该窗口Bundle ID 为"com.apple.springboard")

函数：switchTSInputMethod 切换到触动/帮你玩输入法（仅支持 Android）

函数名称：切换到触动/帮你玩输入法

函数功能：主动切换到触动/帮你玩输入法，大幅提高多次调用inputText执行效率，解决部分第三方输入法无法使用inputText的问题。

支持版本：触动精灵Android v2.0.8以上

函数方法

switchTSInputMethod(逻辑型 flag);
返回值：无

脚本实例：

-- 需要多次输入的登录模块
function login(...)
    switchTSInputMethod(true);   -- 切换到触动/帮你玩输入法
    -- 点击输入框获取焦点
    touchDown(x, y)
    mSleep(30)
    touchUp(x, y)
    inputText("username")
    -- 点击输入框获取焦点
    touchDown(x, y)
    mSleep(30)
    touchUp(x, y)
    inputText("password")
    switchTSInputMethod(false);  -- 切换到之前的输入法
end
-- 不需要inputText输入的其他逻辑模块
function main(...)
    login()
end
main()

注意事项：

1. 点击输入框之前调用switchTSInputMethod(true)，结束调用inputText时调用switchTSInputMethod(false)，这样不会导致用户手动输入失败或者inputText输入异常。
2. 先调动switchTSInputMethod(true)，才可以通过switchTSInputMethod(false)切换回之前的输入法，单纯调用switchTSInputMethod(false)没有效果。
3. 猩猩模拟器不支持切换输入法，不切换输入法也可以正常输入。

函数：getInPutMethod 获取当前输入法包名（仅支持 Android）

函数名称：获取当前输入法包名
函数方法 : getInPutMethod();
返回值：文本型 bid
支持版本：触动精灵Android v1.3.0以上

脚本实例：
频繁输入字符的脚本

-- 脚本启动,获取输入法包名
ipm = getInPutMethod()  
-- 切换到触动输入法
os.execute("settings put secure default_input_method com.touchsprite.android/.core.TSInputMethod")  
-- 脚本主体
-- 结束脚本前切换回之前的输入法
os.execute("settings put secure default_input_method "..ipm)    

注意事项：

1. 触动输入法包名: "com.touchsprite.android/.core.TSInputMethod"

函数：pressHomeKey 模拟主屏幕按键

函数名称：模拟主屏幕按键，模拟 Home 按键

函数功能：模拟用户按下或抬起主屏幕按键的操作。

支持版本：引擎版本 iOS v1.0, Android v1.3.0 以上

函数方法

pressHomeKey(整数型 flag);
返回值：无

脚本实例：
iOS 系统返回主屏幕

pressHomeKey(0);    --按下 Home 键
pressHomeKey(1);    --抬起 Home 键

Android 系统返回主屏幕

pressHomeKey(); --Android 系统不需要填参数，自动点击抬起

iOS 系统调出后台

pressHomeKey(0);    --按一次 Home 键
pressHomeKey(1);
mSleep(30);     --短暂延迟
pressHomeKey(0);    --再按一次，在 iOS 7 以上版本中使用双击功能可使用函数 doublePressHomeKey
pressHomeKey(1);

3.调出 Siri （iPhone 4S 以上，iOS 6 及以下或触动版本高于v2.3.5）

pressHomeKey(0);    --按下 Home 键
mSleep(3000);       --按住不放
pressHomeKey(1);    --抬起

注意事项：

1. 在 iOS 6 系统上，状态标识为 0 时，调用该函数则开始按下 Home 键并按住不放，直到状态标识为 1 时重新调用该函数，抬起 Home 键。
2. 在 iOS 7 系统上，状态标识只能填写 0，代表按一次 Home 键，即按下并立即抬起 Home 键的操作（该问题已经在触动v2.3.5中修复）。
3. 在 iOS 7 以上版本中使用双击功能可使用函数 doublePressHomeKey ，具体用法请参照对应章节。

函数：doublePressHomeKey 双击 HOME 键（仅支持 iOS）

函数名称：双击 HOME 键

函数功能：模拟用户双击 HOME 键的操作。

函数方法

doublePressHomeKey();
返回值：无

脚本实例：
1.双击HOME键打开后台

doublePressHomeKey();           --此函数仅能用于 iOS 7 或以上版本

注意事项：

1. 此函数需触动精灵iOS V2.x 以上版本支持
2. 此函数仅能用于 iOS 7 或以上版本

函数：keyDown、keyUp 模拟键盘（仅支持 iOS）

函数名称：模拟键盘

函数功能：模拟外接键盘按下、抬起。

支持版本：引擎版本 iOS v2.3.5 以上

函数方法

keyDown(文本型 key);
keyUp(文本型 key);
返回值：无

脚本实例：

                     --以下为粘贴示例
keyDown("RightGUI") 
keyDown("v")
keyUp("v")
keyUp("RightGUI")
                    --以下为输入小写字母
keyDown("t")
keyUp("t")
                    --以下为输入大写字母
keyDown("CapsLock")
keyDown("t")
keyUp("t")
keyUp("CapsLock")
                    --以下为输入数字
keyDown("1")
keyUp("1")
                    --以下为输入符号
keyDown("LeftShift")
keyDown("1")
keyUp("1")
keyUp("LeftShift")

注意事项：

1. 当 inputText 函数在某些输入框内无效时可尝试使用此函数输入字符。
2. 每个keyDown都对应一个keyUP，单独使用keyDown有可能发生一些不可预料的问题。

应用相关

函数：runApp、closeApp 运行、关闭应用

函数名称：运行、关闭应用

函数功能：打开或关闭一个应用程序。

函数方法

flag = runApp(文本型 bid,文本型 class);
返回值：启动状态 整数型
closeApp(文本型 bid, 整数型 type);
返回值：无

脚本实例：
打开 iOS 内置天气应用，然后退出

r = runApp("com.apple.weather");    --启动天气应用 
mSleep(10 * 1000);
if r == 0 then
    closeApp("com.apple.weather");  --退出天气应用，使用此函数后在后台仍可看到应用程序图标属正常现象，实际进程已不在后台
else
    dialog("启动失败",3);
end

关闭 iOS 所有后台应用

closeApp("*",1)--关闭所有后台应用（2.3.5以上版本有效）

注意事项：

1. runApp函数需要系统响应时间较长，注意做好延迟或判断。
2. iOS 系统使用 closeApp 函数后在后台仍可看到应用程序图标属正常现象，实际进程已不在后台。
3. 参数 type 仅在引擎版本 iOS v2.3.5 以上版本有效（参数 type 为1时为模拟双击 Home 键，向上滑动退出应用的效果）。
4. 关于 Bundle ID 和包名的获取方法，参见"初始化"一章。
5. 安卓应用类名自行百度，游戏不可以通过类名直接启动指定页面，不是所有应用都可以通过此方法启动指定页面。
6. 请注意，部分手机不支持通过类名跳转指定页面。

函数：isFrontApp 判断前台应用

函数名称：判断前台应用

函数功能：根据应用的 Bundle ID 或包名判断应用是否处于前台。

函数方法

flag = isFrontApp(文本型 bid);
返回值：整数型 flag

脚本实例：
监听应用状态

isfront = 1;
while isfront == 1 do                           --如果应用处于前台则继续
    mSleep(3000);                               --此处放置代码块
    isfront = isFrontApp("com.tencent.mqq");    --更新前台状态
end

注意事项：

1. Bundle ID 的获取方法参见"初始化"一章。

函数：frontAppBid 获取前台应用

函数名称：获取前台应用

函数功能：获取前台应用的 Bundle ID 或包名。

函数方法

bid = frontAppBid();
返回值：文本型 bid

脚本实例：
iOS 系统获取前台应用并初始化

bid = frontAppBid(); 
init(bid,0);
--亦可写作
init(0);