From 788bcf12ac5aae791e45ec1838758f8949e2c056 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 08:29:09 +0000
Subject: [PATCH] Particles: particles are on their emitter's visibility layer

A camera draws a renderable only if it and every container above it share a
layer with the camera's cullMask. Particles stayed on layer 1 whatever
their emitter was on, so a camera that drew only the emitter's layer (the
way to give an effect a camera of its own) drew the emitter and none of its
particles.

Particles are now born on their emitter's visibilityLayer, and the emitter
fans a change out to the live ones on its next update, as it already does
for blendMode. A pooled particle no longer keeps the layer of its last life.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA2BZwXkRJLpNxCXBNt
---
 packages/melonjs/CHANGELOG.md                 |  1 +
 .../melonjs-camera-and-drawing/SKILL.md       |  3 +
 .../melonjs-particles-and-trails/SKILL.md     |  1 +
 packages/melonjs/src/particles/emitter.ts     | 29 +++++++++
 packages/melonjs/src/particles/particle.ts    |  4 ++
 .../melonjs/tests/camera-cull-mask.spec.js    | 62 +++++++++++++++++++
 6 files changed, 100 insertions(+)

diff --git a/packages/melonjs/CHANGELOG.md b/packages/melonjs/CHANGELOG.md
index 16eb999db..f9f27b786 100644
--- a/packages/melonjs/CHANGELOG.md
+++ b/packages/melonjs/CHANGELOG.md
@@ -23,6 +23,7 @@
 - UI: `UITextButton#bitmapText`, for `label`
 
 ### Fixed
+- Particles: particles are on their emitter's `visibilityLayer`, and follow a change to it. They stayed on layer 1, so a camera whose `cullMask` drew only the emitter's layer drew none of its particles
 - Loader: assets on the game's own origin are requested with its cookies and HTTP auth, so a game behind a login no longer gets a 403 for every asset ([#1801](https://github.com/melonjs/melonJS/issues/1801))
 - Loader: an asset on another origin loads whenever its server allows it (CORS), without `crossOrigin`, and one it does not allow fails at load with an error naming it, instead of later with "Unexpected end of input" or "The source image could not be decoded". `crossOrigin` now only applies to the `<video>`, `<script>` and glTF image elements the loader creates; `"use-credentials"` also sends credentials, as `withCredentials` does
 - Text: an outline no longer hides thin or small letters, being drawn behind them, and is no longer cut off at the edges of the text. Its corners are round by default; only its outer half shows now, so double `lineWidth` to keep its weight, or set `paintOrder: "fill"` and `lineJoin: "miter"` for the old look
diff --git a/packages/melonjs/skills/melonjs-camera-and-drawing/SKILL.md b/packages/melonjs/skills/melonjs-camera-and-drawing/SKILL.md
index 889cc9e83..dcf0ab0e6 100644
--- a/packages/melonjs/skills/melonjs-camera-and-drawing/SKILL.md
+++ b/packages/melonjs/skills/melonjs-camera-and-drawing/SKILL.md
@@ -228,6 +228,9 @@ minimap.cullMask = ~PARTICLES;         // the minimap draws every layer but 2
   set it on an emitter and none of its particles are drawn. The world itself
   obeys it too, and so does what it contains: a child is drawn only if it and
   every container above it share a bit with the camera.
+- Particles are on their emitter's layers, and follow a change to them on the
+  emitter's next update, so a camera that draws only the emitter's layer draws
+  its particles too.
 - A renderable on layer `0` is drawn by no camera; a `cullMask` of `0` draws
   nothing.
 - It decides drawing only: what a camera leaves out still updates, collides and
diff --git a/packages/melonjs/skills/melonjs-particles-and-trails/SKILL.md b/packages/melonjs/skills/melonjs-particles-and-trails/SKILL.md
index c41e26991..f7d92429b 100644
--- a/packages/melonjs/skills/melonjs-particles-and-trails/SKILL.md
+++ b/packages/melonjs/skills/melonjs-particles-and-trails/SKILL.md
@@ -372,6 +372,7 @@ answer when you want discrete puffs rather than a continuous ribbon.
 |---|---|
 | trail looks flat under a `Camera3d` | `Trail` is 2D; use `Trail3d` |
 | particles clutter a minimap or a second camera | every camera draws them: set the emitter's `visibilityLayer` to a layer that camera's `cullMask` leaves out (see `melonjs-camera-and-drawing`) |
+| a camera that draws only the emitter's layer shows no particles | before 20.13 particles stayed on layer 1 whatever their emitter was on; update |
 | `Trail3d` draws nothing, with a console warning | it needs a `Camera3d`; the app's `cameraClass` is still the 2D default |
 | `trail.tint` does nothing | `Trail` cannot be tinted at all; `Trail3d` can |
 | assigning `maxPoints` throws | `Trail3d` sizes its geometry once; pass `length` to the constructor |
diff --git a/packages/melonjs/src/particles/emitter.ts b/packages/melonjs/src/particles/emitter.ts
index 1c20752e3..080d088ac 100644
--- a/packages/melonjs/src/particles/emitter.ts
+++ b/packages/melonjs/src/particles/emitter.ts
@@ -193,6 +193,13 @@ function particleFrames(
  * emitter.blendMode = "overlay";   // live particles AND future ones
  * ```
  *
+ * ### Visibility layers
+ *
+ * Particles are on their emitter's {@link Renderable#visibilityLayer}: they
+ * are born on it, and follow a change to it on the emitter's next `update`.
+ * So a camera whose {@link Camera2d#cullMask} draws only the emitter's layer
+ * draws the emitter's particles as well.
+ *
  * ### Reference space
  *
  * A particle stores a position, and
@@ -294,6 +301,15 @@ export default class ParticleEmitter extends Container {
 	 */
 	#appliedBlendMode: string = "normal";
 
+	/**
+	 * The visibility layers last fanned out to the particles, so a change to
+	 * the emitter's {@link Renderable#visibilityLayer} can be detected per
+	 * frame.
+	 * @ignore
+	 * @internal
+	 */
+	#appliedVisibilityLayer = 1;
+
 	/**
 	 * Decide whether this emitter's particles have to be depth sorted.
 	 *
@@ -800,6 +816,19 @@ export default class ParticleEmitter extends Container {
 			this.isDirty = true;
 		}
 
+		// The same for the visibility layers. A camera draws a particle only
+		// if the particle AND its emitter are on a layer it draws, and a
+		// particle is born on the emitter's layers (see `Particle`), so the
+		// ones alive have to follow a change too: or a camera that draws
+		// only the emitter's new layer would leave every one of them out.
+		if (this.visibilityLayer !== this.#appliedVisibilityLayer) {
+			this.#appliedVisibilityLayer = this.visibilityLayer;
+			for (const particle of this.children ?? []) {
+				particle.visibilityLayer = this.visibilityLayer;
+			}
+			this.isDirty = true;
+		}
+
 		// frame-skip: only do the bookkeeping when actually configured.
 		// Defaults to 0 (every frame), and that path is the hot one.
 		if (this.settings.framesToSkip > 0) {
diff --git a/packages/melonjs/src/particles/particle.ts b/packages/melonjs/src/particles/particle.ts
index 2a0e4c554..6b00dac75 100644
--- a/packages/melonjs/src/particles/particle.ts
+++ b/packages/melonjs/src/particles/particle.ts
@@ -216,6 +216,10 @@ export default class Particle extends Renderable {
 			this.tint.parseCSS(emitter.settings.tint);
 		}
 
+		// on the emitter's layers, so a camera that draws the emitter draws
+		// its particles (a pooled particle would otherwise keep the layer of
+		// its last life)
+		this.visibilityLayer = emitter.visibilityLayer;
 		this.blendMode = emitter.settings.textureAdditive ? "additive" : "normal";
 
 		if (emitter.settings.blendMode !== "normal") {
diff --git a/packages/melonjs/tests/camera-cull-mask.spec.js b/packages/melonjs/tests/camera-cull-mask.spec.js
index 09061b433..09bbd82f8 100644
--- a/packages/melonjs/tests/camera-cull-mask.spec.js
+++ b/packages/melonjs/tests/camera-cull-mask.spec.js
@@ -310,6 +310,68 @@ describe("visibilityLayer and cullMask", () => {
 			emitter.destroy();
 		});
 
+		// an emitter with its particles counted as they are drawn
+		const countedEmitter = (layer) => {
+			const emitter = new ParticleEmitter(0, 0, {
+				width: 10,
+				height: 10,
+				totalParticles: 6,
+			});
+			if (layer !== undefined) {
+				emitter.visibilityLayer = layer;
+			}
+			emitter.burstParticles();
+			emitter.draws = 0;
+			for (const particle of emitter.getChildren()) {
+				particle.inViewport = true;
+				particle.draw = () => {
+					emitter.draws++;
+				};
+			}
+			return emitter;
+		};
+
+		it("draws an emitter's particles in a camera that draws only the emitter's layer", () => {
+			const emitter = countedEmitter(2);
+			const count = emitter.getChildren().length;
+			expect(count).toBeGreaterThan(0);
+			for (const particle of emitter.getChildren()) {
+				expect(particle.visibilityLayer).toBe(2);
+			}
+			const camera = corner();
+			camera.cullMask = 2;
+			drawWith(camera, emitter);
+			expect(emitter.draws).toBe(count);
+			emitter.destroy();
+		});
+
+		it("moves the particles already alive when the emitter's layer changes", () => {
+			const emitter = countedEmitter();
+			const count = emitter.getChildren().length;
+			const camera = corner();
+			camera.cullMask = 2;
+			emitter.visibilityLayer = 2;
+			// picked up on the emitter's next update
+			emitter.update(16);
+			for (const particle of emitter.getChildren()) {
+				expect(particle.visibilityLayer).toBe(2);
+			}
+			drawWith(camera, emitter);
+			expect(emitter.draws).toBe(emitter.getChildren().length);
+			expect(count).toBeGreaterThan(0);
+			emitter.destroy();
+		});
+
+		it("does not let a pooled particle keep the layer of its last life", () => {
+			const first = countedEmitter(4);
+			first.destroy();
+			const second = countedEmitter();
+			for (const particle of second.getChildren()) {
+				expect(particle.visibilityLayer).toBe(1);
+			}
+			second.destroy();
+		});
+
 		it("draws nothing of a world on a layer the camera leaves out", () => {
 			const camera = corner();
 			const world = new Container(0, 0, 100, 100);