创建 Lua 插件

本指南概括了如何创建一个 Lua 插件以及如何为提交到Solar2D 插件市场对其进行打包。

如果您以前不了解插件的概念以及如何创建插件，请参阅我们的插件指南。

概述
创建插件
修改插件
插件代码
插件提交

概述

简单来说，Lua 插件只不过是模块或模块系列，为最终用户提供了一组可以被调用以执行您提供代码的方法（函数）和属性（变量）。但是，不必通过 GitHub、自己的网站或类似途径公开分享代码，您可以以二进制形式部署您的 Lua 模块，并切实保护您的知识产权（IP）。

创建插件

作为本指南的基础，请使用我们的项目模板，其中包含基本的必需文件。您既可以下载为.zip文件并将其解压，也可以使用 GitHub 应用程序并将它克隆到您的系统。

为了创建一个新的 Lua 插件，我们提供了帮助脚本，它们将执行对 macOS 和 Windows 都必要的重命名与字符串替换操作

在 Terminal 应用程序（~/Applications/Utilities/Terminal)中，运行create_project.sh脚本，首先将目录（cd）更改为项目模板文件夹，然后指定新项目文件夹的路径和插件名称，替代PLUGIN_NAME

cd /path/to/template/
./create_project.sh /path/to/new/project/ PLUGIN_NAME

在命令提示符中，运行create_project.bat脚本，首先将目录（cd）更改为项目模板文件夹，然后指定新项目文件夹的路径和插件名称，替代PLUGIN_NAME

cd \path\to\template\
create_project.bat \path\to\new\project\ PLUGIN_NAME

假定您已成功执行上面概述的脚本，那么您的新的插件文件夹应该包含以下文件和文件夹层次结构

bin/ — 构建过程所需的内核二进制文件。
build.bat — 使用 Windows 进行编译和打包插件进行分发的脚本。
build.sh — 使用 Mac 进行编译和打包插件进行分发的脚本。
lua/
- build.settings
- config.lua
- main.lua
- plugin/
  - PLUGIN_NAME/
    - defaults.lua — PLUGIN_NAME.lua的示例帮助文件。
  - PLUGIN_NAME.lua — 这是样本库实现，将使用 JSON 保存/加载表格。
metadata.json — 请参阅修改插件，如下。

修改插件

项目文件夹中有一些重要部分，您必须修改

metadata.json

首先，编辑metadata.json 文件，其中包含有关您的插件的信息。基本（未修改）文件的格式如下

{
    "contact": "PUBLISHER_CONTACT@PUBLISHER_URL",
    "url": "http://PUBLISHER_URL",
    "pluginName": "plugin.myLuaPlugin",
    "publisherId": "REVERSE_PUBLISHER_URL"
}

要自定义插件，您需要编辑以下方面

键	值
`"contact"`	代替`PUBLISHER_CONTACT@PUBLISHER_URL`，请指定您的联系电子邮件地址。
`"url"`	代替`http://PUBLISHER_URL`，请指定您的网站 URL。
`"pluginName"`	代替`plugin.myLuaPlugin`，请指出符合您插件名称的名称。这将是 Corona 开发人员使用该插件的名称，将该插件包含到他们项目的`build.settings`中，并在其项目代码中`require()`它。
`"publisherId"`	代替`REVERSE_PUBLISHER_URL`，请在反向域中指定发布者 URL格式，例如 `com.mydomain` 。

测试文件

接下来，打开 lua 文件夹。三个文件 build.settings、config.lua 和 main.lua 是您的测试架构文件。在这些文件中，您应当提供必要的代码，这些代码将表现得像示例应用并便于测试插件代码，换句话说，这些文件将允许终端用户“运行”下一节概述的插件代码。

插件代码

lua 文件夹中包含另一个名为 plugin 的文件夹。您应当将实际插件代码放在此文件夹中。如上面创建插件中概述的那样，将会有一个 Lua 文件，其名称为您的插件名称，例如 myLuaPlugin.lua，

从本质上讲，您应使用 CoronaLibrary 类创建 Lua 插件。以下是如何编写名为 plugin.myLuaPlugin 的插件

-- Create library
local Library = require( "CoronaLibrary" )
local lib = Library:new{ name = "plugin.myLuaPlugin", publisherId = "com.mydomain" }

-- Create a function for the library
lib.doSomething = function()
    print( "I did something!" )
end

-- Return "lib"
return lib

非常重要的是，您使用与用于插件 metadata.json 文件的相同信息更新 Library:new{} 命令，在此示例中即 name 键和 publisherId 键

-- Create library
local Library = require( "CoronaLibrary" )
local lib = Library:new{ name = "plugin.myLuaPlugin", publisherId = "com.mydomain" }

lua/plugin 文件夹还包含一个附加的 文件夹，其命名根据您的插件而定，例如 myLuaPlugin。此文件夹包含一个名为 defaults.lua 的文件，但不一定需要此文件，这仅仅是项目模板使用的示例。从本质上讲，此文件夹可以包含您选择的各种 Lua 文件，例如由 myLuaPlugin.lua 文件require()的“支持”模块。

插件提交

无论您将插件提交给哪个市场，以下步骤都适用。

设备测试

使用 lua 文件夹中的 main.lua 文件，您应构建展示插件及其实际功能的基本示例应用。在此 main.lua 文件内，加载插件就像加载任何其他 Lua 模块一样

local myLuaPlugin = require( "plugin.myLuaPlugin" )

由于插件代码位于 plugin 文件夹中，因此您的插件将以与原生 Solar2D 插件相同的方式访问。

最后，您应确保代码在 iOS 和 Android 设备上都执行，因为 Lua 插件旨在跨平台兼容。验证插件是否能够编译为设备，并了解低端设备上潜在的性能问题。

文档/示例

您应为插件撰写清晰而全面的文档，以便用户能够确切了解如何使用插件。您可以将此文档托管在您自己的网站、GitHub 等网站上。此外，您应为用户提供一个基本的示例项目以便轻松地测试您的插件。可以通过最适合您的方法共享/分发此项目。

插件打包

在提交您的插件之前，您应按照一个特定结构对其进行打包。Corona Labs 提供了执行此流程的脚本

在终端应用程序中，运行 build.sh 脚本，首先将目录更改 (cd) 为插件文件夹

cd /path/to/new/project/
./build.sh

在命令提示符处，运行 build.bat 脚本，首先将目录更改 (cd) 为插件文件夹

cd \path\to\new\project\
build.bat

此流程将转换您的代码为字节码并为提交到插件主机做准备。完成后，您将在项目目录中看到一个plugin-PLUGIN_NAME.zip文件。

提交

如果您希望将插件提交至 Solar2D 插件市场以供使用，请参阅 Solar2D 插件市场资产打包指南以了解其他步骤。