View on GitHub

FOnline Engine

Flexible cross-platform isometric game engine

Android Debugging

Engine-owned documentation. Paths under ../ are relative to the FOnline engine root. Paths under ../../ point to an embedding game project such as Last Frontier when this engine is used as a submodule.

Practical reference for building, packaging, installing, and remote-scene debugging the Android client.

Workflow Overview

Android debug work is split into four layers:

  1. prepare the Android SDK/NDK workspace parts;
  2. build the Android client native library;
  3. package a Gradle project with baked resources;
  4. build/install/launch the APK on a Wi-Fi ADB device.

The current supported platform identifiers are android-arm32, android-arm64, and android-x86. Most local tasks use android-arm64. A package emits an installable Android APK when its DefinePackage(...) entry carries a BINARY Client Android arm64 Apk line — the raw LocalTest AndroidTest package is the reusable example. Which of an embedding project’s release packages include Android (and which CI job builds them) is that project’s own choice; consult the project’s build/CI documentation for its package composition.

The high-level command flow from the repo root is:

bash ../BuildTools/prepare-workspace.sh android-packages android-arm64 # fresh Linux host
# or, when system packages are already present:
bash ../BuildTools/prepare-workspace.sh android-arm64
python3 ../BuildTools/buildtools.py build android-arm64 client RelWithDebInfo
python3 ../BuildTools/buildtools.py package-android-debug LF android-arm64 LocalTest
python3 ../BuildTools/android_device.py --workspace-root Workspace connect
cd Workspace/android-debug/LF-Client-LocalTest-Android
./gradlew assembleDebug
python3 ../BuildTools/android_device.py --workspace-root Workspace install --apk Workspace/android-debug/LF-Client-LocalTest-Android/app/build/outputs/apk/debug/app-debug.apk
python3 ../BuildTools/android_device.py --workspace-root Workspace launch --activity com.lastfrontier.app/.FOnlineActivity
python3 ../BuildTools/android_device.py --workspace-root Workspace logcat

VS Code Task Flow

The active Linux VS Code Android launch tasks are thin wrappers around the same BuildTools entry points:

Android :: Prepare Launch [linux] runs the standard sequence for a LocalTest APK.

Android :: Launch Remote Scene [linux] runs the remote-scene sequence: select scene, prepare workspace, bake resources, build LF_ServerHeadless, build/package/install RemoteSceneLaunch, stop older scene servers on the gameplay ports, start a fresh headless scene server, stop the app, and launch it with a server-host override.

Remote Scene Launch

Android scene debugging uses the RemoteSceneLaunch subconfig rather than the embedded-client SceneLaunch path.

Important differences:

Use Android :: Launch Remote Scene [linux] after compatibility-affecting changes. Launching only the already installed APK can leave an older client talking to a newer scene server and produce Client outdated style failures.

Official Package Targets

The local debug flow above uses package-android-debug and then Gradle assembleDebug from Workspace/android-debug/.... The CI/release package flow is different: MakePackage-<type> targets are generated from the DefinePackage(...) entries in the embedding project’s CMakeLists.txt. Any package whose entry lists BINARY Client Android arm64 Apk produces an installable APK alongside its other artifacts, provided the packaging job runs prepare-workspace android-sdk android-ndk first; the generated package lands under Workspace/output/<DevName>-<type> with the APK produced through the shared ../BuildTools/package.py Android packager. The official packager invokes Gradle with --no-daemon so concurrent package jobs on the same self-hosted runner do not reuse or kill each other’s Gradle daemon.

Source paths inspected

Use this split when debugging Android output:

Runtime Resource Copy

Android packaging moves baked client resources into the Gradle project under app/src/main/assets/Resources.

On first launch after install/update, FOnlineActivity copies those assets into the app files directory and starts the engine with absolute overrides for:

The activity tracks an .asset_revision based on Android package metadata and recopies resources when the installed package changes.

Practical Debugging Notes

When Android launch behavior fails, isolate the failing layer before rebuilding the whole stack:

Key Files and Integration Points

If you need to trace the Android debug flow through the live repository, start with these files:

Validation and Tests

Current checks worth running when Android build, packaging, or launch docs change:

See Also