Creating Custom Particles 1.21.8

Learn how to create a custom particle using Fabric API.

WARNING

This page is written for version 1.21.8. Documentation for older versions may be incomplete.

Particles are a powerful tool. They can add ambience to a beautiful scene, or add tension to an edge of your seat boss battle. Let's add one!

Register a Custom Particle

We'll be adding a new sparkle particle which will mimic the movement of an end rod particle.

We first need to register a ParticleType in your mod's initializer class using your mod id.

// This DefaultParticleType gets called when you want to use your particle in code.
public static final SimpleParticleType SPARKLE_PARTICLE = FabricParticleTypes.simple();

	// Register our custom particle type in the mod initializer.
	Registry.register(BuiltInRegistries.PARTICLE_TYPE, ResourceLocation.fromNamespaceAndPath(MOD_ID, "sparkle_particle"), SPARKLE_PARTICLE);

The "sparkle_particle" in lowercase letters is the JSON path for the particle's texture. You will be creating a new JSON file with that exact name later.

Client-Side Registration

After you have registered the particle in the mod's initializer, you will also need to register the particle in the client-side initializer.

// For this example, we will use the end rod particle behaviour.
ParticleFactoryRegistry.getInstance().register(FabricDocsReference.SPARKLE_PARTICLE, EndRodParticle.Provider::new);

In this example, we are registering our particle on the client-side. We are then giving the particle some movement using the end rod particle's factory. This means our particle will move exactly like an end rod particle.

TIP

You can see all the particle factories by looking at all the implementations of the ParticleProvider interface. This is helpful if you want to use another particle's behaviour for your own particle.

• IntelliJ's hotkey: Ctrl+Alt+B
• Visual Studio Code's hotkey: Ctrl+F12

Creating a JSON File and Adding Textures

You will need to create 2 folders in your resources/assets/mod-id/ folder.

Folder Path	Explanation
/textures/particle	The particle folder will contain all the textures for all of your particles.
/particles	The particles folder will contain all of the json files for all of your particles.

For this example, we will have only one texture in textures/particle called "sparkle_particle_texture.png".

Next, create a new JSON file in particles with the same name as the JSON path that you used when registering your ParticleType. For this example, we will need to create sparkle_particle.json. This file is important because it lets Minecraft know which textures our particle should use.

{
  "textures": ["fabric-docs-reference:sparkle_particle_texture"]
}

TIP

You can add more textures to the textures array to create a particle animation. The particle will cycle through the textures in the array, starting with the first texture.

Testing the New Particle

Once you have completed the JSON file and saved your work, you are good to load up Minecraft and test everything out!

You can see if everything has worked by typing the following command:

/particle fabric-docs-reference:sparkle_particle ~ ~1 ~

INFO

The particle will spawn inside the player with this command. You will likely need to walk backwards to actually see it.

Alternatively, you can also use a command block to summon the particle with the exact same command.