en

Emitter properties at runtime

Emitter properties at runtime

An emitter property is a value you expose from an effect so the game can change it while the effect is playing — a colour, a rate, a direction. You define them in the Emitter Guide or the Emitter Scheme, and every exported runtime gives you a small API to read and write them by name.

This page describes the API of the JavaScript v1.1 and C# v1.2 runtimes.

Setting a property

Write to every emitter that declares the property, or address one emitter by name when several emitters share a property name:

effect.setPropertyInAllEmitters('MyParticlesPerSecond', 100);
effect.setPropertyInAllEmitters('MyColor', [1.0, 0.5, 0.2]);

effect.setPropertyInEmitter('Sparks', 'MyColor', [1.0, 0.5, 0.2]);

A scalar property takes a number; a vector property takes an array of 2, 3 or 4 numbers, matching how the property is declared in the editor.

Reading a property

effect.getEmitterPropertyValue('Sparks', 'MyColor');     // [1.0, 0.5, 0.2]
effect.getEmitterPropertyValue('MyParticlesPerSecond');  // 100

With two arguments the value comes from the named emitter. With one argument it comes from the first emitter that has such a property — the same rule setPropertyInAllEmitters follows.

A scalar property returns a plain number, a vector property returns an array, and an unknown emitter or property returns undefined.

Values are read live from the running simulation at the moment you call the method. If you have not set a property yourself, you get the default value from the editor. If the effect's own scheme drives that property, you get whatever the simulation currently holds.

Checking whether a property exists

effect.hasEmitterProperty('Sparks', 'MyColor');  // true
effect.hasEmitterProperty('NoSuchProperty');     // false

Listing everything an effect exposes

When you build tooling — an inspector, a debug panel, an editor integration — you usually do not know the property names up front:

for (const p of effect.getEmitterProperties()) {
    console.log(p.emitterName, p.name, p.arity, p.value);
    // e.g. 'Sparks', 'MyColor', 3, [1, 0.5, 0.2]
}

Each entry carries the emitter name, the property name, its arity (1 for a scalar, 2/3/4 for a vector) and its current value.

Only root emitters are addressed

All of these methods work on the effect's root emitters. Attached (child) emitters are not included: their property values are rewritten from their parent on every frame, so setting them from the host would have no lasting effect and reading them would report a transient value.

Do not rely on the internals of an exported file

Exported effects are minified. If you open one you will see short, machine generated names, and internal objects that appear to hold property data.

Do not read or write those directly. Those names are not an API: they change between editor versions, and they differ between commercial and non-commercial exports, so code written against them breaks on the next export. Only the methods documented on this page are stable.

C# (v1.2)

The C# runtime mirrors the same API, following C# naming conventions:

effect.setEmittersPropertyValue("MyColor", new float[] { 1.0f, 0.5f, 0.2f });
effect.setPropertyInEmitter("Sparks", "MyColor", new float[] { 1.0f, 0.5f, 0.2f });

if (effect.tryGetEmitterPropertyValue("Sparks", "MyColor", out float[] color))
{
    // color[0], color[1], color[2]
}

effect.hasEmitterProperty("Sparks", "MyColor");

foreach (var p in effect.getEmitterProperties())
{
    // p.emitterName, p.propName, p.arity, p.value
}

Values are always returned as a float[], one element per component, so a scalar property gives you an array of length 1.

Migrating from JavaScript v1.0

In the v1.0 runtime an emitter property was a plain field on the emitter object, so games assigned to it directly:

// v1.0 — no longer available
emitter['_' + propertyName] = value;

In v1.1 all simulation state lives in a single buffer, which is what makes cloning an effect a single fast copy. Properties are no longer plain fields, so direct assignment does not work. Use setPropertyInEmitter / setPropertyInAllEmitters to write and getEmitterPropertyValue to read.