触动精灵脚本开发手册

已不更新，最新版本查看：https://helpdoc.touchsprite.com/dev_docs/598.html
开发手册 触动精灵

Windows 平台按 Ctrl + F 打开快捷搜索

Mac 平台按 command + F 打开快捷搜索

※右侧文本列表可以找到全部手册

目录

前言

       触动精灵是一款模拟手机触摸、按键操作的软件。通过制作脚本,可以让触动精灵代替双手,自动执行一系列触摸、按键操作。触动精灵简单、易用，不需要掌握任何编程知识就可以录制出功能强大的脚本；还可以使用编程知识，编写出功能更为复杂，交互更为灵活的脚本；只要能够在手机上完成的人为操作，触动精灵都可以代替完成，不仅省力，而且高效。

       触动精灵采用 Lua 脚本语言作为底层语言，支持 Lua 5.2.3 版本的所有语法与基本函数，并在其的基础上添加了一些扩展函数，用于取色、找色、找图、发送触摸事件等高级功能的实现。

用户在阅读本函数说明前，请参考 Lua 的官方手册以及相关资料，学习以下基本语法：

        - 注释
        - 变量与类型
        - 运算符
        - 条件、循环控制
        - 函数定义
        - 库函数
        - ……

       本说明仅供初等文化水平以上的、了解计算机编程基本原理的个体学习与参考，并不适用于零基础的编程入门者学习编程基本知识。严禁用于商业以及非法目的，严禁转载、抄袭、未经许可地引用。
为了便于解释和描述，本说明中采用了一些非专业的描述与形容方法（如：number），敬请理解。因编写校对仓促，如有错误欢迎及时指正，本文中的示例仅供函数参考，不要直接用于脚本中。

重要提示：
Lua 官方手册：http:/http://manual.luaer.cn/
Lua 中文开发手册：http://book.luaer.cn/
Lua 基础简明教程：https://zybuluo.com/lisaisacat/note/636399
触动精灵的脚本开发、存储过程必须使用 UTF-8 文本编码，如果您出现脚本中文无法正常显示与处理，请在您使用的编辑器或 IDE 中设置文本编码为 UTF-8，谢谢。

学习前的准备

越狱及 root 常识

• 在学习脚本开发之前，首先要具备一些关于 iOS 越狱和安卓 root 的知识，以及触动精灵的常用信息
• 文档链接：https://www.zybuluo.com/lisaisacat/note/324664
• 看了上面的文档，你可以具备以下知识：
  
  • 什么样的手机适合用来做脚本开发
  • 拿到一台越狱手机之后应该做什么才能避免白苹果和报错
  • Cydia 不见了或者已安装界面空白该怎么办
  • 为什么安装插件总是报错呢

Lua 基础简明教程

• 首先你需要了解 Lua 这门语言的一些基础知识，什么是循环，什么是函数，布尔型和数值型分别是什么意思，才有可能看得懂下面的教程和手册。
• 文档地址：https://www.zybuluo.com/lisaisacat/note/636399

脚本开发取色技巧

• 新手在学习使用触动精灵开发脚本的时候，总会进入一些误区，或者会有一些迷惑的点，觉得无从下手，本文总结了一些自己在学习过程中遇到的问题和经验技巧，欢迎大家一起交流分享。
• 文档链接：https://zybuluo.com/lisaisacat/note/508345
• 看了上面的文档，你可以具备以下知识：
  
  • 透明背景图、动图、带动画的界面应该怎么取色
  • 找色和找图哪个更好用
  • 函数封装是什么
  • 脚本报错了怎么办

小白学触动零基础视频教程

• 如果你没有任何编程基础，可以先看一下零基础教学视频：https://www.zybuluo.com/lisaisacat/note/585252
• 看了上面的文档，你可以具备以下知识：
  
  • deb 插件安装方法
  • 平刷插件 Cydia Eraser
  • SSH 命令工具 putty
  • 触动精灵的安装使用及常识
  • 抓色器和编辑器的使用及常识
  • 同样的脚本为什么有的手机运行异常
  • showUI 返回值的调用
  • showUI 应该怎么写才简洁好用
  • 大漠字库工具的用法

触动精灵开发者指南

• 由于触动精灵在线文档数量较多，很多人不知道如何查询，现建立此文档做为索引，其中会补充一些软件使用的常用信息。
• 触动精灵旗下目前有四款软件：触动精灵（iOS/Android）、帮你玩商城（iOS/Android）、小精灵（iOS/Android）、企业版（iOS/Android）。
  
  • 触动精灵适合开发者和有中控开发能力的工作室使用
  • 小精灵适合有图标和包名自定义需求的开发者和工作室使用
  • 企业版适合有批量控制设备需求的工作室使用
• 文档地址：https://www.zybuluo.com/miniknife/note/509515

触动产品功能对比

安卓小精灵有免费版，但不能使用网络模块和高级函数库
安卓企业版测试期收费：0.1 元/台/年

如何查看更多文档

在文档右侧栏顶部点击文档分类菜单栏按钮，即可查看触动精灵所有在线文档。

脚本开发相关工具

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

触动精灵 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

触动精灵 Android

使用教程：https://www.zybuluo.com/miniknife/note/443534
下载地址：http://www.touchsprite.com/touchsprite
脚本存放路径：/sdcard/TouchSprite/lua
默认资源路径：/sdcard/TouchSprite/res
脚本日志路径：/sdcard/TouchSprite/log
配置文件路径：/sdcard/TouchSprite/config
iOS插件文件路径：/sdcard/TouchSprite/plugin
Android插件文件路径：data/data/com.touchsprite.android/files/plugin

※安卓不同机型路径有差别，请用userPath函数获取路径

注意事项

• 有些函数不支持低版本触动精灵，请仔细阅读函数说明并尽量保持触动精灵客户端为最新版。
• 测试版为不稳定版本，为避免不必要的麻烦，请勿大规模安装。
• 测试版和正式版的 Bundle ID 不同，不能跨源覆盖安装或直接升级，请卸载之后再安装另一个源的版本。
• iOS 11 系统的设备，原 TouchSprite 文件夹下新增 plugin_ios11 快捷方式，连接到 usr/bin/tsplugin
• 如果系统是 iOS 11 则 tsp 自带 so 文件释放到该路径但 lua 文件释放路径保持不变
• 如果开发者想要手动导入 so 文件，也需要放到 usr/bin/tsplugin 目录下

脚本编辑器：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#编辑器与抓色器的使用

已兼容的模拟器

雷电模拟器、猩猩模拟器、网易MUMU模拟器、夜神模拟器、海马玩模拟器、逍遥模拟器、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, 200, 10 do   --使用 for 循环从起始点连续横向移动到终止点
    touchMove(150 + i, 550); 
    mSleep(10);     --延迟
end
touchUp(150 + 200, 550);    --在坐标 (350, 550) 抬起

精准滑动
方法一：

--精准滑动的原理就是通过向滑动方向的垂直线方向移动 1 像素来终止滑动惯性
--简单的垂直精准滑动
touchDown(200,1000)
for i = 0, 500, 50 do
    touchMove(200, 1000-i)
    mSleep(10)
end
--只要横向滑动 1 像素就可以精准滑动
--横向滑动 1 像素
touchUp(201, 500) 
mSleep(10)

方法二：

--使用 v1.2.7 版本 TSLib 新增的 touch() 函数进行滑动
require("TSLib")
touch():Step(50):on(200,1000):move(200,500):off()
--减少步长也可以进行精准滑动

多点触控

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)
    touchMove(x, y) -- 安卓部分机型单点不生效的情况下可以加上此句
    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)

安卓点击滑动失效处理方法

在部分安卓应用程序中的 HTML5 页面中，出现脚本能够点击，但点击没有后续反应的问题。此问题目前可以通过以下写法来解决：
os.execute("input mouse tap x y")，其中 x,y 为坐标值
os.execute("input mouse swipe x1 y1 x2 y2")--滑动，x1,y1 为滑动初始坐标，x2,y2 为滑动结束坐标
如果以上命令还是不生效可以用下面的 API 方法代替 mouse 进行尝试：
keyboard
joystick
touchnavigation
touchpad
trackball
stylus
dpad
touchscreen
gamepad
举例： os.execute("input keyboard tap 100 100")

注意事项：

1. 需要注意的是在使用 touchDown、touchMove、touchUp 函数时，中间一定要插入一定的延时，建议大于 20 毫秒，否则可能会出现点击无效等异常情况。
2. 使用滑动函数时，新手常犯的错误就是两点之间滑动距离过大，请注意touchDown、touchMove 的坐标间隔不宜超过 50 像素。
3. 非多点触控可省略手指 id
4. 新手使用点击、随机点击、直线或角度滑动等相关函数请参考函数扩展库

名词解析：

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

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

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

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

函数方法

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

脚本实例：

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

--获取多个点击坐标
dialog("一秒后接收用户三次点击", 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 引擎版本 iOS v2.2.4,Android v1.1.9 以上中可接收多个点击坐标并以 table 形式返回。

图色类及屏幕相关

函数：init 初始化

函数名称：初始化

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

函数方法

init(rotate);
返回值：无

脚本实例：

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

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

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

注意事项：

1. 安卓系统不同设备初始的截图方向有所不同，编写脚本前请用截图函数确认设备的默认方向。
2. 此函数可在脚本运行过程中多次调用以改变屏幕方向。
3. 如在脚本中未指定屏幕方向，系统将默认为竖屏或初始方向。
4. 安卓设备根据机型初始方向有区别，需要开发者自行调试，0 - 初始方向，1 - 初始方向向左旋转 90°，2 - 初始方向向右旋转 90°

参考资料：

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

函数：getScreenSize 获取屏幕分辨率

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

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

函数方法

width,height = getScreenSize();
返回值：number 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 snapshot
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 使用的多点模糊比色函数来实现精确判断：

zjing0910z88a

名词解析：

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.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);
返回值：number 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)

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

高阶用法：

多方向找色规则：
orient 不填或 orient = 0 表示包括基准点在内的所有参照点都必须在查找范围之内 ，orient = 1 - 8 表示使用 8 种不同的找色方向。
只要写了 orient 参数，那么找色方向就会根据 init() 设置方向旋转，一直保持以当前设置的屏幕方向左上角为初始点。

orient = 1，左上角到右下角，纵向开始找色，先找到 a 顶点。
orient = 2，左上角到右下角，横向开始找色，先找到 b 顶点。
orient = 3，右上角到左下角，横向开始找色，先找到 c 顶点。
以此类推。
完整演示代码、image、多点找色示例图：找色.zip33.6kB

多方向找色方法：

x,y = findMultiColorInRegionFuzzy( 0x000000, "0|0|0x000000", 95, x1, y1, x2, y2,  { orient = 1 })--支持版本：iOS 3.0.0-118,Android 2.3.5 以上

偏色用法：

--另外一种偏色模式，引擎版本 iOS v2.4.1，Andriod v2.3.5.4 以上支持
--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 } )--main 及 list 参数暂不支持 Android
dialog(x..","..y, 0)

注意事项：

1. posandcolor 参数中的坐标为相对坐标。
2. 多点找色的代码可直接用触动精灵取色工具生成，其使用方法参见图文教程。
3. 颜色值的十六进制文本中，其顺序为 RGB。
4. 相对于第一个点的坐标，即用这个点的横坐标、纵坐标分别减去第一个点的横坐标、纵坐标，可以为负数。
5. 使用此函数时精度参数设置过低，会导致性能大幅下降。
6. 引擎版本 iOS v2.4.5-9，v3.0.0-118 以上版本，如果 orient = 1 - 8 按方向进行查找，只要目标点在查找范围内，不需要基准点须在查找范围之内。
7. 引擎版本 Android v2.3.5 以上版本，如果 orient = 1 - 8 按方向进行查找，Android v2.3.5.4 以上版本支持 orient = 0。

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

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

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

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

函数方法

point = findMultiColorInRegionFuzzyExt(color, posandcolor, degree, x1, y1, x2, y2);

高阶用法

返回的 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，Andriod v2.3.5.4 以上支持
--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

多点方向用法：

x,y = findMultiColorInRegionFuzzyExt( 0x000000, "0|0|0x000000", 95, x1, y1, x2, y2,  { orient = 1 })

注意事项：

1. posandcolor 参数中的坐标为相对坐标。
2. 多点找色的代码可直接用触动精灵取色工具生成，其使用方法参见图文教程。
3. 颜色值的十六进制文本中，其顺序为 RGB。
4. 相对于第一个点的坐标，即用这个点的横坐标、纵坐标分别减去第一个点的横坐标、纵坐标，可以为负数。
5. 使用此函数时精度参数设置过低，会导致性能大幅下降。
6. 引擎版本 iOS v2.4.5-9，v3.0.0-118 以上版本，如果 orient = 1 - 8 按方向进行查找，只要目标点在查找范围内，不需要基准点须在查找范围之内。
7. 引擎版本 Andriod v2.3.5.4 以上版本，如果 orient = 0 - 8 按方向进行查找。

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

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

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

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

函数方法

x, y = findImage( picpath, x1, y1, x2, y2, alpha);
返回值：number 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 及 jpg 格式，不可以设置质量;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 v2.3.4,Android 2.2.6 以上

函数方法

flag = imageOperMerge(pictb, string path, number type, quality);

返回值：number 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 之前的目录使之自动获取。

开发辅助类

函数：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(string text, string cbtn, string btn1, string btn2, number time);

返回值：number choice

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

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

1. 选择性别（三选）

choice = dialogRet("请选择您的性别：", "取消", "男", "女", 0);
if choice == 0 then      --取消
    dialog("您放弃了选择",0);
    mSleep(1000);
elseif choice == 1 then  --男
    dialog("你好，帅哥",0);
    mSleep(1000);
elseif choice == 2 then  --女
    dialog("你好，美女",0);
    mSleep(1000);
end

1. 请阅读许可协议

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

注意事项：

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

函数：dialogInput 参数对话框

函数名称：参数对话框

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

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

函数方法

text_a,text_b = dialogInput(title,format, btn);

返回值： text_a, text_b

脚本实例：
1. 单编辑框 - 输入姓名

text_a = dialogInput("请输入您的姓名", "在这里输入姓名", "确认");
mSleep(1000);

1. 多编辑框 - 输入姓名和年龄

::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 函数跳转到代码的指定位置向下执行。该函数请谨慎使用，因为大量的跳转会造成代码编写的混乱。

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

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

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

函数方法

initLog(name, flag);
wLog(name, contents);
closeLog(name);
返回值：无

输出方式

0 - 生成 1 个后缀为 .log的 文件到 log 文件夹下
1 - 生成 1 个以时间戳命名的后缀为 .log 的文件到 log 文件夹下
2 - 异步发送到服务器（仅支持引擎 v1.7.0 及 Android v2.4.1 以上版本）
3 - 同步发送到服务器（仅支持引擎 v1.7.0 及 Android v2.4.1 以上版本）

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

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

2.发送服务器日志

initLog("192.168.1.1", 2);                  --初始化日志，并以异步方式发送；把 2 换成 3  即为同步发送
wLog("192.168.1.1", "[DATE] Test OK!!!");   --发送日志内容：当前时间 Test_1 OK!!! 到 192.168.1.1（控制端 IP 即电脑 IP）
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!!!");  -- test_1.log 中写入 当前时间 Test_1 OK!!!
mSleep(500);                           --间隔时间 500 毫秒
wLog("test_2","[DATE] Test_2 OK!!!");  -- test_2.log 中写入 当前时间 Test_2 OK!!!
closeLog("test_1");                    --关闭 test_1.log 日志
closeLog("test_2");                    --关闭 test_2.log 日志

注意事项

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

函数：sysLog 系统日志（仅支持 iOS10 以下系统）

函数名称：系统日志

函数功能：输出系统日志 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(string 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 函数解决。

文件操作

函数：unzip 解压（仅支持 Android）

函数名称：文件解压
函数功能：文件解压，解压压缩包
支持版本：仅 Android v2.3.5 及其以上版本支持
函数方法：
unzip(zipPath,filePath)

参数说明

脚本实例：

unzip(userPath() .. "/web.zip",userPath() .. "/res/")

函数：zip 压缩（仅支持 Android）

函数名称：文件压缩
函数功能：文件压缩
支持版本：仅 Android v2.3.5 及其以上版本支持
函数方法：
zip(zipPath,filePath)

参数说明

脚本实例：

zip("/mnt/sdcard/TouchSprite/web.zip","/mnt/sdcard/TouchSprite/web")

脚本控制

函数：mSleep 延时

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

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

函数方法

mSleep(numberinterval);
返回值：无

脚本实例：
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();     --否则退出脚本
    mSleep(10)
    mSleep(10)
    mSleep(10)      --lua的机制是调用此函数之后的下一行结束，如果不希望出现此情况可以在调用函数之后加入一行无意义代码。
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，则继续运行脚本
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

系统相关

函数：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")
    --iOS 设备连续输入建议加下延时时间，否则可能因为速度太快导致输入错误
    mSleep(20)
end
inputText("Welcome.#ENTER#"; --在输入框中输入字符串 "Welcome." 并回车；此函数在某些应用中无效，如支付宝、密码输入框等位置，甚至可能会导致目标应用闪退

注意事项：

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

函数：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();
返回值：string 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(state);
返回值：无

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

--iOS 6系统 和 iOS 7.1及以上系统
pressHomeKey(0);    --按下 Home 键
pressHomeKey(1);    --抬起 Home 键
--iOS 7 系统
pressHomeKey(0);    --按下抬起 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 键的操作。
3. 在 iOS 7.1及以上版本中和6系统一致，状态标识为 0 时，调用该函数则开始按下 Home 键并按住不放，直到状态标识为 1 时重新调用该函数，抬起 Home 键。

函数：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")

• 更多键盘码请参看→按键码表

命令： 安卓模拟物理按键（仅支持 Android）

注意事项：

1. 当 inputText 函数在某些输入框内无效时可尝试使用此函数输入字符。
2. 推荐使用键名，不同的手机的键值不同会导致此函数无效。。
3. 在安卓某些 HTML 页面，使用 inputText 函数输入无效，可尝试使用模拟物理按键。
   具体参数见→约定的按键编码。

实例：

os.execute("input keyevent 键名")
--按下 Home 键
os.execute("input keyevent KEYCODE_HOME")
--按下返回键
os.execute("input keyevent KEYCODE_BACK")
--按下回车键
os.execute("input keyevent KEYCODE_ENTER")
--按下菜单键
os.execute("input keyevent KEYCODE_MENU")
 --按下音量加键
os.execute("input keyevent KEYCODE_VOLUME_UP")
--按下音量减键
os.execute("input keyevent KEYCODE_VOLUME_DOWN")
--输入10086
os.execute("input text \"10086\"")   
--按拨号键打通
os.execute("input keyevent KEYCODE_CALL")