Bin & Particle Dictionary

Every other page in this section teaches you to do something. This one is for the moment you are scrolling a .py dump, land on a property you have never seen, and just need to know what it is and where it belongs.

Entries are grouped by the class that owns them, because in a bin the same name can appear on more than one class, and knowing which one you are inside decides what the value does.

How to read a bin

A VFX bin is a tree. The spine looks like this:

VfxSystemDefinitionData              one complete effect, e.g. a recall or a Q
└── complexEmitterDefinitionData     the list of emitters the system owns
    └── VfxEmitterDefinitionData     one emitter: a trail, a flash, some sparks
        ├── primitive                what each particle draws as
        └── *Definition pointers     erosion, palette, distortion, children, ...

VfxSystemDefinitionData is the container. A property that is not inside the system playing during an ability will not show up during that ability.

The emitter is where most of your time goes. It carries 135 registered fields on its own, and hangs a dozen optional sub-definition objects off pointers. A null pointer means that whole feature is off, which is why deleting a block is often the correct way to disable something.

Value wrappers

Numeric properties are usually wrapped so the engine can hold them constant or vary them:

rate: embed = ValueFloat {
    constantValue: f32 = 20
}

The wrappers are ValueFloat, ValueColor, ValueVector2 and ValueVector3. Each holds a constantValue plus an optional dynamics pointer. They are two separate fields, not two spellings of one field: the constant is always there, and dynamics is an extra object hanging off it.

Birth properties and their over-life partners

Many properties come in pairs. The birth* one is evaluated once, when the particle spawns. Its partner without the prefix keeps acting across the particle's life, and is multiplied with the birth value rather than replacing it.

If a value looks wrong and only one half of a pair is authored, check the other half before changing anything.

Units

Rotations and rotational velocities are in degrees and degrees per second. Lifetimes, periods and delays are in seconds. UV scroll rates are in UVs per second, and UV rotation is in degrees. Colour channels run 0 to 1.

Randomisation, and the 0 suffix

Several birth properties end in 0, such as birthScale0 and birthRotation0. This is a naming leftover, not a minimum-maximum pair. There is no matching birthScale1 on the current emitter class. Per-particle variation comes from probabilityTables, as above.

Flag bytes

Many booleans are not separate fields. They are single bits packed into shared flag bytes on the emitter. Text tooling surfaces them individually as flag, so you will write them one at a time, but they live four or eight to a byte. The full list is in Emitter flags.

System level

VfxSystemDefinitionData, the outermost container. 33 registered fields as of patch 16.16.

Emitter: identity and lifetime

VfxEmitterDefinitionData. Everything from here to Emitter flags is on this class unless a row says otherwise.

How importance culls

importance is checked against the player's Effects Quality setting when the system builds its emitters. It is a category, not a scale, and two of the values behave in ways the name does not suggest.

So 0 through 3 ascend in priority, and 3 is gameplay-critical and never culled. 4 is a low-quality substitute shown only on low settings, and 5 is the reverse, shown only on Medium and above. Pairing a 4 emitter with a 5 emitter is how one effect ships two versions of itself.

Four other things gate whether an emitter exists at all: disabled, colorblindVisibility, ChanceToNotExist, and system flags bit 0x800, which strips everything except importance 3 and 4.

rate, lifetime, particleLifetime and particleLinger are shown with screenshots on the Emitter Library page.

Emitter: emission and timing

Emitter: placement and orientation

Emitter: birth properties

The state a particle is handed the instant it spawns. Anything named birth* is an initial condition, not an ongoing one.

Each of these has a flex* sibling (flexBirthVelocity, flexBirthUVOffset, flexScaleBirthScale and so on) that overrides it when a flex value is supplied.

Emitter: motion over life

Where birth* sets the starting state, these keep acting.

Emitter: colour

Reading an RGBA value

birthColor: embed = ValueColor {
    constantValue: vec4 = { 1, 0.7059, 0, 1 }
}

Channels run 0 to 1 rather than 0 to 255. To convert, divide by 255. The green channel above is 180, and 180 / 255 gives 0.7059.

The fourth value is alpha, where 0 is fully transparent and 1 is fully opaque.

For recolouring in practice, Quartz does the maths for you.

Emitter: texture and UV

Emitter: render state

blendMode values

These are fixed, and the same for every primitive. Each mode selects a source and destination blend factor and a blend operation.

Reading that table in practice:

• 0 and 4 are the additive modes. Black contributes nothing, so they are the safe ones to recolour towards black.
• 1 is standard alpha blending, the closest thing to "normal".
• 2 darkens, since it multiplies by the inverse of the source colour.
• 3 is the opaque mode. It is the only one that writes depth and the only one that does not blend at all.
• 6 and 7 take the minimum or maximum of source and destination instead of adding.

Emitter flags

Four bytes on the emitter, each carrying up to eight named bits. Text tooling exposes them one at a time as flag.

Primitives

primitive is a pointer that decides what each particle draws as. Leaving it unset gives the default camera-facing billboard quad.

Mesh fields

Mesh primitives carry a VfxMeshDefinitionData in mMesh. Note the m prefixes: these are not spelled the way the emitter's own fields are.

Mesh primitives also carry AlignPitchToCamera and AlignYawToCamera on VfxPrimitiveMeshBase.

Mesh file types

An .skn and .skl pair inside a particle folder means an animated mesh. See Meshes as Particles.

Trail and ribbon

VfxPrimitiveTrailBase carries a VfxTrailDefinitionData in mTrail:

VfxRibbonDefinitionData carries birthTilingSize as a ValueVector2.

Sub-definition classes

Each of these hangs off a pointer on the emitter. Null means the feature is off entirely.

Texture mult

VfxTextureMultDefinitionData. A second texture multiplied over the base, the same idea as Multiply in an image editor. The emitter's textureMult field points at this object, and the actual filename is the textureMult string inside it.

Its flag byte carries uvScrollAlphaMult, uvScrollClampMult, TextureMultFilpU, TextureMultFilpV and isRandomStartFrameMult. Those last two really are spelled that way in the engine, so search for "Filp" rather than "Flip" when you go looking for them.

Palette

VfxPaletteDefinitionData. Colours particles by sampling a gradient texture instead of using a flat value.

Alpha erosion

VfxAlphaErosionDefinitionData. Dissolves the particle using a map. This is how nearly every burning-away or wipe effect is built.

An erosion map is usually greyscale, where white erodes first and black last. Multi-channel maps carry an independent pattern per colour channel, and erosionMapChannelMixer picks between them.

Distortion

VfxDistortionDefinitionData. Warps whatever is drawn behind the particle. Shockwaves and heat haze.

Reflection and fresnel

VfxReflectionDefinitionData. The rim-highlight and reflection block. fresnel lives here, not on the emitter.

Soft particles

VfxSoftParticleDefinitionData. Softens the hard seam where a particle intersects geometry.

There is a fifth mode byte selecting which of the two fades apply. A null softParticleParams pointer disables the feature outright, and there is no separate on-off field.

Linger

VfxLingerDefinitionData. Changes the particle during the linger phase rather than just delaying its removal.

Each has a matching Use* flag: UseLingerRotation, UseLingerScale, UseKeyedLingerVelocity, UseKeyedLingerAcceleration, UseKeyedLingerDrag and UseSeparateLingerColor. Setting the value without its flag does nothing.

Materials and drivers

VfxMaterialDefinitionData holds a Material link and a materialDrivers map. Drivers animate a material parameter instead of holding it constant.

For glow and toon shader work, see Static Materials.

Force fields

VfxFieldCollectionDefinitionData, reached through the emitter's fieldCollectionDefinition. Where birthVelocity sets a particle moving, a field keeps acting on it.

Emission shapes

SpawnShape points at an IVfxShape.

VfxEmissionMeshData handles spawning from a mesh, with meshName, skeletonName, AnimationName, meshScale, maxJointWeights, Submeshes and useSurfaceNormalForBirthPhysics.

Child particles

VfxChildParticleSetDefinitionData, reached through the emitter's childParticleSetDefinition. This is how a trail sheds sparks or an explosion throws debris.

VfxChildIdentifier holds effect (a link), effectKey (a hash) and effectName (a string).

VfxParentInheritanceParams holds Mode and RelativeOffset. The offset is a first-class parent-relative channel, separate from the child's own EmitterPosition.

A common pattern is a parent emitter using VfxPrimitiveNonRenderable: it draws nothing and exists only to place its children.

The legacy component model

Older effects use a second, component-based emitter model that still ships in the engine. You will meet it on long-standing champions. It is documented here so you can recognise it, not because you should author new work with it.

Many names appear on both models. blendMode, texture, bindWeight, birthVelocity, particleLifetime and others exist on the modern emitter and on a legacy component, at different offsets. When a value seems to have no effect, check which of the two you are actually editing.

Three names exist only on the legacy model:

VfxEmitterLegacySimple also carries birthScale, scale, birthRotation, birthRotationalVelocity, rotation, scaleBias, orientation, fixedOrbitType, hasFixedOrbit and scaleUpFromOrigin. Note the unsuffixed birthScale and birthRotation here, against birthScale0 and birthRotation0 on the modern emitter.

The LegacySimple pointer is what emitters in the system's simpleEmitterDefinitionData list use. If a system populates that list rather than complexEmitterDefinitionData, this is the block its emitters read.

Properties the emitter has lost

Four emitter properties were retired and will only turn up in old bins or old documentation.

assetCategory was removed from VfxSystemDefinitionData in 14.15.

Things that are easy to get wrong

A short list of the misreadings that cost the most time.

Names and types on this page were read from the engine's registered class layout for patch 16.16. If a property is missing or a description is wrong, it is worth fixing: see How to contribute.