PopcornFX v2.18

Generic selectors
Exact matches only
Search in title
Search in content
Post Type Selectors
  1. Home
  2. Docs
  3. PopcornFX v2.18
  4. Plugins
  5. Unity Plugin
  6. Getting started

Getting started

Project setup

When loading the PopcornFX plugin for the first time, a PKFxSetting.asset will be created under “Assets/Resources/”. This asset is used to configure all PopcornFX settings.

Those options are separated in 4 main categories:


PKFXSetting General 2.11

  • 1: Enable/Disable raycast collision queries. Might be necessary for certains effects. Might cause lag if used carelessly.
  • 2: Relative path to source PopcornFX project. Make sure that the project has the same version as your PopcornFX Unity Plugin.
  • 3: Path relative to “Assets/’ where baked assets will be stored.
  • 4: Bake with force determinism: Your effect random are now seeded.
  • 5: Enable/Disable console Unity logs from Native plugin.
  • 6: Enable/Disable file logs from Native plugin.


PKFXSetting Rendering 2.11

  • 7:   Debug Only. Show effect bounding boxes.
  • 8:   Debug Only. Show effect raycasts.
  • 9:   Enable/Disable soft particles rendering.
  • 10: Enable/Disable dynamic effects bounds.
  • 11: Enable/Disable vertex shader billboarding. When enabled, billboarding will be handled on GPU. This relies on DrawProcedural from Unity API and VertexID and drastically improves CPU/GPU performance by reducing overhead.
  • 12: Enable/Disable Mesh instancing. Will improve overall performance but need per instance data for the mesh color.
  • 13/14: Enable/Disable Localized Pages.
  • 15: Free unused batches if they are unused during a number of frames.
    • 16: number of frames during which the batch are unused before deletion.
  • 17: See the reason for this option here.
    • 18: The size multiplicators are used to avoid resizing the meshes buffers too often.
      The formula to compute the vertex buffer size for a mesh is the following:
      BufferVertexCount = ParticleCount * VertexPerParticle + VertexBufferSizeMultiplicator * ParticleCount * VertexPerParticle
      Lets say that you have a Unity mesh which holds at most 10 regular billboard particles, if your vertex buffer size multiplicator is 0.5, the mesh will be resized to hold 10 + 0.5 * 10 = 15 particles, which means that if more particles spawn later on, the mesh will not have to resize until at least 5 more particles are spawned.
    • 19: Exactly the same thing as the vertex buffer size multiplicator, but applied to the index count of the meshes. Generally, you should try to set the same value in both multiplicators.
  • 20: List of the PopcornFX rendering buffers with their maximum index and vertex sizes (computed using the values from properties 18 and 19).
  • 21: Clear the existing list of rendering buffers.


PKFXSetting Multithreading 2.11


PKFXSetting Asset 2.11

  • 19: Expose all Pkfx.asset in project. Useful on project upgrade where GUID can be regenerated and need an update in scripts.

Effect ImportingUnity_import_effect

A PopcornFX Effect is the asset (.pkfx.asset) that will contain the sources of the PopcornFX Effect (.pkfx) (see Effect production pipeline). It is defined as an asset by PKFxEffectAsset.cs


To import an effect select the PKFXSetting, Set your “Source Effects Pack” with a valid PopcornFX project (.pkproj). Be sure that the version number of the project is matching the project version of your Unity plugin.

You can then import the whole project, or click on “Choose files” and choose wich effect to import with the interface provided (right image).





Scene basic setup


  • It is required to have a single PKFxRenderingPlugin component present on a game object and active at all times.
    • The PKFxRenderingPlugin component will also instantiate a PKFxLogger which allows the configuration of logs from the plugin.
  • For every camera that should render particles, there should be one attached PKFxCamera component.
  • Instantiate your effects via the PKFxEmitter component.
    • Set your effect source asset.

Particle/Scene Collision

You can choose two ways to setup collision between scene and particles.

  • In PKFXSettings enabling `raycast for collisions` will allow the plugin to perform raycast everytime a particle need a collision check. This is the most acccurate method, and it allow collision between moving objects and particle but can be extremely expensive if too much particles have collision checks
  • otherwise, In PKFxRenderingPlugin enabling ‘Use Scene Mesh’ and choose the PopcornFX Mesh asset corresponding to your scene.

PKFxRendering plugin collision setup

To bake the PopcornFX Mesh asset, add the relevant meshes of the scene and click `Build meshes`

ECS/Burst Integration

By default, PopcornFX simulation is called in MonoBehavior.LateUpdate() while using ECS, we might have systems updating entities transforms after MonoBehavior.LateUpdate(). This will cause one frame of lag to effect transforms.
For better scheduling, PopcornFX plugin lets you call the particle update explicitly. Check “Call particle simulation update manually” in  the PopcornFXSettings asset.

By calling Update() inside a custom ECS system, you can ensure the simulation is run after another specific system.

We suppose that YourCustomSystem updates some entities that have PopcornFX emitters attached to.
In the following example, we ensure that PopcornFX simulation is run after YourCustomSystem.

using UnityEngine;
using Unity.Entities;
using PopcornFX;
public class PKFxSystem : SystemBase
    private PKFxRenderingPlugin m_RenderingPlugin;
    public void SetRenderingPlugin(PKFxRenderingPlugin rp)
        m_RenderingPlugin = rp;
    protected override void OnUpdate()
        if (m_RenderingPlugin == null)

During game initialization, we get the system using ECS’s World.GetOrCreateSystem() and reference the currentPKFXRenderingPlugin.
Here, we assume that the rendering plugin is always in the scene but it can also be instantiated programmatically.

var rp = FindObjectOfType(typeof(PKFxRenderingPlugin));
Was this article helpful to you? Yes No

How can we help?