Plugins

Solar2D

Plugins for Solar2D are hosted in a number of places. Many are available at Free Plugins Directory, Solar2D Marketplace, and Solar2D Plugins Marketplace. You can incorporate a plugin by adding an entry to the plugins table of build.settings, for example:

settings =
{
    plugins =
    {
        ["plugin.myPlugin"] =
        {
            publisherId = "com.domainname"
        },
    },
}

Each plugin host will provide specific build.settings for the individual plugin.

When added in this manner, Solar2D will integrate the plugin during the build phase.

From there, the plugin can be loaded using the standard Lua require() function, for instance:

local myPlugin = require( "plugin.myPlugin" )

Solar2D Native

Native plugins can easily be added to your iOS or Android project.

On iOS, plugins will be in the form of static library (.a) files that need to be linked into your app executable.

On Android, plugins can come in the form of .so (shared library), .jar or .aar files.

iOS

In the ios folder, there are two Xcode projects:

1. App.xcodeproj — This is the project that builds the .app executable which runs on the device. It automatically builds the plugin as an implicit dependency.

2. Plugin.xcodeproj — For plugin development, you should modify this project. It builds the plugin as a static library (.a) and you can use this project directly if you want to share your plugin outside of the App project.

lipo -create "/path/to/iphoneos/staticlibrary.a" "/path/to/iphoneos-simulator/staticlibrary.a" -output "/path/to/dst/staticlibrary.a"

Android

In the android folder, the contents include:

1. app — This module builds the .apk that installs on the device. The app module automatically builds the plugin as an explicit dependency per this entry in the dependencies block of the build.gradle script for the app module (compile project(':plugin')).

2. plugin — This module builds the plugin as a .jar file, only including the Java files under plugin/src/main/java in your project. You can use this project directly if you want to share your plugin outside of the App project.

Pure Lua

A Lua library plugin can be created using the CoronaLibrary class. Please see the Creating Lua Plugins guide for details on how to create, package, and submit a Lua plugin to the available marketplaces.

Native C

In addition to the plugin naming conventions discussed above, Solar2D expects plugins to follow some additional conventions that ensure Lua can locate these modules. In C, these conventions are just the standard Lua naming conventions for modules:

• The name of the module function must be prefixed by luaopen_.
• The signature of this function should match lua_CFunction.
• If a module contains a dot (.), it is replaced by an underscore (_) in the name of the function, since C does not allow dots in symbol names.
• This function should be publicly visible.

For example, the Lua library plugin.myLibrary would have a Lua function called luaopen_plugin_myLibrary:

static int doSomething( lua_State *L )
{
    lua_getglobal( L, "print" );
    lua_pushstring( "I did something!" );
    CoronaLuaDoCall( L, 1, 0 );
    return 0;
}

// Export so it's visible to "require()"
CORONA_EXPORT
int luaopen_plugin_myLibrary( lua_State *L )
{
    static const luaL_Reg kFunctions[] =
    {
        { "doSomething", doSomething },

        { NULL, NULL }
    };

    // Create "myLibrary"
    // Lua version assumes version and revision default to 1
    int result = CoronaLibraryNew(
        L, "myLibrary", "com.mycompany", 1, 1, kFunctions, NULL );

    return result;
}

Native Java

If you write the module in Java, Corona has set up Lua to load Java code and to let that Java code define the Lua library via JNLua. Here, Lua looks for the Java class LuaLoader and instantiates it.

Solar2D assumes the following conventions:

• The LuaLoader class has a default (empty) constructor.
• The LuaLoader class must implement the JNLua interface com.naef.jnlua.JavaFunction.
• The namespace of LuaLoader should be the same as the name passed to require().

For example, the Lua library plugin.myLibrary would be implemented by the (fully-qualified) class plugin.myLibrary.LuaLoader and that class would implement the invoke() method of the com.naef.jnlua.JavaFunction interface.

Lua + Native

You can also create plugins in a hybrid fashion. For example, you can create the library via Lua code and then do further initialization in C.

Below is an example for creating the myLibrary library from Lua and then adding additional functions on the native C side. Here, we assume kBuffer stores the Lua bytecodes corresponding to myLibrary.lua.

// The bytecodes for "myLibrary.lua" are contained in kBuffer
static const unsigned char kBuffer[] = { ... }

static int bufferLoader( lua_State *L )
{
    return luaL_loadbuffer( L, (const char*)kBuffer, sizeof( kBuffer ), "myLibrary" );
}

static int somethingElse( lua_State *L )
{
    printf( "I'm doing something else!" );
    return 0;
}

CORONA_EXPORT
int luaopen_myLibrary( lua_State *L )
{
    lua_CFunction factory = Corona::Lua::Open< bufferLoader >;
    int result = CoronaLibraryNewWithFactory( L, factory, NULL, NULL );

    if ( result )
    {
        const luaL_Reg kFunctions[] =
        {
            { "somethingElse", somethingElse },

            { NULL, NULL }
        };

        luaL_register( L, NULL, kFunctions );
    }

    return result;
}