From 0b5d3a456e8bc5f3b056f3aebf01b96ebd426f02 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/4] 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 a43dccb0476a86e7829b054ff19da7416bdef0fe 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/4] 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. From d1929949d0ed286c6e6fe74242e76a66c6b0d1f8 Mon Sep 17 00:00:00 2001 From: Privatech <99482159+Privatech38@users.noreply.github.com> Date: Wed, 17 Jun 2026 14:37:28 +0200 Subject: [PATCH 3/4] feat: Add data types for geyser particles and hyperlink them to JavaDoc --- src/content/docs/paper/dev/api/particles.mdx | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/content/docs/paper/dev/api/particles.mdx b/src/content/docs/paper/dev/api/particles.mdx index 45a6ff6e8..bb9357fbe 100644 --- a/src/content/docs/paper/dev/api/particles.mdx +++ b/src/content/docs/paper/dev/api/particles.mdx @@ -735,7 +735,8 @@ one with a scale of `4.0` right after: 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. +`GEYSER_BASE` and `GEYSER_POOF` particles function identically, with the only difference being their appearance. They use +[`Particle.GeyserBase`](jd:paper:org.bukkit.Particle$GeyserBase) as their data. 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 @@ -760,6 +761,8 @@ Starting values of `xd` and `zd` are in the range [-0.1, 0.1], while `yd` is in ::: ### Plume +The `GEYSER_PLUME` particle uses [`Particle.Geyser`](jd:paper:org.bukkit.Particle$Geyser) as its data. + 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]`. @@ -772,7 +775,9 @@ 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`. + +While this particle uses [`Particle.Geyser`](jd:paper:org.bukkit.Particle$Geyser) as its data, +the geyser base particle's burst impulse base is set to `1.5` and 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 From b631e76a440afd4633249c48c37a9c47ac67476c Mon Sep 17 00:00:00 2001 From: Privatech <99482159+Privatech38@users.noreply.github.com> Date: Wed, 17 Jun 2026 15:03:51 +0200 Subject: [PATCH 4/4] feat: Mention particle size definition for geyser base particles --- src/content/docs/paper/dev/api/particles.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/content/docs/paper/dev/api/particles.mdx b/src/content/docs/paper/dev/api/particles.mdx index bb9357fbe..8e9931bca 100644 --- a/src/content/docs/paper/dev/api/particles.mdx +++ b/src/content/docs/paper/dev/api/particles.mdx @@ -735,9 +735,11 @@ one with a scale of `4.0` right after: 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. They use +`GEYSER_BASE` and `GEYSER_POOF` particles function identically, differing only in appearance.They use [`Particle.GeyserBase`](jd:paper:org.bukkit.Particle$GeyserBase) as their data. +The particle size is calculated as `3.0F + 0.125F * waterBlocks`. + 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]`.