Running the example application¶

The examples/ParticleSystem_example directory contains a minimal C++ application that registers the Kanzi Particles plugin and loads the ParticlesAssetPackage demo scene. Use it to see Kanzi Particles running outside Kanzi Studio on Windows and Android, and as a reference for registering the plugin in your own application.

The example has no Kanzi Studio project of its own. Its content is the ParticlesAssetPackage project in the assets directory, so you export that project’s kzb file and copy it to the example before you run it.

The example builds for Windows with CMake and for Android with Gradle.

Export the demo scene¶

Note

Kanzi Studio writes files into a project directory when it opens the project. To keep your Kanzi installation unchanged, copy the whole <KanziWorkspace>/Engine/plugins/particles directory to a working location, called <particles> in the steps below. See Kanzi Studio: opening the asset package changes the installation.

To export the demo scene from Kanzi Studio:

In Kanzi Studio, open <particles>/assets/ParticlesAssetPackage/ParticlesAssetPackage.proj.kzm.
Select File → Export → Export KZB.

Kanzi Studio writes particlesassetpackage.kzb and particlesassetpackage.kzb.cfg to the assets/ParticlesAssetPackage/Binary directory.

To export without opening the Kanzi Studio user interface, save these lines to a file, for example export.ktcs, using your own paths:

LoadProject "<particles>\assets\ParticlesAssetPackage\ParticlesAssetPackage.proj.kzm"
ExportBinary "<particles>\assets\ParticlesAssetPackage\Binary\particlesassetpackage.kzb"
ExitApplication

Then run Kanzi Studio from the <KanziInstallation>/Studio/Bin directory in a Windows command prompt:

KanziStudio.exe /Script="<path>\export.ktcs"

Copy the kzb files to the example¶

Copy these files from <particles>/assets/ParticlesAssetPackage/Binary to <particles>/examples/ParticleSystem_example/Application/bin:

particlesassetpackage.kzb
particlesassetpackage.kzb.cfg

The example loads particlesassetpackage.kzb.cfg from its bin directory. The bin/application.cfg that ships with the example sets SurfaceColorSpace = "srgb", because ParticlesAssetPackage uses the Linear color workflow.

Build and run on Windows¶

You need Visual Studio 2022 and CMake 3.13 or newer.

To build and run the example on Windows:

Open a command prompt in <particles>/examples/ParticleSystem_example/Application and run:
```
set KANZI_HOME=<KanziWorkspace>
cmake -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release --target INSTALL
```
The INSTALL target copies ParticleSystem_example.exe to the bin directory.
Open build/ParticleSystem_example.sln in Visual Studio, select the Release configuration, set ParticleSystem_example as the startup project, and run it. The project sets the working directory to bin and adds the Kanzi Engine and Kanzi Particles DLL directories to PATH.

To run bin/ParticleSystem_example.exe outside Visual Studio, first add these directories to PATH:
```
<KanziWorkspace>\Engine\lib\win64\vs2022_Release_DLL
<particles>\lib\win64\vs2022_Release_DLL
```

The application shows the demo scene from a fixed camera, with the first exhibit in view. It has no navigation, so the other exhibits are out of view. To browse all exhibits (shape emitters, affectors, fire and smoke, colliders, events, mesh emitters, and emission counts), open ParticlesAssetPackage.proj.kzm in Kanzi Studio and move the camera in the Preview.

Build and run on Android¶

Set up the Android tools, KANZI_HOME, and the Kanzi Particles Android libraries as described in Setting up Kanzi Particles for Android. The example uses the plugin in <particles>, not the one in your Kanzi installation, so <particles>/lib/android must exist: make the working copy after you install the Android libraries, or copy <KanziWorkspace>/Engine/plugins/particles/lib/android to <particles>/lib.

To build and run the example on Android:

Copy the kzb files to bin as described above. The Android build packs the bin directory into the APK assets.
In <particles>/examples/ParticleSystem_example/Application/configs/platforms/android_gradle, run:
```
set KANZI_HOME=<KanziWorkspace>
gradlew assembleRelease -Parch=aarch64
```
-Parch selects the ABIs to build. The Kanzi Particles Android package contains arm64-v8a and x86_64 libraries, so use aarch64, x86_64, or aarch64,x86_64. Without -Parch, Gradle builds every ABI and fails on the ones the plugin does not ship.
Install the APK from app/build/outputs/apk/release with adb install.

The Gradle build packages the Kanzi Particles plugin library, libkzparticles.so, into the APK.