Corona Native — Android

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

Corona Native Setup

The following steps will help you set up your native development environment such that it's optimized for integration with Corona Native.

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

  2. Android development is done using the Java programming language, so you must install the Java Development Kit as outlined here.

  3. After installing Java, you should install and use Android Studio, the official IDE for Android development.

Project Templates

New projects can easily be created by using template files as a starting point. Inside the ~/Applications/Corona/Native/Project Template/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, 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 — For plugins, there are additional files and directories of interest:
      • build.gradle — This is the build script that creates the plugin. The output is a .jar file. The only files included in the .jar are those located in plugin/src/main/, whether they are code or resources.
      • 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  
                • — 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.
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/ — At launch time, 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/ — 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.

Corona 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 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 Corona 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 androidsigningConfigs 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.