Setting up Kanzi Particles for Android¶

This guide walks through what you need to install and configure to ship a Kanzi project that uses Kanzi Particles as an Android application. It assumes you already have a working Kanzi project on the desktop: see Setting up Kanzi Particles if you do not.

The flow is validated against Snapdragon / Adreno 650 (Galaxy Tab S7+, OpenGL ES 3.2). Other Adreno- or Mali-based ES 3.1+ devices follow the same steps.

Prerequisites¶

Install the following before you start. Versions listed are what Kanzi Particles is currently validated against; older versions may work but are not tested.

Component	Version / source
Android Studio	Ladybug or newer
Android NDK	`28.2.13676358`
CMake (Android-bundled)	`3.30.5`
Android SDK Platform	API level 35
Android SDK Build-Tools	35.0.0
Android Platform-Tools (`adb`)	Latest from Android Studio’s SDK Manager
JDK	The JBR shipped with Android Studio

Install the NDK and CMake versions through Android Studio’s SDK Manager → SDK Tools panel, with Show Package Details enabled so you can pin the exact versions. Install API 35 from the SDK Platforms panel.

Note

The bundled cmake from Android Studio is what Gradle invokes; a system cmake higher up the PATH will not be used. If you upgrade or downgrade the bundled version, also update the cmake.version value in your project’s kanzinative/build.gradle to match.

Environment variables¶

Set these in Windows System Properties → Environment Variables (or the equivalent on your OS):

KANZI_HOME=<path-to-your-kanzi-workspace>
JAVA_HOME=<Android-Studio-install>\jbr
ANDROID_HOME=<your-user-home>\AppData\Local\Android\Sdk

KANZI_HOME must point at a workspace containing both the Kanzi Engine and the Kanzi Particles plugin built for Android. After Kanzi Hub installs the plugin, you should see:

<KANZI_HOME>\Engine\lib\android\KZGFX_Release\arm64-v8a\libkzgfx.so
<KANZI_HOME>\Engine\plugins\particles\lib\android\KZGFX_Release\arm64-v8a\libkzparticles.so

If those files are missing, install Kanzi Engine for Android and the Kanzi Particles Android binaries through Kanzi Hub, or contact your build engineer for a snapshot.

Device setup¶

Enable Developer Options and USB debugging on your Android device.
Plug it in and accept the RSA prompt.
Confirm the device is recognised:
```
adb devices
```
The device should be listed as device, not unauthorized or offline.

Kanzi Particles requires an OpenGL ES 3.1+ runtime for compute shaders. Most devices released after 2018 support this; older or budget-tier hardware may not.

Configuring your project¶

Two changes are required in your project for Kanzi Particles to load and run on Android.

1. Link the Kanzi Particles plugin into your application’s native build¶

When Kanzi Studio generates an Android build configuration for your project, the templated kanzinative Gradle module ships with the particles plugin disabled by default. If you skip this step the application will exit at startup with:

com.rightware.kanzi.InvalidKzbFileException: Failed to load plugin 'kzparticles'

To enable it:

Open <YourProject>/Application/configs/platforms/android_gradle/kanzinative/build.gradle.

Locate the externalNativeBuild block and change -DKANZI_LINK_KZPARTICLES=OFF to ON:

// Enable to add Particles plugin to the AAR.
// It has to be available in Engine/plugins/particles/.
arguments "-DKANZI_LINK_KZPARTICLES=ON"

Save the file.

Note

In Android Studio you may need Sync Project with Gradle Files followed by Clean Build for the change to be picked up.

2. Declare OpenGL ES 3.1 in your application’s manifest¶

Kanzi Particles dispatches compute shaders for emission, simulation, affectors, collision, and event generation. Compute shaders require OpenGL ES 3.1 or newer. Without an explicit declaration, Kanzi may pick a context that does not support compute and every Kanzi Particles dispatch will silently fail.

Edit <YourProject>/Application/configs/platforms/android_gradle/app/src/main/AndroidManifest.xml and ensure the <manifest> element contains:

<uses-feature
    android:glEsVersion="0x00030001"
    android:required="true" />

Setting required="true" also makes the application invisible on the Play Store to devices that do not meet the requirement, which avoids users installing it on hardware where it cannot run.

Building and installing¶

Once the two changes above are in place, build the APK from your project’s Android Gradle folder:

Open a console at <YourProject>/Application/configs/platforms/android_gradle/.

Confirm the environment is set up:

echo %KANZI_HOME%
echo %JAVA_HOME%
echo %ANDROID_HOME%
adb devices

Build the APK:

gradlew assembleDebug

The output APK lands at:

app\build\outputs\apk\debug\app-debug.apk

Install on your connected device. Replace the placeholders with your project’s package name (defined in the manifest):
```
adb install -r app\build\outputs\apk\debug\app-debug.apk
```

Launch:

adb shell am start -n com.example.yourapp/.YourActivity

Watch the device log for any Kanzi messages:
```
adb logcat -s Kanzi
```

Verifying the run¶

A working run looks like:

The application process stays alive (adb shell pidof com.example.yourapp returns a PID).
adb logcat shows the engine loading, shader programs being reflected, and no entries containing EGL_CONTEXT_LOST or does not have a valid uniform buffer object.
Particles are visible on the device screen.

If you see EGL_CONTEXT_LOST shortly after launch, the most common cause is the kernel GPU watchdog firing on a long-running compute dispatch: your scene exceeds the device’s per-frame budget. Try a smaller scene (lower per-emitter MaximumAmount, fewer effects on screen at once) before suspecting a real defect.

Troubleshooting¶

com.rightware.kanzi.InvalidKzbFileException: Failed to load plugin 'kzparticles'

You have not flipped KANZI_LINK_KZPARTICLES to ON in kanzinative/build.gradle. See 1. Link the Kanzi Particles plugin into your application’s native build.

Unsupported class file major version 65

Gradle is using an older JDK than the AGP version requires. Confirm JAVA_HOME points at Android Studio’s bundled JBR (Android Studio Ladybug ships JDK 21).

CMake '<version>' was not found

The bundled CMake version pinned in your project’s kanzinative/build.gradle does not match what is installed under <Sdk>/cmake/. Install the requested version through Android Studio’s SDK Manager, or update the pinned version in build.gradle to one you have.

SDK location not found. Define a valid SDK location...

ANDROID_HOME is not set in the environment Gradle sees. Either set it system-wide and restart the console, or add it to your project’s local.properties file:

sdk.dir=C\:\\Users\\<you>\\AppData\\Local\\Android\\Sdk

AAPT2 RES_TABLE_TYPE_TYPE entry offsets overlap

Android Gradle Plugin / Gradle wrapper / Kanzi Gradle plugin versions are mismatched. Kanzi Particles is currently validated against AGP 8.5, Kanzi Gradle plugin 0.9.0, and Gradle wrapper 8.13.

INSTALL_FAILED_UPDATE_INCOMPATIBLE

You are installing a debug build over a previous install signed with a different debug key (for example, one built on a colleague’s machine). Uninstall the existing app first:

adb uninstall com.example.yourapp

Could not find or access Kanzi's Gradle plugin directory

The Kanzi Gradle plugin needed by your project has not been downloaded into your workspace. Install the snapshot the project’s build.gradle is requesting through Kanzi Hub, or run the workspace’s downloadGradlePlugins helper if your build engineer has provided one.

Particles do not appear, but the app does not crash

Most likely a compute-shader binding issue specific to ES <3.2 drivers. See Known issues for the explicit-binding requirement on custom SSBOs in compute snippets.

Where to go next¶

Getting started with Kanzi Particles: author your first scene against Kanzi Particles in Kanzi Studio.
Writing custom compute materials: write your own compute materials.
Known issues: current platform constraints, including Android specifics.