Skip to content

feat(paper): 26.2 Particles #763

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Privatech38 wants to merge 2 commits into
base: main
Choose a base branch
from
+45 −1
Draft

feat(paper): 26.2 Particles #763

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7784db5
Document geyser base and poof particles
Privatech38 May 9, 2026
97281e6
Document plume and emitter particles
Privatech38 May 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 45 additions & 1 deletion src/content/docs/paper/dev/api/particles.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Particles
description: A comprehensive guide to particle spawning.
slug: paper/dev/particles
version: 26.1.1
version: "26.2"
---

import { Tabs, TabItem, Badge } from "@astrojs/starlight/components";
Expand Down Expand Up @@ -731,6 +731,50 @@ one with a scale of `4.0` right after:

![Explosion particle scale comparison](./assets/particles/explosion.webp)

## Geyser particles
There are four geyser particles: `GEYSER_BASE`, `GEYSER_POOF`, `GEYSER_PLUME` and `GEYSER`.

### Base and poof
`GEYSER_BASE` and `GEYSER_POOF` particles function identically, with the only difference being their appearance.

The spawn position of these particles is slightly altered by adding a random offset to each coordinate. The x and z
coordinates are altered by a random value in the range `[-0.25, 0.25]`, while the y coordinate is altered by a random
value in the range `[-0.05, 0.45]`.

They are [directional particles](#directional-particles), but are also affected by the water blocks and burst impulse
parameters. The initial velocity is calculated as follows:
```java
float burstImpulse = burstImpulseBase + 0.25F * waterBlocks;

// xd, yd and zd are the particle velocity's x, y and z components respectively
// xAux, yAux and zAux are the provided velocity vector's x, y and z components respectively
this.xd = this.xd * burstImpulse + xAux;
this.yd = this.yd * burstImpulse + yAux;
this.zd = this.zd * burstImpulse + zAux;

this.yd = Math.abs(this.yd);
```

:::note
Starting values of `xd` and `zd` are in the range [-0.1, 0.1], while `yd` is in the range [0.0, 0.2].
:::

### Plume
The spawn position of these particles is slightly altered by adding a random offset to each coordinate. The x and z
coordinates are altered by a random value in the range `[-0.1, 0.1]`, while the y coordinate is altered by a random
value in the range `[-0.5, 0.5]`.

While technically a [directional particle](#directional-particles), the vertical velocity of this particle is set to `0`
and the horizontal velocity is applied only on the first tick.

The height of the plume is calculated as `5 * waterBlocks`.

### Emitter
The `GEYSER` particle is an emitter particle, meaning it spawns other particles. In this case, it spawns all the previously
mentioned geyser particles. The provided velocity vector is passed to the spawned particles and used as described above.
The geyser base particle's burst impulse base is set to `1.5`, while the poof particle's burst impulse base is set to `2.0`.
The plume particle therefore does not use the burst impulse parameter.

## Miscellaneous behaviors
This chapter covers particles that have unique behaviors when spawning.

Expand Down