Android Studio: project and native debugging — documentation

Open the correct project

Android Studio is used here for the Java/Kotlin wrapper, JNI and native engine C++. Game C# code needs a separate .NET build/debug workflow; Dual (Java + Native) does not attach a C# debugger.

Open Source/platform/android/java, containing settings.gradle. This is the engine platform project rather than a particular exported game's android/build. Before Sync prepare SDK/NDK and tools from compiling for Android. The IDE must see the same ANDROID_HOME, Java and scons as your terminal. Do not accept AGP/Gradle upgrade suggestions without reviewing compatibility with current build files.

Modules and variants

Module	Purpose
`:lib`	Java/JNI wrapper and native engine libraries, AAR packaging.
`:editor`	Android editor and Android/XR variants; depends on the library.
`:app`	Application template for running a game; requires game resources.
`:assetPackInstallTime`, `:dataLib`, `:fusedDepsLib`	Supporting application-packaging modules.
`:nativeSrcsConfigs`, `:editor:macrobenchmark`	Native-source configuration and separate editor measurements.

Maven configuration in source does not establish that your required Reckfell AAR is published and available from Maven Central. Use matching artifacts from this build for local work.

For editor debugging select the editor module run configuration, an Android Debug variant and the device ABI. For app, use a Debug template variant and exported game data. An empty app/src/main/assets does not become a complete game after successful Gradle Sync. Produce a correct export first; copying raw source files does not replace resource imports and C# publishing.

The root Gradle project defaults to selectedAbis=["arm64"]. An x86_64 emulator needs the matching ABI in both the native build and package. Android Studio tasks can run SCons automatically; Sync does not establish compiler readiness. Ordinary CLI packaging instead excludes SCons tasks by default and consumes existing .so files.

Attach native symbols

Build the matching Debug variant with symbols; do not use a .so from another commit, ABI or target.
Select Native Only or Dual (Java + Native) in Run/Debug Configuration when stepping through Java→JNI→C++. Install LLDB through Android Studio. Debugger configuration.
Add Symbol Directories for external symbols. Editor native libraries are under platform/android/java/lib/libs/tools/debug/<ABI>, templates under platform/android/java/lib/libs/debug/<ABI>. Paths are relative to Source; for separate symbols point to matching unstripped/symbol files.
Start Debug on the selected device and verify a stop in Java/JNI, then in the required C++ method. LLDB attachment alone does not establish matching symbols. Debugging Android apps.

Current Gradle code preserves debug symbols when packaging under Android Studio, but this cannot restore symbols already stripped from a library. For an unresolved native breakpoint inspect the loaded module, ABI, build ID and source mapping.

Diagnose the failing stage

Failure	Next step
Gradle Sync/JDK	Compare wrapper, AGP, Gradle JDK and SDK versions against build files.
`Unable to find executable path for the 'scons' command`	Fix PATH for the Android Studio process itself and restart the IDE.
SCons fails	Read the full native build log; successful IDE indexing does not establish compilation.
`app` opens without a game	Check fresh exported resources, the main level and managed publish, not just the wrapper APK.
LLDB cannot resolve lines	Check exact library/ABI/symbol identity instead of adding an arbitrary directory from another build.

Do not begin with a full clean: this repository's Gradle clean also removes some SCons outputs. Preserve needed libraries and symbols before intentional cleanup.

Review boundary: module layout, ABIs, SCons tasks, JNI paths and symbol rules were checked in source. Debugger controls were checked against official Android Studio documentation. The IDE, Sync, compilation, APK installation and on-device LLDB were not run here; this is not a successful debugging-session report.