Solar2D Native — Android

以下资源将更深入地介绍如何在 Android 上使用 Solar2D Native。

Solar2D Native 设置

下载并安装 Android Studio，Android 开发的官方 IDE。

适用于 macOS

在 /Applications/Corona/Native/ 文件夹中，双击 **Setup Corona Native**。这将创建项目模板所需的符号链接。

项目模板

可以使用模板文件作为起点轻松创建新项目。项目模板位于

要开始一个新项目，请将 App 文件夹复制到所需位置并重命名。启动 Android Studio，点击“打开现有 Android Studio 项目”，然后从复制的 App 模板中选择 android 目录。

请注意，打开App/android从原始模板位置使用 Android Studio 容易出错：安装位置通常在系统保护文件夹中。将其复制到具有写入权限的文件夹。

在 App 文件夹的副本中，以下文件/目录是主要关注点

  • Corona — 此文件夹代表一个经典的 Corona 项目，包含 main.lua、应用程序图标等文件。默认情况下，build.gradle (Module: App)设置为假设这些文件位于此确切文件夹 (Corona) 中。
  • android — 包含所有Android 特定的代码、项目等。
    • app  
      • build.gradle — 这是主要的构建脚本，您还可以在其中设置一些应用程序设置，例如版本和要使用的 SDK 版本。
      • libs/ — 这是放置第三方(Corona) 应用程序依赖的 .jar 插件的位置。
      • src  
        • main  
          • AndroidManifest.xml — 您可以在此处配置应用程序设置，例如名称、权限等。
          • java/ — 这是应用程序的 Java 源文件应放置的位置。由于包是 com.mycompany.app，因此默认情况下文件位于此处。您应该根据指定的包名称进行修改。
          • jniLibs/ — 这是放置第三方应用程序依赖的 (Corona) .so 插件的位置。
    • plugin - 这是开发 SOlar2D 插件时的主要文件夹。您所有的代码都在这里。对于插件，还有其他一些需要注意的文件和目录
      • build.gradle — 这是创建插件的构建脚本。输出通常是一个 .jar 文件。.jar 文件中只包含位于 plugin/src/main/ 中的文件，无论它们是代码还是资源。如果您有要添加到插件的额外资源（例如，UI），这些资源通常位于 res 目录中（见下文），则会生成一个 aar 文件（如何处理 aar 文件，请参阅构建自托管插件）。
      • libs — 这是放置插件依赖的 (Corona) .jar 插件的位置。第三方**插件** 依赖的 (Corona) .jar 插件应该放在这里。
      • src  
        • main  
          • AndroidManifest.xml — 您可以在此处设置插件的包名称。
          • java  
            • plugin  
              • library  
                • LuaLoader.java — 这是 Android 端 Lua 库 plugin.library 的代码。
          • jniLibs/ — 这是放置第三方**插件**依赖的(Corona) .so 插件应该放在这里。
          • res/ — 这是您的 Android 资源所在的位置（即颜色、样式、文本等等）。如果存在此类资源，请记住在您的 build.gradle 中应用插件 'com.android.library' 而不是 'com.android.appication'。
项目流程

以下步骤简要概述了/Applications/Corona/Native/Project Template/App/Android 项目的流程

  1. android/app/src/main/java/com/mycompany/app/CoronaApplication.java — 在启动时，会实例化 CoronaApplication.java。它添加了一个私有类，用于接收各种应用级事件的通知，例如应用暂停和恢复。在调用 main.lua 之前，会调用 onCreate() 方法。此时，OpenGL 已设置完毕，所有 Corona 框架均可用。

  2. Corona/main.lua — 在 Lua 代码中，通过 require() 加载 plugin.library。然后，Corona 引擎将查找名为 plugin.library.LuaLoader 的相应 Java 类并调用它。此类的名称是动态的，使用传递给 require() 的原始库名称作为 LuaLoader 类的包名称构造。LuaLoader 类应实现 JNLua 接口 com.naef.jnlua.JavaFunction。

  3. android/plugin/src/main/java/plugin/library/LuaLoader.java — 当完全限定的 LuaLoader 类路径解析后，将使用默认构造函数实例化该类。然后 Lua 通过 JNLua 调用 invoke() 方法并完成所有繁重的工作，例如创建 Lua 库表、注册 show() 等 Lua 方法，然后将表留在 Lua 堆栈的顶部。

请注意，LuaLoader 类在进程的生存期内只实例化 **一次**，就像 .dll 或 .so 文件通常在进程的生存期内只加载一次一样。另请注意，每次 Lua 状态执行 require() 时都会调用一次 invoke() 方法 — 这对应于每次实例化 CoronaActivity 时调用一次。

Solar2D Native 开发

Lua/Java 桥接

要桥接 Lua 和 Java 代码，您将使用 JNLua 提供的功能。这允许您在 Lua 中添加直接调用 Java 的库和函数。

原生 API

Android 的原生 API 以 JavaDoc 的形式提供。

使用 ProGuard

只需记住通过添加以下行来防止 ProGuard 混淆您的 plugin.your-plugin-name.LuaLoader 类

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

到插件模块中的 proguard-rules.pro 文件中。

使用常见的 Android 库

如果您正在开发一个插件，它依赖于Android 支持库或Google Play 服务，请阅读我们的Android 依赖项集成指南。

运行时权限支持

有关在 **Android 6.0** 或更高版本中使用 Android 运行时权限的信息，请阅读我们的Android 运行时权限支持指南。

构建设备版本

要从 Android Studio 构建 Solar2D Native 项目，只需使用图标顶栏上的 **运行** 按钮。这将构建您的项目，对其进行签名，并提示您选择部署目标。构建的 .apk 使用您在android → signingConfigsandroid/app/build.gradle 脚本块中指定的密钥库或默认的 debug.keystore（如果没有提供）进行签名。

Android Studio 还有其他几个与构建相关的选项，您可以在此处阅读相关信息。

构建自托管插件

构建要在 Web 服务器上发布的插件（因为该插件尚未打算与社区共享），需要几个简单的额外步骤

  1. 创建一个用于打包的目录，例如 `package-plugin`。在 `package-plugin` 中创建一个名为 `android` 的文件夹。

  2. 创建一个名为 `corona.gradle` 的新 gradle 文件，并将您插件的 `build.gradle` 中的所有依赖项和存储库定义也复制到该文件中。

  3. 将 `metadata.lua` 文件也放在 `package-plugin` 目录中

  4. 使用一个简单的打包脚本将构建结果复制到此目录中，并调用 zip/tar 程序。例如，在 Mac 上，您可以使用以下行，并将它们放在 shell 脚本 `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"

最后，对于那些将使用您的自托管插件的人，他们必须将位置（`www.YOUR_DOMAIN.de/plugins/android.tgz`）添加到他们的 `build.settings` 中，以便 Corona-Apps 的构建过程可以找到该插件。