Index
返回顶部Basic Structure Overview
Particle effects consist of basic render parameters, and a set of components. Components can be placed in any order. Outline: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 having to wrangle those parameters to get the desired behavior.返回顶部Current Component List
For fields in these components, the following shorthand is used:Emitter Components
Emitter Lifetime Components
Emitter Lifetime Events component
Allows for lifetime events on the emitter to trigger certain events.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 entity variable.Emitter Lifetime Looping component
Emitter will loop until it is removed.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.Emitter Rate Components
Emitter Rate Instant component
All particles come out at once, then no more unless the emitter loops.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.Emitter Rate Steady component
Particles come out at a steady or Molang rate over time.Emitter Shape Components
Shape controls both where the particles are emitted from and the initial direction of the particles.Emitter Disc component
This component spawns particles using a disc shape, particles can be spawned inside the shape or on its outer perimeter.Emitter Shape Box component
All particles come out of a box of the specified size from the emitter.Emitter Shape Custom component
All particles are emitted based on a specified set of Molang expressions.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.Emitter Shape Point component
All particles come out of a point offset from the emitter.Emitter Shape Sphere component
All particles come out of a sphere offset from the emitter.Initial State Components
Emitter Initialization component
This component allows the emitter to run some Molang at creation, primarily to populate any Molang variables that get used later.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 emitter. Note that rotation = true and position = false is an invalid option. Velocity will add the emitter's velocity to the initial particle velocity.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.Particle Appearance Lighting
When this component exists, particle will be tinted by local lighting conditions in-game.Particle Appearance Tinting component
Color tinting of the particle is controlled by this component:Particle Initial State Components
Particle Initial Speed component
Starts the particle with a specified speed, using the direction specified by the emitter shape.Particle Initial State component
Starts the particle with a specified orientation and rotation rate.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.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.Particle Lifetime Events component
This component allows for triggering events based on various lifetime events.Particle Lifetime Expression component
Standard lifetime component. These expressions control the lifetime of the particle.Particle Lifetime Kill-Plane component
Particles that cross this plane expire. The plane is relative to the emitter, but oriented in world space. The four parameters are the usual 4 elements of a plane equation.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.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.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.Curves
Curves are interpolation values, with inputs from 0 to 1, and outputs based on the curve. The result of the curve is a Molang variable of the same name that can be referenced in Molang in components. For each rendering frame for each particle, the curves are evaluated and the result is placed in a Molang variable of the name of the curve.Events
Events can be triggered elsewhere in the .json and fire off new particle and sound effects.Particle effects have different types. If the type is "emitter", this will create an emitter of "effect" type at the event's world position, in a fire-and-forget way. "emitter_bound" works similarly, except if the spawning emitter is bound to an actor/locator, the new emitter will be bound to the same actor/locator. If the type is "particle", then the event will manually emit a particle on an emitter of "effect" type at the event location, creating the emitter if it doesn't already exist (be sure to use "minecraft:emitter_rate_manual" for the spawned emitter effect). "particle_with_velocity" will do the same as "particle" except the new particle will inherit the spawning particle's velocity.Sound effects specify the specific "level sound event" to be played when the event fires.The events themselves consist of an optional node tree and/or an actual event. When "sequence" is specified, that array will execute in order, with every element executing when that event fires. When using "random", one element will be picked from the array based on the weight.Examples
Bouncing Bubbles
This particle effect generates a bunch of bubbles that bounce around.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: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 entity 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: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: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.| Name | Description |
|---|---|
| variable.emitter_age | Age since the current loop started for the emitter |
| variable.emitter_lifetime | How long the current loop lasts 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 |
| variable.entity_scale | When the effect is attached to an entity, this value is the scale of the entity |
| variable.particle_age | How long the particle has lived |
| variable.particle_lifetime | How long the particle lives for |
| 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 |
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.返回顶部Particles Entity Integration
One of the primary uses for emitting particles in the Bedrock engine is particles associated with entities, such as mobs. Examples can be when the Blaze flames-up during it's attack sequence, or the Evoker's spell effect while summoning Vexes. The goal is to allow binding and management of particle effects attached to entities.The following concepts are important for managing particles with entities via .json:- Effect lists. These live in the resource definition of the entity's .json, along with textures, etc. These list the effects available to the entity, with an internal entity name for the effect, and the associated effect to play.- Locators. These live in the geometry files, and specify a location in the geometry. These locators can be associated with bones, and thus follow the bone as it animates.- Animation controller-based particle management. Using the Animation Controller state machine concept, one can trigger both fire-and-forget and sustained particle effects- Animation timeline particle management. As part of an animation .json for the entity, one can set up a timeline that triggers particle effects at specified times while the animation is playing. Note that an actual physical animation is not needed, just the animation .json structure.Particles that are attached to entities are intrinsically tied to those entities. If the entity ceases to exist, the particle effects cease as well. Emitters follow either the entity, or a locator on the entity.time1/time2/etc are numerical time points, e.g. "0.0". In this example, when the cat sits down, after 3 seconds a smoke puff is generated:Animation Controller effects
Animation controllers can specify effect events for their states. This allows for a list of particle effects to be started upon state entry, and for those particle effects to be automatically ended when leaving the state. For particles that don't terminate (or don't terminate prior to state transition), they will be terminated at state exit.The schema is:"particle_effects": [ // array of effect events]The array syntax allows for more than one effect to be triggered on state entry.An example is the Blaze's flame-up effect in it's animation controller. This animation controller has two states, "default" and "flaming". It transitions between the two via the "query.is_charged" entity flag check. When in the "flaming" state, the "charged_flames" effect is started (with no locator or initialization Molang expression), and is terminated when the state exits.Animation Timeline effects
Animations can also trigger particle effects. These are fire-and-forget effects that are tied to a timeline, when the animation hits that time point, the effect(s) are fired.Effect Event
Particle events in the entity have the following properties:- "effect" is the effect name specified in the entity's resource definition .json (the particle effect list), this specifies what particle effect to start/play- "locator" is an optional parameter that maps to a locator of the same name in the resource definition. By specifying a locator, the emitter will follow that locator around as the entity animates, including orientation. If this is not specified, the effect will occur at the origin of the entity.- "pre_effect_script" is an optional parameter that is a Molang expression run at emitter startup time. This can set up Molang variables, (for example 'particle color'), which can be then referred to inside the particle effect .json itself.Effect List
The effect list is a list of internal effect names to actual particle effects bindings. This is the general form for adding particle effects to an entity. The effect list consists of a list of shorthand names to actual effects. All references to effects will use the shorthand name in animations and animation controllers. Note that this by itself will not cause the particle effect to appear.Particles Examples Pack
https://aka.ms/MCParticlesPackExamples of various particles can be found in the link above. These are examples of various stand-alone particle effects. The particle effects provided as part of the Minecraft installation are tuned to be used with the Minecraft game, and thus do not serve as good examples. Please refer to the examples in the pack to see various ways to utilize the particle system. To invoke an example particle with the examples particles pack enabled, bring up the console, type "/particle name x y z" where "name" is the name of the particle effect, and x/y/z are the coordinates the particle appears at.For example, "/particle minecraft:example_smoke_puff 0 5 0" will spawn a smoke puff at the origin of the world, 5 blocks up from the bottom of the world. "/particle minecraft:example_smoke_puff ~ ~1 ~5" will create that smoke puff about 5 blocks away from the player.| Name | Description |
|---|---|
| minecraft:example_bezier_chaincurve | Demonstrates the use of a bezier chain curve in an effect |
| minecraft:example_beziercurve | Demonstrates the use of a bezier curve in an effect |
| minecraft:example_bounce | Demonstrates collision detection and bouncing for particles |
| minecraft:example_catmullromcurve | Demonstrates the use of a catmull-rom curve in an effect |
| minecraft:example_colorcurve | Demonstrates the use of a color-gradient approach to color variation in an effect |
| minecraft:example_colorcurve2 | Demonstrates the use of a color-gradient approach with variable spacing in an effect |
| minecraft:example_combocurve | Demonstrates the use of a variety of curves in an effect |
| minecraft:example_directional_sphere | Demonstrates the use of directional billboard facing in an effect |
| minecraft:example_entity_sparkle_aabb | When attached to an entity, this effect creates a sparkle effect with the rough axis-aligned bounding box around the entity |
| minecraft:example_entity_sparkle_box | When attached to an entity, this effect creates a sparkle effect in a box around the entity |
| minecraft:example_expire_on_contact | Demonstrates particles disappearing when colliding with the terrain |
| minecraft:example_flipbook | Demonstrates texture uv flipbook technique, of applying successive frames of a texture for visual animation |
| minecraft:example_highrestitution | Demonstrates particle collision with particles gaining energy on each bounce |
| minecraft:example_linearcurve | Demonstrates a piecewise linear curve in an effect |
| minecraft:example_particle_event_system | Demonstrates various particle events executing |
| minecraft:example_smoke_puff | Demonstrates a general smoke puff effect |
| minecraft:example_spiral | Demonstrates a parametric motion spiral effect |
| minecraft:example_watertest | Demonstrates excluding particles from various block types, in this case, particles only survive in water |
| minecraft:fireworks_events_demo | Demonstrates sequencing various particle effects together via events to create a fireworks effect |
Structure In Detail
Outline: