Plugin Submission Guide

Solar2D

Your plugins will be hosted live on Corona's build servers, immediately available to all Solar2D developers. When a Solar2D developer creates a project that requires your plugin, the build server automatically integrates the plugin during the build process.

Solar2D Native

The Solar2D Native developer will have to include the plugin in the native project. Depending on the target platform, this can take several forms: a static library (iOS), a shared library (macOS/Windows/Android), or a .jar file (Android).

Pure Lua

If you have a plugin written in pure Lua (Lua code only), please see the Creating Lua Plugins.

Native / Hybrid

If your plugin is written in native code or hybrid native+Lua, it should be submitted via a Bitbucket repo that has been shared with you (the structure of that repo must follow a particular format). Once you have an update for your repo, you can generate a pull request.

To help you get started, we have created a plugin submission template that contains starter files, with the exception of the plugins binary directory. Essentially, you should package up your native/hybrid plugin files with the following structure:

metadata.json

This JSON file contains information about the publisher, the name of the plugin as it appears in Lua, and other related information, for example:

{
    "contact": "me@mycompany.com",
    "url": "http://www.mycompany.com",
    "pluginName": "plugin.mylibrary",
    "publisherId": "com.mycompany"
}

metadata.lua

For native/hybrid plugins, the per-platform metadata.lua file describes properties of the plugin binary. This file is required for Android, iOS, and the iOS Simulator.

• For Android, you need to specify the format of the binary. Currently, .jar and .so are supported. In addition, you can specify elements in the AndroidManifest.xml file that need to be modified in order to accommodate the plugin.

• For iOS and the iOS Simulator, the metadata.lua files should be the same. In both, you specify the format of the binary. Currently, only static libraries (.a) are supported.

• You can declare dependencies through the coronaManifest section. These plugins will be downloaded and bundled with your own during a Corona Simulator build.

• The plugin submission template provides stub versions. Here are some examples:

-- Android
local metadata =
{
    plugin =
    {
        format = "jar",
        manifest = 
        {
            permissions = {},
            usesPermissions =
            {
                "android.permission.INTERNET",
                "android.permission.ACCESS_NETWORK_STATE",
                "android.permission.READ_PHONE_STATE",
            },
            usesFeatures = {},
            applicationChildElements =
            {
                -- Array of strings
                [[
                    <activity android:name="com.mycompany.MyActivity"
                    android:configChanges="keyboard|keyboardHidden"/>
                ]],
            },
        },
    },
    coronaManifest = {
        dependencies = {
            ["shared.memoryBitmap"] = "com.coronalabs",
        },
    },
}

return metadata

-- iOS / iOS Simulator
local metadata =
{
    plugin =
    {
        format = "staticLibrary",

        -- This is the name without the "lib" prefix
        -- In this case, the static library is called "libplugin_openudid.a"
        staticLibs = { "plugin_openudid", },

        frameworks = {},
        frameworksOptional = {},
    },
    coronaManifest = {
        dependencies = {
            ["shared.memoryBitmap"] = "com.coronalabs",
        },
    },
}

return metadata

Android Resources

For Android, resources can be included into the assets or the res directory in the resulting .apk after a build.

To package resources into the assets directory, put the resources into the assets folder indicated below. The directory structure will be persist through the build process.

To package resources into the res directory, put the resources into the res folder indicated below. This res folder can contain subfolders which are the same folders as a native Android build, for example drawable, layout, etc.

iOS Resources

To include resources in the .app bundle, put them into the resources folder indicated below. These resources will be added to the bundle relative to the base directory. For example, if you put example.png into the resources folder, it will be included like example.app/example.png.

Choosing a Version

For new plugins, we highly recommend that you support the most recent public release. This ensures that your plugin is available to the broadest audience possible.

Multiple Versions

Normally, when you update a plugin binary, you simply re-submit the plugin. However, there may be occasions when a newer version of the plugin breaks backwards compatibility, or your updated plugin relies on new functionality available in a more recent Solar2D build.

In this situation, you should deploy a separate plugin binary. This binary will correspond to a different/newer build version of Solar2D. A developer can then simply obtain that version to access the newer version of the plugin. In this manner, you can keep the legacy plugin binary around to preserve backwards compatibility.