This guide outlines how to create a Lua plugin and package it for submission to the Solar2D Plugins Marketplace.
If you are new to the concept of plugins and how to create them, please see our Plugins guide.
In simple terms, a Lua plugin is nothing more than a module or series of modules that provide the end user with a set of methods (functions) and properties (variables) that can be called to execute the code you're providing. However, instead of sharing the code publicly via GitHub, your own website, or similar, you can deploy your Lua modules in a binary form and effectively protect your Intellectual Property (IP).
As the foundation for this guide, please use our project template which contains the basic required files. You can either download it as a .zip file and unzip it, or you can use the GitHub application and clone it to your system.
To create a new Lua plugin, we have provided helper scripts which perform the necessary file renaming and string replacements for both macOS and Windows:
In the Terminal application (~/Applications/Utilities/Terminal), run the create_project.sh script, first changing directory (cd) to the project template folder, then specifying the path to the new project folder along with the plugin name in place of PLUGIN_NAME:
cd /path/to/template/ ./create_project.sh /path/to/new/project/ PLUGIN_NAME
From the Command Prompt, run the create_project.bat script, first changing directory (cd) to the project template folder, then specifying the path to the new project folder along with the plugin name in place of PLUGIN_NAME:
cd \path\to\template\ create_project.bat \path\to\new\project\ PLUGIN_NAME
Assuming you successfully executed the script as outlined above, your new plugin folder should contain the following file and folder hierarchy:
bin/ — Core binaries required by the build process.build.bat — Script which compiles and packages the plugin for distribution using Windows.build.sh — Script which compiles and packages the plugin for distribution using a Mac.lua/
build.settings config.lua main.lua plugin/
PLUGIN_NAME/
defaults.lua — Example helper file for PLUGIN_NAME.lua.PLUGIN_NAME.lua — This is a sample library implementation which saves/loads a table using JSON.metadata.json — See Modifying the Plugin as follows.There are some essential parts of the project folder that you must modify:
First, edit the metadata.json file which contains information about your plugin. The base (unmodified) file looks like this:
{
"contact": "PUBLISHER_CONTACT@PUBLISHER_URL",
"url": "http://PUBLISHER_URL",
"pluginName": "plugin.myLuaPlugin",
"publisherId": "REVERSE_PUBLISHER_URL"
}
To customize your plugin, you'll need to edit the following aspects:
| Key | Value |
|---|---|
"contact" |
In place of PUBLISHER_CONTACT@PUBLISHER_URL, specify your contact email address. |
"url" |
In place of http://PUBLISHER_URL, specify your website URL. |
"pluginName" |
In place of plugin.myLuaPlugin, indicate a suitable name for your plugin. This will be the name which Corona developers use to include the plugin within their project's build.settings and require() it within their project code. |
"publisherId" |
In place of REVERSE_PUBLISHER_URL, specify a publisher URL in com.mydomain. |
Next, open up the lua folder. The three files build.settings, config.lua, and main.lua are your test harness files. In these files, you should provide the necessary code which behaves like a sample app and facilitates testing of the plugin code — in other words, these files will allow end users to "run" the plugin code outlined in the following section.
Inside the lua folder is another folder called plugin. This is where you should include the actual plugin code. As outlined in Creating a Plugin above, there will be a Lua file with the name of your plugin, for example myLuaPlugin.lua,
Essentially, your Lua plugin should be created using the CoronaLibrary class. Here's how a plugin called plugin.myLuaPlugin might look:
-- 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
It's very important that you update the Library:new{} command using the same information that you used for the plugin metadata.json file, in this case both the name key and publisherId key:
-- Create library
local Library = require( "CoronaLibrary" )
local lib = Library:new{ name = "plugin.myLuaPlugin", publisherId = "com.mydomain" }
The lua/plugin folder also contains an additional folder named according to your plugin, for instance myLuaPlugin. This folder contains a file named defaults.lua, but this file isn't necessarily required — it's merely an example used by the project template. Essentially, this folder can contain various Lua files of your choosing, for instance "support" modules that are require()-dmyLuaPlugin.lua file.
The following steps apply regardless of which marketplace you choose to submit your plugin to.
Using the main.lua file in the lua folder, you should build a basic sample app which exhibits the plugin and its features in action. Within that main.lua file, load the plugin just like you would any other Lua module:
local myLuaPlugin = require( "plugin.myLuaPlugin" )
Because the plugin code is in the plugin folder, your plugin will be accessible in the same manner as native Solar2D plugins.
Finally, you should ensure that your code executes on both iOS and Android devices, since Lua plugins are intended to be
You should prepare clear and complete documentation for your plugin so that users understand exactly how to use it. You can host this documentation on your own website, on GitHub, etc. In addition, you should offer users a basic sample project to easily test your plugin. This project can be shared/distributed via whatever method is best for you.
Before submitting your plugin, you should package it, following a specific structure. Corona Labs offers scripts which perform this process for you:
In the Terminal application, run the build.sh script, first changing directory (cd) to the plugin's folder:
cd /path/to/new/project/ ./build.sh
From the Command Prompt, run the build.bat script, first changing directory (cd) to the plugin's folder:
cd \path\to\new\project\ build.bat
This process converts your code into bytecode and prepares it for submission to a plugins host. When complete, you will see a plugin-PLUGIN_NAME.zip
If you'd like to submit a plugin for availability in the Solar2D Plugins Marketplace, refer to the Solar2D Plugins Marketplace Asset Packaging Guidelines for additional steps.