Building Android libraries and templates

When to build

This workflow produces native Android libraries and templates for your Reckfell build. Use it when changing modules, C++ or build options. For ordinary game packaging use Android export; a template APK does not yet contain your game.

Run commands from Source, containing SConstruct. Editor, SDK and templates must match one source/module configuration; the number 1.0.0 alone does not establish that match.

Dependencies pinned by current source

These are this build's versions rather than instructions to replace them with the newest releases. Install SDK packages through Android Studio SDK Manager, including the exact side-by-side NDK. If a version is unavailable from your configured repositories, resolve that before building rather than substituting an arbitrary NDK. Installing the NDK.

ANDROID_HOME must point to the SDK root containing platforms, build-tools, ndk and cmdline-tools, not cmdline-tools/bin itself. If absent, code falls back to ANDROID_SDK_ROOT; a defined but empty ANDROID_HOME suppresses that fallback. Separately check JAVA_HOME, java -version and scons availability from the terminal/IDE performing the build.

If the NDK is missing, configuration can invoke cmdline-tools/latest/bin/sdkmanager (sdkmanager.bat on Windows) to download the pinned version. This requires that tool, network access and accepted licenses. Do not expect an arbitrary empty SDK directory to be fully populated automatically. can_build checks path existence rather than SDK completeness.

Build native libraries first

Minimal ARM64 example without the .NET module:

scons platform=android target=template_debug arch=arm64
scons platform=android target=template_release arch=arm64

Expected native outputs are platform/android/java/lib/libs/debug/arm64-v8a/libreckfell_android.so and the corresponding release path. They are not APKs yet. SCons names arm32, arm64, x86_32, x86_64 map to Android package ABIs armeabi-v7a, arm64-v8a, x86, x86_64.

For additional ABIs repeat both targets with the required arch before packaging. One ARM64 library does not support every device. ndk_platform defaults to android-24; lower values are raised to 24 by configuration. This native API level is separate from Gradle compileSdk/targetSdk.

Package with Gradle

From Source/platform/android/java, use the repository wrapper:

./gradlew generateReckfellTemplates

On Windows, use the equivalent PowerShell step:

.\gradlew.bat generateReckfellTemplates

This CLI workflow normally consumes previously built .so files instead of rebuilding C++ automatically. The task processes available debug/release directories; a missing target may be skipped. Check for both fresh bin/android_debug.apk, bin/android_release.apk and bin/android_source.zip. The ZIP is a Gradle template, not an archive of the whole game or engine source.

Alternatively, generate_android_binaries=yes on the last SCons invocation runs Gradle after the native stage. Avoid repeating it for every ABI unnecessarily. The current Python wrapper invokes Gradle without check=True; a successful SCons exit does not replace checking Gradle logs and outputs. If uncertain, run packaging through the wrapper separately and inspect its exit code.

C#, editor and symbols

module_mono_enabled=yes selects a separate native variant, for which packaging chooses generateReckfellMonoTemplates. It does not turn a standard APK into a .NET template. Matching managed assemblies/SDK and successful C# project publishing are also required; the two commands above do not validate them.

target=editor builds the Android editor rather than a game template. Its libraries go to lib/libs/tools/<debug-or-release>/<ABI>, and package outputs to bin/android_editor_builds. Do not substitute them for android_debug.apk/android_release.apk. The editor auto-packaging branch also invokes XR-distribution editor tasks; this does not establish installation or launch of those variants.

For native debugging use debug_symbols=yes; separate_debug_symbols=yes separates symbols from the distributed binary. Debug target, symbol inclusion and dev_build=yes are distinct settings. Keep symbols tied to the exact .so identity, otherwise LLDB can show incorrect source lines. Working in Android Studio.

Diagnose missing output

Do not start diagnosis with gradlew clean: it also removes generated native libraries and packages. Preserve needed outputs first and identify the failing stage.

Review boundary: pinned versions, ABI selection, SDK paths, packaging dispatch and Gradle tasks were reviewed in source. SDK/NDK selection functions and packaging commands were exercised in isolation with stubbed paths/processes, without downloads. Actual SCons/Gradle, APK compilation, .NET publishing, installation and Android rendering were not performed here; the engine was not changed.