XXTouch 脚本应用包 (XPP) 规范

XXTouch XXTouchApp

在 XXTouch 1.2 之前，我们采用 Lua 作为开发语言，采用 .lua 作为源代码，.xxt 作为编译加密后的可执行脚本。

然而，单一的源代码或可执行脚本，需要引用一些模块、配置和资源文件，往往不能独立发布，不便于打包、版本管理、资源调用。因此我们引入了 Bundle 包 XPP 的概念。

Bundle ( 包 )

Bundle ( 包 ) 是一种特定结构、特定扩展名的目录 ( 文件夹 ) ，这种结构允许将相关资源（例如可执行文件，本地化资源，图片等）组合在一起，成为在概念上独立的项目。

多数类型的 Bundle ( 包 ) 在使用时与常规文件类似，从而减少了其内部文件意外更改或丢失的风险。同时，Bundle ( 包 ) 的另一个意义在于可以使用文件夹简化组织资源的方式，避免使用资源分支导致的额外的复杂性。

XPP 格式

XPP ( 以下称作“脚本应用包” ) 是可以被 XXTouch 解析、查看与执行的一种 Bundle ( 包 ) 结构，以单一文件的形式出现在用户面前。这个“文件”实际上是一个以 .xpp 为扩展名的目录 ( 文件夹 ) ，其目录结构如下：

Info.lua

XXTouch 需要 Info.lua 返回一个用于描述当前脚本应用包元信息的 Lua 表常量。它不应该包含常量值以外的 Lua 代码

以下是一个典型的 Info.lua 示例：

return {
    BundleIdentifier = "com.yourcompany.yourscript";
    BundleVersion = "0.0.1";
    BundleName = "Your Name";
    BundleDisplayName = "\U4f60\U7684\U540d\U5b57";
    BundleIconFile = "appicon.png";
    Executable = "xui-script.lua";
    MainInterfaceFile = "xui-demo.xui";
    MinimumSystemVersion = "10.0";
    MaximumSystemVersion = "10.2";
    MinimumXXTVersion = "1.1.2";
    SupportedResolutions = {
        {
            width = 640;
            height = 1136;
        };
    };
    SupportedDeviceTypes = {
        "iPhone6,1";
    };
    PackageControl = {
        AuthorName = "i_82";
        AuthorEmail = "i.82@me.com";
        Description = "";
        Homepage = "https://82flex.com";
    };
};

Info.lua 返回的表通常包含以下键值对：

BundleIdentifier ( 包标识符 )

包标识符 用来精确、唯一地表示一个独立脚本应用包。当开发者创建了一个脚本应用包并设置了 包标识符 后，该应用的 包标识符 在其整个生命周期内不能被更改。

包标识符 字符串必须为通用类型标识符 ( UTI )，只允许包含数字与字母 ( A-Z, a-z, 0-9 )、短横线 ( - ) 和点 ( . )。该字符串通常应该以倒序 DNS 格式呈现。举个例子，如果开发者组织的域名为 82flex.com，并且该脚本应用包名称为 Hello，开发者应该以 com.82flex.hello 作为其 包标识符。

BundleVersion ( 脚本应用包的版本号 )

脚本应用包的版本号，用于表示脚本应用包副本每一次的更新迭代，其格式为：

1.1.0
主版本.副版本.发布号

这种定义虽然并不严格，但是值得注意的是，主版本、副版本、发布号均为整数，且它们之间以点分隔，其中，发布号可省略 ( 默认为 0 )：

1.1
主版本.副版本

在脚本应用包的生命周期中，每次发布版本号必须递增，其比较规则为：先比较主版本的数值，再比较副版本的数值，最后比较发布号的数值。

BundleName ( 短名称 )

短名称，该名称不应超过 16 个字符，也可用于在脚本中显示和读取，用于菜单、推送。

BundleDisplayName ( 显示名称 )

显示名称，该名称可以超过 16 个字符，仅用于显示在 XXTouch 应用程序中的脚本列表，不应该用于逻辑判断。

若不设置，则使用 BundleName ( 短名称 ) 的值。

BundleIconFile ( 图标文件 )

图标文件，指定用于显示在 XXTouch 应用程序中的脚本列表中的图标在脚本应用包中的相对位置，图标文件必须为 .png 格式，若图标名为 appicon.png，则需要提供以下图标：

若不设置，则显示默认图标。

Executable ( 可执行入口脚本文件 )

可执行入口脚本文件，指定直接运行将会执行的脚本文件在脚本应用包中的相对位置，必须为 .lua 或 .xxt 格式。

MainInterfaceFile ( 主界面配置入口文件 )

主界面配置入口文件，指定在 XXTouch 应用程序的脚本列表中选择配置脚本应用包时，将打开该 XUI 配置，必须为 .xui 格式。

若不设置，该 XPP 不显示配置按钮。

MinimumSystemVersion/MaximumSystemVersion ( 最低/最高 iOS 版本要求 )

最低/最高 iOS 版本要求，如不在该区间，则运行时提示不兼容的 iOS 版本。

在 XXTouch 脚本中获取当前系统版本：

ver = sys.version()

MinimumXXTVersion ( 最低 XXTouch 服务版本要求 )

最低 XXTouch 服务版本要求，如不满足最低版本，则运行时提示不兼容的 XXTouch 版本。

若不设置，则默认兼容所有 XXTouch v1.2-1 及以上所有版本。

在 XXTouch 脚本中获取当前 XXTouch 版本：

xver = sys.xtversion()

SupportedResolutions ( 支持的设备屏幕物理尺寸数组 )

支持的设备屏幕物理尺寸数组。如运行设备的屏幕尺寸不在该数组中，则运行时提示不兼容的设备屏幕尺寸。

若不设置，则默认兼容所有设备屏幕尺寸。

在 XXTouch 脚本中获取设备屏幕物理尺寸：

width, height = screen.size()

SupportedDeviceTypes ( 支持的设备类型数组 )

支持的设备类型数组。如运行设备的类型代号不在该数组中，则运行时提示不兼容的设备类型。

若不设置，则默认兼容所有的设备类型。

在 XXTouch 脚本中获取设备类型：

dtype = device.type()

PackageControl ( 附加信息 )

附加信息，字典。用于存放该脚本应用包的作者信息、发布者信息、发布时间、版权信息等等。支持的键值对有：

可执行脚本

界面配置

资源文件

多语言*