From 7784db505a9450677d28d4aeffeb697f280beae6 Mon Sep 17 00:00:00 2001
From: Privatech <99482159+Privatech38@users.noreply.github.com>
Date: Sat, 9 May 2026 15:19:23 +0200
Subject: [PATCH 1/2] Document geyser base and poof particles

---
 src/content/docs/paper/dev/api/particles.mdx | 36 +++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/src/content/docs/paper/dev/api/particles.mdx b/src/content/docs/paper/dev/api/particles.mdx
index 627727496..f3808e55c 100644
--- a/src/content/docs/paper/dev/api/particles.mdx
+++ b/src/content/docs/paper/dev/api/particles.mdx
@@ -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";
@@ -731,6 +731,40 @@ 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
+
+### Emitter
+The `GEYSER` particle is an emitter particle, which means that it spawns other particles. In this case, it spawns all the
+above-mentioned geyser particles. The `offsetX` and `offsetZ` arguments are ignored, while `offsetY` is used to determine the vertical velocity of the spawned particles.
+
 ## Miscellaneous behaviors
 This chapter covers particles that have unique behaviors when spawning.
 

From 97281e61d883a23f129c09c871b2e7b9ab13dfae Mon Sep 17 00:00:00 2001
From: Privatech <99482159+Privatech38@users.noreply.github.com>
Date: Sat, 9 May 2026 15:43:18 +0200
Subject: [PATCH 2/2] Document plume and emitter particles

---
 src/content/docs/paper/dev/api/particles.mdx | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/src/content/docs/paper/dev/api/particles.mdx b/src/content/docs/paper/dev/api/particles.mdx
index f3808e55c..45a6ff6e8 100644
--- a/src/content/docs/paper/dev/api/particles.mdx
+++ b/src/content/docs/paper/dev/api/particles.mdx
@@ -760,10 +760,20 @@ Starting values of `xd` and `zd` are in the range [-0.1, 0.1], while `yd` is in
 :::
 
 ### 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, which means that it spawns other particles. In this case, it spawns all the
-above-mentioned geyser particles. The `offsetX` and `offsetZ` arguments are ignored, while `offsetY` is used to determine the vertical velocity of the spawned particles.
+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.