Known issues

Android: Failed to load plugin 'kzparticles' on app start

When you build a Kanzi project that uses Kanzi Particles for Android, the application exits at startup with:

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

The templated kanzinative Gradle module ships with the particles plugin disabled by default. To enable it:

  1. Navigate to <ProjectName>/Application/configs/platforms/android_gradle/kanzinative.

  2. Open build.gradle.

  3. 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"

  4. Save and rebuild.

    Note

    In Android Studio, you may also need Sync Project with Gradle Files and Clean Build for the change to take effect.

Android: OpenGL ES 3.1 is the minimum runtime

Kanzi Particles dispatches compute shaders for emission, simulation, affectors, collision, and event generation. Compute shaders require OpenGL ES 3.1 or newer. The example application (see Running the example application) declares <uses-feature android:glEsVersion="0x00030001" android:required="true"/>; your application should do the same. Devices reporting only ES 3.0 will not run the plugin.

Validated against Snapdragon / Adreno 650 (Galaxy Tab S7+, ES 3.2).

Kanzi Studio: imported shaders cannot find their include files

The compute shaders in ParticlesAssetPackage include shared files from the Shaders/Particles directory, for example #include "Particles/emitter.glsl". When you import a material, or a prefab that uses one, from the asset package, Kanzi Studio copies the include files that its shader uses directly into the Shaders directory of your project, without their Particles directory, so the imported shader fails to compile with an error like:

#include - Could not process include directive for header name: Particles/emitter.glsl

To work around the issue, copy the Shaders/Particles directory from <KanziWorkspace>/Engine/plugins/particles/assets/ParticlesAssetPackage into the Shaders directory of your Kanzi Studio project, so that Shaders/Particles sits next to the imported shader. You need the same directory when you write your own compute shaders that include these files. See Writing custom compute materials.

Custom compute materials: explicit SSBO bindings required (temporary)

If you author a custom emission-count, affector, collider, or event material that introduces a new buffer (SSBO) declaration, you must give it an explicit, distinct binding = N qualifier within its descriptor set. For example:

layout(std430, set = 1, binding = 7) buffer KZParticlePersistentState
{
    float accumulator;
};

The engine reserves the following bindings in set 1 (engine-managed):

Binding

Buffer

0

ParticleDataBuffer / IndirectEmitBuffer (depending on the snippet)

1

IndirectEmitBuffer (in emitter.glsl)

2

EventBuffer

7

KZParticlePersistentState

For your own SSBOs, pick any other binding number that doesn’t collide with the table above or with other SSBOs in the same program. Without an explicit binding, the SSBO can flatten to GL binding = 0 after spirv-cross set-flattening and silently overlap another buffer on OpenGL ES <3.2 (e.g. Adreno 650), causing “no particles” with no error message.

This restriction is temporary – it will be lifted in an upcoming engine release once explicit binding assignment moves into the shader compilation pipeline.

Kanzi Studio: opening the asset package changes the installation

When you open ParticlesAssetPackage.proj.kzm in Kanzi Studio, for example to browse the demo scene or to export its kzb file, Kanzi Studio writes files into the project directory without asking: a Conan recipe scaffold (conanfile.py, create_and_deploy.bat, README.md), cubemap face and thumbnail images, and kzb export caches. In a Kanzi installation that directory is <KanziWorkspace>/Engine/plugins/particles/assets/ParticlesAssetPackage, so after you open the project, the installation no longer matches what shipped.

To keep your installation unchanged, copy the whole <KanziWorkspace>/Engine/plugins/particles directory to a working location and open the project from the copy. Copy the whole directory, not only assets/ParticlesAssetPackage: the project loads the Kanzi Particles plugin from ../../lib/Win64/vs2022_<configuration>_DLL/kzparticles.dll, relative to the project.