Plugin Submission Guide

This guide is for third party plugin developers who are ready to submit a plugin to the Solar2D Free Plugin directory at plugins.solar2d.com. Alternatively, you may submit it to the Solar2D Plugins Marketplace, please see the Asset Packaging Guidelines.

If you are new to the concept of plugins and how to create them, please see our Plugins guide.

Distribution

Plugins are distributed differently depending on the product for which it will be used.

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).

Packaging for Submission

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 — Core information about your plugin; see metadata.json below.
  • plugins/ 
    • ${VERSION}/ — Build version, for example 2022.3683; see Version Targeting below.
      • android/ 
        • .jar or .so binary.
        • metadata.lua — See metadata.lua below.
        • resources/ 
          • package.txt — Contains the name of the package for which to generate a R file.
          • assets/ — This folder contains files to be added to the assets folder and can be retrieved via the assets manager.
          • res/ — This folder contains files you want to put in the res folder and can be accessed via getIdentifier or by accessing the R file of the package under package.txt. The structure of the subfolder is exactly the same as the res folder.
      • iphone/ 
        • .a binary (ARMv7).
        • metadata.lua — See metadata.lua below.
        • resources/ This folder will contain all the resources you want in the app. It is relative to the root app directory.
      • iphone-sim/ 
        • .a binary (i386).
        • metadata.lua — See metadata.lua below.
        • resources/ — This folder will contain all of the resources you want in the app. It's relative to the root app directory.
      • mac-sim/ 
        • .dylib binary or Lua plugin.
      • win32-sim/ 
        • .dll binary or Lua plugin.

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
Note

In regards to iOS frameworks, Corona automatically links to the following frameworks. If you need to link against additional frameworks, you can specify them as either required inside the frameworks table or optional (weak linking) inside the frameworksOptional table. When you specify them, please omit the .framework extension.

  • AddressBook
  • AddressBookUI
  • AssetsLibrary
  • AudioToolbox
  • AVFoundation
  • CFNetwork
  • CoreGraphics
  • CoreLocation
  • CoreMedia
  • CoreMotion
  • Foundation
  • GameKit
  • iAd
  • ImageIO
  • MapKit
  • MediaPlayer
  • MessageUI
  • MobileCoreServices
  • OpenAL
  • OpenGLES
  • Photos
  • QuartzCore
  • Security
  • StoreKit
  • SystemConfiguration
  • UIKit

Additionally, for backward compatibility, Corona weak links against the Accounts, AdSupport, Social, and Twitter frameworks.

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.

  • plugins/ 
    • ${VERSION}/ — Build version, for example 2022.3683; see Version Targeting below.
      • android/ 
        • resources/ 
          • assets/ — This folder contains files to be added to the assets folder and can be retrieved via the assets manager.

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.

  • plugins/ 
    • ${VERSION}/ — Build version, for example 2022.3683; see Version Targeting below.
      • android/ 
        • resources/ 
          • res/ — This folder contains files you want to put in the res folder and can be accessed via getIdentifier or by accessing the R file of the package under package.txt. The structure of the subfolder is exactly the same as the res folder.

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.

  • plugins/ 
    • ${VERSION}/ — Build version, for example 2022.3683; see Version Targeting below.
      • iphone/ 
        • resources/ This folder will contain all the resources you want in the app. It is relative to the root app directory.
      • iphone-sim/ 
        • resources/ — This folder will contain all of the resources you want in the app. It's relative to the root app directory.

Version Targeting

When a plugin is published to Corona's servers, you must specify a minimum build version of Solar2D for the plugin you're deploying. This build version controls the availability of your plugin — specifically, developers will need to use that version (or later) of Solar2D in order to use the plugin for a device build and, if available, within the Corona Simulator.

For example, if you want your plugin to be supported in build 2022.3683 or later, you should use 2022.3683 for ${VERSION} per the directory structures shown above. Then, in your documentation or elsewhere, you would tell developers to install Solar2D version 2022.3683 or later to access the plugin.

When you build your plugin binary, you should use the corresponding version of Solar2D Native.

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.

FAQ

Do I need to create plugins for platforms that are not yet supported, such as Windows and macOS?

At a minimum, you will need to supply a Lua plugin stub for all platforms, including versions for Windows and macOS. These stubs should allow Solar2D developers to make calls as they would on a fully-supported platform. A sample Lua stub can be found here.

I have uploaded a plugin for a specific platform. Where do I add plugins for the additional platforms?

Under the build version of the plugin folder, you should supply your plugin implementations within the folders named android, iphone, iphone-sim, mac-sim, and win32-sim.

How do I produce .dll and .dylib files for the Corona Simulator?

If the plugin does not have an implementation for Windows or macOS, we recommend creating Lua stub files (see above).

If you wish to provide Simulator plugin implementations, you will need to use Visual Studio (Windows) or Xcode (macOS). Some useful guidelines can be found here:

Why is there both an iphone and iphone-sim folder?

When you submit a plugin, two versions should be submitted. The iphone folder should contain the ARMv7 plugin and the iphone-sim folder should contain the i386 plugin. This ensures that there is a plugin available for both the iOS Simulator and physical devices.

Which version of the Android NDK should I be using for native library (.so) plugin creation?

The native library (.so) plugin should be built with the Android NDK labeled android-ndk-r10d.

How can I test my plugin?

The plugin can be tested using Solar2D Native by linking the static library (iOS) or through including the library in your project's libs directory (Android). After initial testing, you will need to submit the binaries to Corona Labs to test with Solar2D.