Разработка плагина RuStore Billing для Defold. Часть 1: Создание Defold-проекта

Мы хотим, чтобы интеграция наших инструментов была максимально простой и понятной. Поэтому запускаем серию статей, в которых будем делиться советами по работе с RuStore Billing SDK и созданию плагинов для разных платформ и игровых движков.

Интеграция RuStore Billing SDK в игры на движке Defold может быть немного сложнее, чем нативный вариант. SDK написан на Kotlin, и взаимодействие системы скриптинга Defold на Lua с нативным SDK требует использования JNI (Java Native Interface). 

Меня зовут Роман Пельмегов, я работаю разработчиком в RuStore.

В этой статье расскажу, как мы интегрировали платежные функции RuStore в Defold. Вы узнаете, как создать плагин и подключить нативные Android-библиотеки, чтобы упростить работу с SDK.

Стек технологий

Инструменты разработки​

Для создания платёжного решения в рамках гайда необходимы следующие инструменты разработки (см. таблицу ниже).

Создание Defold-проекта и настройка сборки под Android

Перед началом

1. Создайте файл хранилища ключей. Подробные шаги описаны в документации.

2. Создайте эмулятор Android. Как это сделать?

Когда предварительные настройки выполнены, перейдите к созданию проекта в Defold:

1. Запустите исполняемый файл Defold.

2. Выберите шаблон Mobile game и задайте имя (в примере используется billing_example).

3. При необходимости задайте путь к проекту в поле Location или оставьте путь по умолчанию.

Для примера мы используем следующий путь: C:\Defold\billing_example.

4. Нажмите Create New Project, чтобы создать новый проект.

• Отобразится окно приветствия Welcome to Defold созданного проекта.

• Также будут созданы папки .gitignore и .gitattributes для хранения проекта в репозиториях Git.

Проект создан! Перейдём к созданию и настройке сборки под Android.

Проекты на Defold собираются нелокально — это упрощает настройку проекта для сборки под Android.

5. Откройте для редактирования как формы файл game.project, который расположен в корне проекта.

6. В секции Platforms выберите раздел Android.

7. В секции настроек Android выполните задайте следующие значения полей (см. таблицу ниже).

8. В меню инструментов сверху выберите Project > Bundle > Android Application.

Отобразится окно Bundle Application.

9. Укажите путь к файлам, необходимым для подписи приложения (см. таблицу ниже).

10. Убедитесь, что в настройке Architectures установлен флажок архитектуры 32-bit (armv7).

Проекты на Defold собираются нелокально — это упрощает настройку проекта для сборки под Android.

11. В раскрывающемся списке Variant выберите пункт Release.

12. Снимите флажок Generate debug symbols.

Настройки должны выглядеть следующим образом.

13. Нажмите Create Bundle.

14. В отобразившемся окне укажите папку, в которой будет размещена сборка проекта, и подтвердите выбор.

Если все действия были выполнены верно, по указанному пути будет создана папка сборки для Android, в нашем примере:
C:\Defold\armv7-android.

Проекты на Defold собираются нелокально — это упрощает настройку проекта для сборки под Android.

Создание расширений

Для работы платёжного плагина необходимо создать два расширения Defold (см. таблицу ниже).

Каждое из расширений в файловой системе, согласно документации Defold, должно иметь структуру следующего вида.

my_extension/ │ ├── ext.manifest │ ├── src/ │ ├── include/ │ ├── lib/ │   └── [platforms] │ ├── manifests/ │   └── [platforms] │ └── res/     └── [platforms]

Ниже представлено описание структуры расширения.

Структура расширений Defold​

RuStoreCore​

1. В корне проекта billing_example создайте папку extension_rustore_core.

2. Создайте файл extension_rustore_core/ext.manifest, который будет содержать только строку с именем расширения.
   extension_rustore_core/ext.manifest.

name: RuStoreCore

3. Создайте файл extension_rustore_core/src/rustorecore.cpp и пока оставьте его пустым.

4. Создайте папку extension_rustore_core/include и оставьте её пока пустой. В расширении RuStoreCore мы будем создавать заголовочные файлы для классов, которые будут использоваться в других расширениях SDK RuStore.

5. Создайте папку extension_rustore_core/lib/android — в дальнейшем в неё будут помещены файлы .jar.

6. Создайте файл extension_rustore_core/manifests/android/build.gradle.

Структура расширения RuStoreCore на текущем этапе должна иметь следующий вид.

extension_rustore_core/ │ ├── include/ │ ├── lib/ │   └── android/ │ ├── manifests/ │   └── android │       └── build.gradle │ ├── src/ │   └── rustorecore.cpp │ └── ext.manifest

RuStoreBilling​

1. В корне проекта (billing_example) создайте папку extension_rustore_billing.

2. Создайте файл extension_rustore_billing/ext.manifest со следующим содержимым, который будет содержать только строчку с именем расширения.

name: RuStoreBilling

3. Создайте файл extension_rustore_billing/src/rustorebilling.cpp — этот файл будет содержать JNI-вызовы нативных методов.
   Сейчас оставьте этот файл пустым — описание его содержимого будет приведено далее.

4. Создайте папку extension_rustore_billing/lib/android — в ней впоследствии нужно будет разместить созданные в дальнейшем файлы .jar, которые будут содержать обёртку над классами из SDK RuStore billing. Эта обёртка сделает методы SDK пригодными для вызова через JNI.

5. Создайте файл extension_rustore_billing/manifests/android/build.gradle.

Структура расширения RuStoreBilling на текущем этапе должна иметь следующий вид.

extension_rustore_billing/ │ ├── lib/ │   └── android/ │ ├── manifests/ │   └── android │       └── build.gradle │ ├── src/ │  └── rustorebilling.cpp │ └── ext.manifest 

Создание точек входа в расширения​

Далее займёмся настройкой точек входа в расширения. Для этого Defold SDK использует макрос DM_DECLARE_EXTENSION.

RuStoreCore​

Реализуйте вызов DM_DECLARE_EXTENSION для расширения RuStoreCore в ранее созданном файле extension_rustore_core/src/rustorecore.cpp.

#define EXTENSION_NAME RuStoreCore #define LIB_NAME "RuStoreCore" #define MODULE_NAME "rustorecore"  #if defined(DM_PLATFORM_ANDROID)  static const luaL_reg Module_methods[] = {    {0, 0} };  #else  static const luaL_reg Module_methods[] = {    {0, 0} };  #endif  static void LuaInit(lua_State* L) {    int top = lua_gettop(L);    luaL_register(L, MODULE_NAME, Module_methods);    lua_pop(L, 1);    assert(top == lua_gettop(L)); }  static dmExtension::Result InitializeMyExtension(dmExtension::Params* params) {    LuaInit(params->m_L);    return dmExtension::RESULT_OK; }  static dmExtension::Result UpdateMyExtension(dmExtension::Params* params) {    return dmExtension::RESULT_OK; }  static dmExtension::Result FinalizeMyExtension(dmExtension::Params* params) {    return dmExtension::RESULT_OK; }  DM_DECLARE_EXTENSION(EXTENSION_NAME, LIB_NAME, nullptr, nullptr, InitializeMyExtension, UpdateMyExtension, nullptr, FinalizeMyExtension) 

RuStoreBilling​

Реализуйте вызов DM_DECLARE_EXTENSION для расширения RuStoreBilling в ранее созданном файле extension_rustore_billing/src/rustorebilling.cpp.

#define EXTENSION_NAME RuStoreBilling #define LIB_NAME "RuStoreBilling" #define MODULE_NAME "rustorebilling"  #if defined(DM_PLATFORM_ANDROID)  static const luaL_reg Module_methods[] = {    {0, 0} };  #else  static const luaL_reg Module_methods[] = {    {0, 0} };  #endif  static void LuaInit(lua_State* L) {    int top = lua_gettop(L);    luaL_register(L, MODULE_NAME, Module_methods);    lua_pop(L, 1);    assert(top == lua_gettop(L)); }  static dmExtension::Result InitializeMyExtension(dmExtension::Params* params) {    LuaInit(params->m_L);    return dmExtension::RESULT_OK; }  static dmExtension::Result FinalizeMyExtension(dmExtension::Params* params) {    return dmExtension::RESULT_OK; }  DM_DECLARE_EXTENSION(EXTENSION_NAME, LIB_NAME, nullptr, nullptr, InitializeMyExtension, nullptr, nullptr, FinalizeMyExtension)

JNI-вызовы и обратные вызовы (callback)​

Создание метода отображения тоста

Для примера рассмотрим создание простого всплывающего уведомления (тоста) в рамках создаваемого приложения. Отображение тоста можно реализовать с помощью вызова Java метода через JNI или с помощью обратного вызова (callback).

1. Создайте файл extension_rustore_core/src/Example.java со следующим содержимым: .extension_rustore_core/src/Example.java.

package ru.rustore.defold.example;  import android.app.Activity;import android.widget.Toast;public class Example {    public static void showToast(Activity activity, String message) {        activity.runOnUiThread(() -> Toast.makeText(activity, message, Toast.LENGTH_LONG).show());    }}

2. Для вызова метода showToast в файле extension_rustore_core/src/rustorecore.cpp создайте метод, реализующий JNI-запросы.

   Примечание.
   Код нужно вставить в секцию #if defined(DM_PLATFORM_ANDROID), чтобы код выполнялся только на устройствах Android, и перед массивом Module_methods.

   См. пример фаргмента кода До и После ниже.

   До:

//...  static const luaL_reg Module_methods[] =  {         {0, 0}  };  #else  //...

После:

//...  static const luaL_reg Module_methods[] =  {         {"show_toast", ShowToast},         {0, 0}  };  #else  //...  

Созданным методом можно воспользоваться в Lua через имя модуля, указанное в MODULE_NAME при вызове luaL_register.

4. В файле extension_rustore_billing/src/rustorebilling.cpp вставьте строку #include перед секцией #if defined(DM_PLATFORM_ANDROID) (см. пример кода ниже).

До:

#define EXTENSION_NAME RuStoreBilling  #define LIB_NAME "RuStoreBilling"  #define MODULE_NAME "rustorebilling"  #if defined(DM_PLATFORM_ANDROID)  static const luaL_reg Module_methods[] =  {     {0, 0}  };  #else  //...  

После:

#define EXTENSION_NAME RuStoreBilling #define LIB_NAME "RuStoreBilling" #define MODULE_NAME "rustorebilling"  #include <dmsdk/sdk.h>  #if defined(DM_PLATFORM_ANDROID)  static const luaL_reg Module_methods[] = {    {0, 0} };  #else //... 

5. Откройте файл main/main.script и добавьте в метод on_input вызова нашего метода (см. пример кода ниже).

   До:

   function init(self)      msg.post(".", "acquire_input_focus")      msg.post("@render:", "use_fixed_fit_projection", { near = -1, far = 1 })  end  function on_input(self, action_id, action)      if action_id == hash("touch") and action.pressed then          print("Touch!")      end  end

После:

function init(self)      msg.post(".", "acquire_input_focus")      msg.post("@render:", "use_fixed_fit_projection", { near = -1, far = 1 })  end  function on_input(self, action_id, action)      if action_id == hash("touch") and action.pressed then          rustorecore.show_toast("Hello JNI")      end  end

6. Выполните сборку:

• Project > Bundle > Android Application > Create Bindle.

ИЛИ

• Project > Rebundle (если вы уже делали сборку во время сеанса работы с Defold).

Готово! Теперь каждый тап по экрану будет запускать тост (см. изображение ниже).

Обратный вызов (callback)

Обратный вызов (callback) представляет собой немного более сложную задачу. Для примера напишем обратный вызов, который срабатывает после вызова ShowToast и делает запись в Logcat средствами Defold.

1. Модифицируйте класс Example в файле extension_rustore_core/src/Example.java, для этого:

• добавьте приватный метод NativeCallback с ключевым словом native;

• используйте метод для получения текущей даты Date и вызов NativeCallback.

После всех доработок Java-код примет следующий вид.

До:

package ru.rustore.defold.example;  import android.app.Activity;  import android.widget.Toast;  public class Example {      public static void showToast(Activity activity, String message) {          activity.runOnUiThread(() -> Toast.makeText(activity, message, Toast.LENGTH_LONG).show());      }  }

После:

package ru.rustore.defold.example;  import android.app.Activity;  import android.widget.Toast;  import java.util.Date;  public class Example {      private static native void NativeCallback(String value);      public static void showToast(Activity activity, String message) {          activity.runOnUiThread(() -> Toast.makeText(activity, message, Toast.LENGTH_LONG).show());          Date currentDate = new Date();          NativeCallback(currentDate.toString() + ": " + message);      }  }

2. JNI требует использования соглашения о вызовах C для взаимодействия между кодом на Java и кодом на C++ — для этого в файле extension_rustore_core/src/rustorecore.cpp объявите секцию extern «C» и внутри неё напишите функцию согласно соглашениям о вызовах JNI.

До:

//...  #if defined(DM_PLATFORM_ANDROID)  #include <dmsdk/sdk.h>  #include <dmsdk/dlib/android.h>  static int ShowToast(lua_State* L)  //...

После:

//...  #if defined(DM_PLATFORM_ANDROID)  #include <dmsdk/sdk.h>  #include <dmsdk/dlib/android.h>  #include <android/log.h>  extern "C"  {      JNIEXPORT void JNICALL Java_ru_rustore_defold_example_Example_NativeCallback(JNIEnv* env, jobject obj, jstring jvalue)      {          const char* value = env>GetStringUTFChars(jvalue, 0);                  __android_log_print(ANDROID_LOG_INFO, "Example", value);          env>ReleaseStringUTFChars(jvalue, value);      }  }  static int ShowToast(lua_State* L)  //...

3. Выполните сборку:

• Project > Bundle > Android Application > Create Bindle.

ИЛИ

• Project > Rebundle (если вы уже делали сборку во время сеанса работы с Defold). Каждый показ тоста теперь сопровождается записью в Logcat вида: Tue May 14 16:51:16 GMT 2024: Hello JNI.

Итоги

Итак, мы создали простое приложение в Defold. Теперь у нас есть базовое понимание того, как работать с JNI и нативным кодом. В следующей части статьи мы подключим библиотеку RuStore Billing SDK для реализации внутриигровых покупок и создадим демо-приложение, чтобы протестировать все функции плагина.