Plugin Submission Guide

Corona SDK

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

Corona Enterprise

The Corona Enterprise 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).

Directory Structure

You should package up your files in 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"
}

The plugin submission template contains a metadata.json file that should be updated with the appropriate information.

metadata.lua

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:

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

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

Creating Documentation

In order for your plugin to be used successfully, you should provide complete and accurate documentation. Plugin documentation must be written in Markdown (.markdown or .md extension). For the most part, Corona documentation follows standard Markdown syntax, however the formatting of links must be modified slightly to accommodate proper relative linking within your documentation structure.

As a starting point, we recommend using our Plugin Docs Template.

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.

To generate a custom R file for your plugin, you must include a package.txt file inside the android folder as indicated below. This file should contain the package name for the R file.

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 daily build of Corona.

In this situation, you should deploy a separate plugin binary. This binary will correspond to a different/newer build version of Corona SDK. 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.

For example, here's what your plugins directory might look like: