Distribution

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

Corona

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

Corona Native

The Corona 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

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:

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.

metadata.lua

For native/hybrid plugins, the per-platformmetadata.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.

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.

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.

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.

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 Corona 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 Corona 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 2018.3326 or later, you should use 2018.3326 for ${VERSION} per the directory structures shown above. Then, in your documentation or elsewhere, you would tell developers to install Corona version 2018.3326 or later to access the plugin.

When you build your plugin binary, you should use the corresponding version of Corona 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 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. 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 Corona 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 Corona 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 Corona.