Solar2D Native — Android

The following resources go further in depth on using Solar2D Native for Android.

Solar2D Native Setup

Download and install Android Studio, the official IDE for Android development.

For macOS

Within the /Applications/Corona/Native/ folder, double click Setup Corona Native. This will create the symbolic link required for the project templates.

Project Templates

New projects can easily be created by using template files as a starting point. Project template can be found:

To start a new project, copy the App folder to desired location and rename it. Start Android Studio, click "Open an existing Android Studio Project", and select android directory from copied App template.

Note, that opening App/android from original template location with Android Studio is error prone: install location is often in system protected folder. Copy it to folder with write access.

Inside your copy of the App folder, the following files/directories are of primary concern:

  • Corona — This folder represents a classic Corona project, containing files like main.lua, app icons, etc. By default, build.gradle (Module: App) is set up to assume that these files reside inside this exact folder (Corona).
  • android — Contains all of the Android-specific code, projects, etc.
    • app  
      • build.gradle — This is the main build script and it's also where you set up some application settings like version and what SDK versions to use.
      • libs/ — This is where third-party (Corona) .jar plugins that your app relies upon should go.
      • src  
        • main  
          • AndroidManifest.xml — This is where you configure application settings such as name, permissions, etc.
          • java/ — This is where the Java source files for your app should go. Because the package is com.mycompany.app, this is where the files are located by default. You should modify this according to the package name you specify.
          • jniLibs/ — This is where third-party (Corona) .so plugins that your app relies upon should go.
    • plugin — This is the main folder when developing plugins for SOlar2D. All your code goes here. For plugins, there are additional files and directories of interest:
      • build.gradle — This is the build script that creates the plugin. The output is usually a .jar file. The only files included in the .jar are those located in plugin/src/main/, whether they are code or resources. In case you have additional resources to be added to the plugin (e.g., UI) that reside usually in the res directory (see below), an aar file will be generated (How to handle aar files please see Building for Self Hosted Plugins).
      • libs — This is where third-party (Corona) .jar plugins that your plugin relies upon should go.
      • src  
        • main  
          • AndroidManifest.xml — This is where you set up the plugin's package name.
          • java  
            • plugin  
              • library  
                • LuaLoader.java — This is the code for the Lua library plugin.library on the Android side.
          • jniLibs/ — This is where third-party (Corona) .so plugins that your plugin relies upon should go.
          • res/ — This is where your Android resources will be located (i.e., color, style, texts, and so forth). If there will be such resources remember to appy the plugin 'com.android.library' instead of 'com.android.appication' in your build.gradle.
Project Flow

The following steps briefly outline the flow of the /Applications/Corona/Native/Project Template/App/ project for Android:

  1. android/app/src/main/java/com/mycompany/app/CoronaApplication.java — At launch time, CoronaApplication.java is instantiated. It adds a private class to be notified of various app-level events like app suspend and resume. Right before main.lua is invoked, the onCreate() method is invoked. At this point, OpenGL is set up and all Corona frameworks are available.

  2. Corona/main.lua — In the Lua code, plugin.library is loaded via require(). The Corona engine will then look for a corresponding Java class called plugin.library.LuaLoader and invoke it. The name of this class is dynamic and is constructed using the original library name passed to require() as the package name for a LuaLoader class. The LuaLoader class is expected to implement the JNLua interface com.naef.jnlua.JavaFunction.

  3. android/plugin/src/main/java/plugin/library/LuaLoader.java — When the fully-qualified class path for LuaLoader is resolved, the class is instantiated with the default constructor. The invoke() method is then called by Lua via JNLua and does all the heavy lifting, for example creating the Lua library table, registering the Lua methods like show(), and then leaving the table at the top of the Lua stack.

Note that the LuaLoader class is instantiated once for the lifetime of the process, much like a .dll or .so file is typically loaded once for the lifetime of the process. Also note that the invoke() method is called once for each Lua state that does a require() — this corresponds to being called once each time the CoronaActivity is instantiated.

Solar2D Native Development

Bridging Lua/Java

To bridge Lua and Java code, you'll use functionality made available by JNLua. This allows you to add libraries and functions in Lua that call directly into Java.

Native APIs

The native APIs for Android are available as a JavaDoc.

Using ProGuard

Just remember to keep ProGuard from obfuscating your plugin.your-plugin-name.LuaLoader class by adding the line:

-keep public class plugin.your-plugin-name.LuaLoader { public *;}

to your proguard-rules.pro file within the plugin module.

Using Common Android Libraries

If you're developing a plugin that depends on the Android Support Libraries or Google Play Services, please read our Android Dependency Integration guide.

Runtime Permission Support

For information on working with Android Runtime Permissions in Android 6.0 or newer, please read our Android Runtime Permission Support guide.

Building for Devices

To build a Solar2D Native project from Android Studio, simply use the Run button on the top bar of icons. This will build your project, sign it, and prompt you to select a deployment target. The built .apk is signed with either a keystore you've specified in the android → signingConfigs block of the android/app/build.gradle script, or the default debug.keystore if none is provided.

Android Studio has several other build-related options that you can read about here.

Building for Self Hosted Plugins

Building the plugin-in to be published on a web server (since the plugin is not yet intended to be shared with the community), a few simple extra steps are required:

  1. Create a directory for packaging, for instance package-plugin. Create a folder named android within package-plugin.

  2. Create a new gradle file, called corona.gradle and copy all your dependencies and repository definitions from your plugin's build.gradle also into that file.

  3. Place the metadata.lua file also in the directory package-plugin

  4. Use a simple packaging script to copy the build result into this directory and to call the zip/tar program. On Mac you could use the following lines, for instance, placed into a shell script deploy.sh:

#!/bin/bash
cp ../../build/outputs/aar/plugin-release.aar .
COPYFILE_DISABLE=true tar -czf ../"$(basename "$(pwd)").tgz" --exclude='.[^/]*'  ./*
scp ../android.tgz "[email protected]:/var/www/YOUR_DOMAIN/plugins"

Finally, for those who will use your Self-Hosted-Plugin, they have to add the location (www.YOUR_DOMAIN.de/plugins/android.tgz) into their build.settings so that the build proccess for Corona-Apps can find the plugin.