PARTICLES DOCUMENTATION
Version: 1.9.0.10

Index

Component Concept
Namespacing
MoLang integration
Basic Structure Overview
In Detail
Current Component List
Emitter Components
Particle Components
Examples
Flame particle
Smoke particle
Mob Flame effect
Bouncing Bubbles
Back to top

Component Concept

The particle system is component based. What this means is that particle effects are composed via a set of components. In order for an effect to do something, you add a component that handles that aspect of the effect. For example, an emitter usually needs to have rules for its lifetime, thus the effect should have one or more lifetime components that handle lifetime duties for the emitter and emitted particles.

The idea is that new components can be added later, and one can combine components (where it makes sense) to get different behaviors. A particle might have a Dynamic component for moving around, and a Collision component for handling interaction with the terrain, for example.

Think of components as telling the particle system what you want the emitter or particle to do, rather than exposing a list of particle parameters and wrangling of those parameters to get the desired behavior.
Back to top

Namespacing

All particle effects should be namespaced (in their name).

Namespacing involves adding a 'name:' prefix on the effect tag.

Regular Minecraft will use the 'minecraft: prefix. See the examples for example names.
Back to top

MoLang integration

Where it makes sense, any field can use a MoLang expression. MoLang expressions are strings, and are defined in the MoLang documentation. The particle system uses some special MoLang variables that particle MoLang expressions can use. Additionally, custom MoLang paramaters can be set in various ways and used in MoLang expressions in effects.

Parameters

Name Description
variable.emitterage Age since the current loop started for the emitter
variable.emitterlifetime How long the current loop lasts for the emitter
variable.emitterrandom1 A random from 0.0 to 1.0 that is constant for the current loop of the emitter
variable.emitterrandom2 Another random from 0.0 to 1.0 that is constant for the current loop of the emitter
variable.emitterrandom3 A third random from 0.0 to 1.0 that is constant for the current loop of the emitter
variable.emitterrandom4 A fourth random from 0.0 to 1.0 that is constant for the current loop of the emitter
variable.particleage How long the particle has lived
variable.particlelifetime How long the particle lives for
variable.particlerandom1 A random from 0.0 to 1.0 that is constant for the lifetime of the particle
variable.particlerandom2 Another random from 0.0 to 1.0 that is constant for the lifetime of the particle
variable.particlerandom3 A third random from 0.0 to 1.0 that is constant for the lifetime of the particle
variable.particlerandom4 A fourth random from 0.0 to 1.0 that is constant for the lifetime of the particle
Back to top



Basic Structure Overview

Particle effects consist of basic render parameters, and a set of components. Components can be placed in any order.

Outline:

Back to top

In Detail

Outline:

Back to top

Current Component List

For fields in these components, the following shorthand is used:

Back to top

Emitter Components

Emitter Lifetime Components

Emitter Lifetime Expression component

Emitter will turn 'on' when the activation expression is non-zero, and will turn 'off' when it's zero. This is useful for situations like driving an entity-attached emitter from an actor variable.



Back to top

Emitter Lifetime Looping component

Emitter will loop until it is removed.



Back to top

Emitter Lifetime Once component

Emitter will execute once, and once the lifetime ends or the number of particles allowed to emit have emitted, the emitter expires.



Back to top



Emitter Rate Components

Emitter Rate Instant component

All particles come out at once, then no more unless the emitter loops.



Back to top

Emitter Rate Manual component

Particle emission will occur only when the emitter is told to emit via the game itself. This is mostly used by legacy particle effects.



Back to top

Emitter Rate Steady component

Particles come out at a steady or MoLang rate over time.



Back to top



Emitter Shape Components

Shape controls both where the particles are emitted from and the initial direction of the particles.

Emitter Shape Custom component

All particles are emitted based on a specified set of MoLang expressions.



Back to top

Emitter Shape Entity-AABB component

All particles come out of the axis-aligned bounding box (AABB) for the entity the emitter is attached to, or the emitter point if no entity.



Back to top

Emitter Shape Point component

All particles come out of a point offset from the emitter.



Back to top

Emitter Shape Sphere component

All particles come out of a sphere offset from the emitter.



Back to top



Initial State Components

Emitter Local Space component

This component specifies the frame of reference of the emitter. Applies only when the emitter is attached to an entity. When 'position' is true, the particles will simulate in entity space, otherwise they will simulate in world space. Rotation works the same way for rotation. Default is false for both, which makes the particles emit relative to the emitter, then simulate independently from the entity. Note that rotation = true and position = false is an invalid option.



Back to top





Particle Components

Particle Appearance Components

Particle Appearance Billboard component

This component tells the particle system to render the particle as a billboard, a rectangle in the world facing a particluar direction.



Back to top

Particle Appearance Lighting

When this component exists, particle will be tinted by local lighting conditions in-game



Back to top

Particle Appearance Tinging component

Color tinting of the particle



Back to top



Particle Initial State Components

Particle Initial Speed component

Starts the particle with a specified speed, using the direction specified by the emitter shape.



Back to top

Particle Initial State component

Starts the particle with a specified orientation and rotation rate.



Back to top



Particle Lifetime Components

Particle Expire If In Blocks component

Particles expire when in a block of the type in the list. Note: this component can exist alongside particle_lifetime_expression.



Back to top

Particle Expire If Not In Blocks component

Particles expire when in a block of the type not in the list. Note: this component can exist alongside particle_lifetime_expression.



Back to top

Particle Lifetime Expression component

Standard lifetime component. These expressions control the lifetime of the particle.



Back to top



Particle Motion Components

Particle Motion Collision component

This component enables collisions between the terrain and the particle. Collision detection in Minecraft consists of detecting an intersection, moving to a nearby non-intersecting point for the particle (if possible), and setting its direction to not be aimed towards the collision (usually perpendicular to the collision surface). Note that if this component doesn't exist, there will be no collision.



Back to top

Particle Motion Dynamic component

This component specifies the dynamic properties of the particle, from a simulation standpoint what forces act upon the particle? These dynamics alter the velocity of the particle, which is a combination of the direction of the particle and the speed. Particle direction will always be in the direction of the velocity of the particle.



Back to top

Particle Motion Parametric component

This component directly controls the particle. Note that this component won't work for either manually-emitted particles, or entity-based particle emitters that aren't in local space.



Back to top







Examples

Flame particle

This particle is the little flame that appears on torches and furnaces to indicate fire. It is a simple particle, consisting of a non-moving flame, with some variations. Note the use of MoLang to create variations in the particle behavior.

In addition, the use of texturewidth/height in the UV section of the billboard component allows referencing of UVs via texels:



Back to top

Smoke particle

This particle is the general-purpose smoke puff. It appears on torches, furnaces, Blazes, etc. It is a simple particle with an upward motion consisting of an upwards acceleration tempered by drag.

The main feature of this particle different from the flame particle is the flipbook texture animation. See the details in the particle below, but the effect uses a flipbook subpart of the billboard appearance component to drive uv coordinates from frame to frame over time.

In addition, the use of texturewidth/height in the UV section of the billboard component allows referencing of UVs via texels for the flipbook:



Back to top

Mob Flame effect

The mob flame effect is used by the Blaze when it's charging up to hurl fireballs. This is a flipbook flame effect that rises over time.

This emitter is typically tied to an entity. This allows the use of the entity_aabb shape, as we want the flames to appear all over the blaze. The effect is created/destroyed by the entity, thus the effect itself just needs to be always on.

For this effect, we use the texturewidth/height to make the texel "resolution" be one frame of animation, thus allowing advancement of the frames to be just one.



Back to top

Bouncing Bubbles

This particle effect generates a bunch of bubbles that bounce around.



Back to top