PARTICLES DOCUMENTATION Version: 1.11.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#
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_opaqueFor 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:
"format_version": "1.8.0",
"particles": {
"minecraft:my_particle_effect": {
"basic_render_parameters": {
"material": <string>
"texture": <string>
}
"curves": {
"<molangvar>": {
"type": type,
"nodes": [<float / molang>, <float / molang>, <float / molang>, <float / molang>],
"input": <float / molang>,
"horizontal_range": <float / molang>
}
}
"components": {
...
}
}
}
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 |
Additionally, custom MoLang paramaters can be set in various ways and used in MoLang expressions inside and effect.
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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.
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 |
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 |
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 |
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) |
|
|
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 |
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.)
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.)
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:
"format_version": "1.8.0","particles": {
"minecraft:basic_flame_particle": {
"basic_render_parameters": {
"material": "particles_alpha",
"texture": "textures/particle/particles"
}
"components": {
"minecraft:emitter_rate_instant": {
"num_particles": 1
},
"minecraft:emitter_lifetime_expression": {
"activation_expression": 1,
"expiration_expression": 0
},
"minecraft:emitter_shape_sphere": {
"radius": 0.025,
"direction": [0, 0, 0]
},
"minecraft:particle_lifetime_expression": {
"max_lifetime": "Math.random(0.6, 2.0)"
},
"minecraft:particle_appearance_billboard": {
"size": [
"(0.1 + variable.particle_random_1*0.1) - (0.1 * variable.particle_age)",
"(0.1 + variable.particle_random_1*0.1) - (0.1 * variable.particle_age)"
],
"facing_camera_mode": "lookat_xyz",
"uv": {
"texturewidth": 128,
"textureheight": 128,
"uv": [0, 24],
"uv_size": [8, 8]
}
}
}
}
}
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:
"format_version": "1.8.0","particles": {
"minecraft:basic_smoke_particle": {
"basic_render_parameters": {
"material": "particles_alpha",
"texture": "textures/particle/particles"
}
"components": {
"minecraft:emitter_rate_instant": {
"num_particles": 1
},
"minecraft:emitter_lifetime_expression": {
"activation_expression": 1,
"expiration_expression": 0
},
"minecraft:emitter_shape_custom": {
"offset": [0, 0, 0],
"direction": [ "Math.random(-0.1, 0.1)", 1.0, "Math.random(-0.1, 0.1)" ]
},
"minecraft:particle_initial_speed": 1.0,
"minecraft:particle_lifetime_expression": {
"max_lifetime": "Math.random(0.4, 1.4)"
},
"minecraft:particle_motion_dynamic": {
"linear_acceleration": [ 0, 0.4, 0 ]
},
"minecraft:particle_appearance_billboard": {
"size": [ 0.1, 0.1 ],
"facing_camera_mode": "lookat_xyz",
"uv": {
"texturewidth": 128,
"textureheight": 128,
"flipbook": {
"base_UV": [56, 0],
"size_UV": [8, 8],
"step_UV": [-8, 0],
"frames_per_second": 8,
"max_frame": 8,
"stretch_to_lifetime": true,
"loop": false
}
}
},
"minecraft:particle_appearance_tinting": {
"color": ["variable.particle_random_1*0.5", "variable.particle_random_1*0.5", "variable.particle_random_1*0.5", 1.0]
},
"minecraft:particle_appearance_lighting": {}
}
}
}
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:
"format_version": "1.8.0","particles": {
"minecraft:mobflame_emitter": {
"basic_render_parameters": {
"material": "particles_alpha",
"texture": "textures/flame_atlas"
}
"components": {
"minecraft:emitter_local_space": {
"position": true
"rotation": true
},
"minecraft:emitter_rate_steady": {
"spawn_rate": "Math.random(15, 25)",
"max_particles": 50
},
"minecraft:emitter_lifetime_expression": {
"activation_expression": "variable.Flags.CHARGED",
"expiration_expression": 0
},
"minecraft:emitter_shape_entity_aabb": {
"direction": [ 0, 1, 0 ]
},
"minecraft:particle_initial_speed": "Math.random(0, 1)",
"minecraft:particle_lifetime_expression": {
"max_lifetime": 1.25
},
"minecraft:particle_motion_dynamic": {
"linear_acceleration": [ 0, 1.0, 0 ],
"linear_drag_coefficient": 0.0
},
"minecraft:particle_appearance_billboard": {
"size": [ 0.5, 0.5 ],
"facing_camera_mode": "lookat_xyz",
"uv": {
"texturewidth": 1,
"textureheight": 32,
"flipbook": {
"base_UV": [0, 0],
"size_UV": [1, 1],
"step_UV": [0, 1],
"frames_per_second": 32,
"max_frame": 32,
"stretch_to_lifetime": true,
"loop": false
}
}
},
}
}
}
Bouncing Bubbles#
This particle effect generates a bunch of bubbles that bounce around.
"format_version": "1.8.0","particles": {
"minecraft:bounce": {
"basic_render_parameters": {
"material": "particles_alpha",
"texture": "textures/particle/particles"
}
"components": {
"minecraft:emitter_rate_instant": {
"num_particles": 100
},
"minecraft:emitter_lifetime_once": {
"active_time": 2
},
"minecraft:emitter_shape_sphere": {
"offset": ["Math.random(-0.5, 0.5)", "Math.random(-0.5, 0.5)", "Math.random(-0.5, 0.5)"],
"direction": "outwards"
"radius": 1
},
"minecraft:particle_initial_speed": 5.0,
"minecraft:particle_initial_spin": {
"rotation": "Math.random(0, 360)",
"rotation_rate": 0
},
"minecraft:particle_lifetime_expression": {
"max_lifetime": 5
},
"minecraft:particle_motion_dynamic": {
"linear_acceleration": [ 0, -9.8, 0 ]
},
"minecraft:particle_motion_collision": {
"coefficient_of_restitution": 0.5,
"collision_drag": 4,
"collision_radius": 0.1
},
"minecraft:particle_appearance_billboard": {
"size": [ 0.1, 0.1 ],
"facing_camera_mode": "rotate_xyz",
"uv": {
"texturewidth": 128,
"textureheight": 128,
"uv": [ 0, 16 ],
"uv_size": [ 8, 8 ]
}
},
"minecraft:particle_appearance_lighting": {}
}
}
}