PARTICLES DOCUMENTATION
Version: 1.10.0.3

This is documentation for a beta release of Minecraft. New features, components, and capabilities in this release are not final and might change without notice before the final release.
Be sure to check the documentation once the release is out of beta if your add-on isn't working properly. Resource and Behavior Packs created for the beta are not guaranteed to work on the final release.

Index

Getting Started
Basic Structure
MoLang Integration
Particles Components
Emitter Components
Particle Components
Examples
Legacy Flame Particle
Legacy Smoke Particle
Legacy Mob Flame Effect
Bouncing Bubbles
Back to top

Getting Started

New particles are contained within a Resource Pack. To begin create a new folder named "particle" in the root of the Resource Pack that you want to add the new particle in.In the particle folder create a JSON file and give it a name.The JSON file needs a format and particle information.

Particle Information contains the particles name, basic render parameters and a set of components. When giving the particle a name, namespacing should be used.

All particle effects must have a namespace as part of their identifier in the format "namespace:name". The minecraft namespace is used for built-in effects only.

Basic Structure

Particle effects consist of basic render parameters and a set of components. The basic render parameters need to appear just after the version and contains a material and a texture.
For materials there are 2 material types to choose from:
-particles_alpha
-particles_opaque
For textures, the particle system can use any particle that can be read by Minecraft.

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

Parameters

Name Type Description
format_version String Required for particle .json is the format version and the particles scope.
particles JSON Object
Name Type Description
my_namespace:my_particle_effect JSON Object Overall effect. This name is the name used to reference the particle from elsewhere, such as a slash command
Name Type Description
basic_render_parameters JSON Object Basic rendering properties such as the texture and material used. All particles require a material to render and a texture to draw
Name Type Description
material String Minecraft material to use for emitter
texture String Minecraft texture to use for emitter
curves JSON Object Interpolation values, with inputs from 0 to 1, and outputs based on the curve described. The result is a MoLang variable that can be used inside MoLan expressions in the components. Curves are evaluated once per frame for each particle.
Name Type Description
molangvar JSON Object The name of the variable that can be used to reference the value of the curve
Name Type Description
type String Can be linear, bezier or catmull_rom
nodes Vector [a, b, c, d] Control nodes for the curve at 0, 0.25, 0.5 and 1.0. Each node can be given as a float or a MoLang expression
input Decimal Input value to use. Can either be a float or a MoLang expression
horizontal_range Decimal The range of input is mapped between 0 and this value. Can either be a float or a MoLang expression
components JSON Object These are the components that define the behavior of the particle system. See below in the Particles Components section of the documentation for more information on them

Outline:

Back to top

MoLang Integration

Where it makes sense, any field can use a MoLang expression. For additional information about MoLang, please check the MoLang Documentation.

The Particle system uses some special MoLang variables that particle MoLang expressions can use:

Name Description
variable.particle_lifetime How long the particle lives for
variable.particle_age How long the particle has lived
variable.particle_random_1 A random from 0.0 to 1.0 that is constant for the lifetime of the particle
variable.particle_random_2 Another random from 0.0 to 1.0 that is constant for the lifetime of the particle
variable.particle_random_3 A third random from 0.0 to 1.0 that is constant for the lifetime of the particle
variable.particle_random_4 A fourth random from 0.0 to 1.0 that is constant for the lifetime of the particle
variable.emitterlifetime How long the current loop lasts for the emitter
variable.emitterage Age since the current loop started for the emitter
variable.emitter_random_1 A random from 0.0 to 1.0 that is constant for the current loop of the emitter
variable.emitter_random_2 Another random from 0.0 to 1.0 that is constant for the current loop of the emitter
variable.emitter_random_3 A third random from 0.0 to 1.0 that is constant for the current loop of the emitter
variable.emitter_random_4 A fourth random from 0.0 to 1.0 that is constant for the current loop of the emitter
Back to top

Additionally, custom MoLang paramaters can be set in various ways and used in MoLang expressions inside and effect.
Back to top





Particles Components

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 componentthat handles that aspect of the effect.For example, an emitter needs to have rules for its lifetime, thus the emitter will (usually) 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 requiring wrangling of those parameters to get the desired behavior.

Emitter Components

This is the documentation for the attributes properties, and components available to use in particle JSON files. Below is a list of components that can be used in the particle JSON files.

Initial State Components

minecraft:emitter_local_space

This component specifies the frame of reference of the emitter.

Parameters

Name Type Default Value Description
position Boolean false When true, particle will simulate in entity space, otherwise it will simulate in world space
rotation Boolean false When true, particle will simulate in entity space, otherwise it will simulate in world space
Back to top



Rate Components

minecraft:emitter_rate_instant

This component causes all the particles to come out at once. The particles do not come out again unless the emitter loops.

Parameters

Name Type Default Value Description
num_particles Decimal / MoLang 10 The number of particles that are emitted at once
Back to top

minecraft:emitter_rate_steady

This component causes the particles to come out at a steady rate over time.

Parameters

Name Type Default Value Description
spawn_rate Decimal / MoLang 1 The number of particles that are emitted per second
max_particles Decimal / MoLang 50 Maximum number of particles that can be active at once for this emitter
Back to top

minecraft:emitter_rate_manual

This component has particle emission only occur when the emitter is told to emit through code. This is used for legacy particle effects and should not be added to new particles.

Parameters

Name Type Default Value Description
max_particles Decimal / MoLang 50 Maximum number of particles that can be active at once for this emitter
Back to top



Lifetime Components

minecraft:emitter_lifetime_looping

This component causes the emitter to loop until the component is removed.

Parameters

Name Type Default Value Description
active_time Decimal / MoLang 10 The emitter will emit particles for this time per loop
sleep_time Decimal / MoLang 0 The emitter will pause emitting particles this time per loop
Back to top

minecraft:emitter_lifetime_once

This component causes the emitter to execute once. When the lifetime ends or the number of particles allowed to emit is reached the emitter expires.

Parameters

Name Type Default Value Description
active_time Decimal / MoLang 10 The emitter will emit particles for this time per loop
Back to top



Shape Components

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

minecraft:emitter_shape_point

This component causes all particles emerge from a point that is offset from the emitter.

Parameters

Name Type Default Value Description
offset Vector [a, b, c] [0, 0, 0] Specifies an offset from the emitter to emit the particles. Each number can be replaced by a MoLang expression instead of a float
direction Vector [a, b, c] [0, 0, 0] Specifies the direction of the particles. Each number can be replaced by a MoLang expression instead of a float
Back to top

minecraft:emitter_shape_sphere

This component causes all particles to come out of a sphere from an offset from the emitter.

Parameters

Name Type Default Value Description
offset Vector [a, b, c] [0, 0, 0] Specifies an offset from the emitter to emit the particles. Each number can be replaced by a MoLang expression instead of a float
direction Vector [a, b, c] [0, 0, 0] Specifies the direction of the particles. Each number can be replaced by a MoLang expression instead of a float
radius Decimal / MoLang 1 Specifies the size of the sphere
surface_only Boolean false If true, particles will only emit from the surface of the sphere
Back to top

minecraft:emitter_shape_custom

This component allows players to create a custom shape for the particle.

Parameters

Name Type Default Value Description
offset Vector [a, b, c] [0, 0, 0] Specifies an offset from the emitter to emit the particles. Each number can be replaced by a MoLang expression instead of a float
direction Vector [a, b, c] [0, 0, 0] Specifies the direction of the particles. Each number can be replaced by a MoLang expression instead of a float
Back to top

minecraft:emitter_shape_entity_aabb

This component causes all particles to come out of the aabb for the attached entity. If there is no entity then it comes out of the emitter point.

Parameters

Name Type Default Value Description
direction Vector [a, b, c] [0, 0, 0] Specifies the direction of the particles. Each number can be replaced by a MoLang expression instead of a float
Back to top





Particle Components

Initial State Components

minecraft:particle_initial_spin

This component starts the particle with a specified rotation and rotation rate.

Parameters

Name Type Default Value Description
rotation Decimal / MoLang 0 Specifies the initial rotation in degrees
rotation_rate Decimal / MoLang 0 Specifies the spin rate in degrees per second
Back to top

minecraft:particle_initial_speed

This component starts the particle with a specified speed. Component uses the direction specified by the emitter shape. The speed can be defined by a float or MoLang with a default value of 0.
Back to top



Motion Components

minecraft:particle_motion_dynamic

This component specifies the dynamic properties of the particle. This determines what forces affects the particle. The dynamic properties alters the velocity of the particle (Affects the speed and direction of the particle.) Direction is always the direction of the velocity.

Parameters

Name Type Default Value Description
linear_acceleration Vector [a, b, c] [0, 0, 0] Specifies the initial rotation in degrees
linear_drag_coefficient Decimal / MoLang 0 Specifies the amount of drag that is applied to the particle. The higher the value the more drag that is applied to the particle
rotation_acceleration Decimal / MoLang 0 Specifies the amount of rotation speed that's applied to the particle. Rotation slows down over time
rotation_drag_coefficient Decimal / MoLang 0 Specifies the amount of drag that is applied to particle rotation. The higher the value the more drag that is applied to particle rotation
Back to top

minecraft:particle_motion_parametric

This component is used to directly control the particle. If a specific position is applied then velocity is ignored.

Parameters

Name Type Default Value Description
relative_position Vector [a, b, c] [0, 0, 0] Values can either be a float or a MoLang Expression
direction Vector [a, b, c] [0, 0, 0] Specifies the 3D direction of the particle
rotation Decimal / MoLang 0 Specifies the rotation of the particle
Back to top

minecraft:particle_motion_collision

This component enables collision between blocks and the particle. The particle will not have collision if this particle doesn't exist.

Parameters

Name Type Default Value Description
enabled Boolean / MoLang true Enables the collision when the value is true
collision_drag Decimal 0 Specifies the amount of drag that is applied to a particle when it collides with a block
coefficient_of_restitution Decimal 0 Specifies the amount of bounce the particle has when it collides (value between 0.0-1.0)
collision_radius Decimal Used to minimize the interpenetration of the particles with the environment. This must be less than or equal to 1/2 block
Back to top



Appearance Components

minecraft:particle_appearance_billboard

This component specifies the size and facing mode for the particle. If this component isn't specified then all particles will aim upwards.

Parameters

Name Type Description
size Vector [a, b] Specifies the x and y size of the billboard. The values can either be deco,a;s pr MoLang Expressions
face_camera_mode String A string used to determine the orientation of the billboard. Valid strings:
Name Description
rotate_xyz Aligned to the camera, perpendicular to the view axis
rotate_y Aligned to the camera, but rotating around the world on the Y axis
lookat_xyz Aimed at the camera, biased toward world y up
lookat_y Aimed at the camera, but rotating around the world on the Y axis
direction Billboard is aligned perpendicular to the direction vector
uv JSON Object Specifies the UVs for the particle
Name Type Default Value Description
texturewidth Integer 1 Specifies the assumed texture width of the particle
textureheight Integer 1 Specifies the assumed texture height of the particle
uv Vector [a, b] Assuming the texture width and height use these uv coordinates. Values can either be decimals or MoLang Expressions
uv_size Vector [a, b] Specifies the size of the UV. Values can either be decimals or MoLang Expressions
flipbook JSON Object Specifies a flipbook animation
Name Type Default Value Description
base_UV Vector [a, b] Specifies the upper-left corner of the UV patch
size_UV Vector [a, b] Specifies the size of the UV patch
step_UV Vector [a, b] Specifies how far to move the UV patch each frame
frames_per_second Decimal Specifies the default frames per second
max_frame Decimal Specifies the maximum frame number (with the first frame being frame 1)
stretch_to_lifetime Boolean Adjusts the Frames per Second to match the lifetime of the particle (optional)
loop Boolean Loops the animation when it reaches the end (optional)
Back to top



Lifetime Components

minecraft:particle_lifetime_expression

This component controls when the particle expires.

Parameters

Name Type Default Value Description
expiration_expression Decimal / MoLang 0
max_lifetime Decimal / MoLang Specifies the amount of time before the particle expires
Back to top

minecraft:particle_expire_if_in_blocks

This component causes the particles to expire when in one of the block types in the list. When adding a block name to the list ensure the at the "minecraft:" prefix appears for the block name (ex. minecraft:water, minecraft:dirt, etc.)
Back to top

minecraft:particle_expire_if_not_in_blocks

This component causes the particles to expire when it is not in one of the block types in the list. When adding a block name to the list ensure the at the "minecraft:" prefix appears for the block name (ex. minecraft:water, minecraft:dirt, etc.)
Back to top







Examples

Legacy 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

Legacy 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

Legacy 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.

Unlike the earlier particles, this is a regular emitter. It is tied to an entity, thus uses the entity_aabb shape, as we want the flames to appear all over the blaze. As the effect is tied to the charged state, the activation expression is used, tied to the EntityFlag::CHARGED actor variable.This causes the flames to appear when the Blaze is charging, then to disappear when it isn't.

In this case, we use the texturewidth/height to make the texel "resolution" be one frame of animation, thus allowing advancement of the frames to be just 1:



Back to top

Bouncing Bubbles

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



Back to top