Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

examples(particle-demo): page through effect showcases with UI buttons

yhhf55051d94d52
diff --git a/examples/particle-demo/README.md b/examples/particle-demo/README.md
index c46e8c953..23fe8e357 100644
--- a/examples/particle-demo/README.md
+++ b/examples/particle-demo/README.md
@@ -1,62 +1,63 @@
# Particle Effects
-An interactive playground for the engine's `ParticleEmitter` component and the
-`Particle` runtime API. A single emitter follows your mouse, leaving trails; you
-switch its preset on the fly and fling fireworks with a click.
+A gallery of the engine's `ParticleEmitter`. Page through six composed effects
+with on-screen buttons, and click empty space to throw fireworks.
## Controls
-| Input | Action |
-| ------------ | ------------------------------------------------------------- |
-| Move mouse | The follow emitter tracks the cursor (World space, so it trails) |
-| `1`–`6` | Jump to a preset |
-| `Space` | Cycle to the next preset |
-| Left-click | Spawn a one-shot firework burst at the cursor |
-| `P` | Pause / resume the follow stream |
+| Input | Action |
+| -------------------- | ----------------------------------------------- |
+| **Prev / Next** buttons | Page to the previous / next effect |
+| `←` / `→` / `Space` | Same, from the keyboard |
+| Left-click empty space | Throw a one-shot firework at the cursor |
-## Presets
+## The effects
-`1` Fire · `2` Sparks · `3` Smoke · `4` Magic · `5` Snow · `6` Fountain — each
-remixes the emitter's shape, velocity, colour-over-life, size-over-life, gravity,
-damping and blend mode (additive vs. normal). See `src/config.ts`.
+`Campfire` (fire + smoke + embers) · `Fireworks` (staggered colored bursts) ·
+`Magic Portal` (a swirling ring) · `Fountain` (ballistic jet + mist) ·
+`Snowfall` (a wide, slow drift) · `Sparkles` (a twinkling field). Each mixes
+shape, velocity, colour/size-over-life, gravity, spin and blend mode — see
+`src/config.ts`.
## How it works
-Particles are a plain ECS component (`ParticleEmitter`) simulated by the built-in
-`ParticleSystem`. Nothing here runs per-particle code — a system only starts an
-emitter, edits its fields, or calls the `Particle` resource.
-
-- **The follow emitter** lives in the scene (so its `texture` resolves) with the
- lifecycle fields fixed (`looping`, `playOnStart`, `maxParticles`, World
- `simulationSpace`). `setupSystem` applies preset 0 at startup so `config.ts` is
- the single source for how each preset looks.
-- **Switching presets** (`src/systems/control.ts`) mutates the emitter's fields
- live via `Query(Mut(ParticleEmitter))`. New particles adopt the look next
- frame; particles already alive finish with the look they were born with — a
- natural cross-fade, no reset needed.
-- **Pausing** calls `Particle.stop(entity)` / `.play(entity)` — emission halts
- while live particles play out.
-- **Click bursts** spawn a temporary emitter (`burstCount` > 0, `looping: false`,
- a short `duration` so it emits exactly once) that reuses the follow emitter's
- resolved `texture` handle. It has no self-despawn, so `cleanupSystem` removes it
- once `Particle.getAliveCount(entity)` reaches 0.
-
-Particles draw as additive quads sampling `assets/textures/particle.png` (a soft
-radial dot), so overlapping particles bloom into glows.
+It's **one scene, no reloads** — each effect is a *group of emitters* spawned on
+switch and despawned on the next switch, so the camera and UI persist and there's
+no load latency. (Runtime `.esscene` switching exists via `SceneManager`, but
+entity-group swapping is the idiomatic fit here.)
+
+- **The buttons** are plain UI entities in the scene (`UINode` + `UIVisual` +
+ `Button` + `Interactable`, with a `Text` label child). A click surfaces as a
+ `'click'` UI event, which `switchSystem` reads with
+ `events.query('click').some(e => e.target === entity)` — the same pattern the
+ audio demo uses. The title `Text` is retitled on each switch.
+- **Spawning a group** (`src/config.ts` `spawnShowcase`) inserts each effect's
+ emitters via `Commands`, tagged `ShowcaseEmitter` so they can be despawned as a
+ set. Commands can't set a texture by asset path, so every emitter reuses the
+ handle read from an invisible `TexHolder` sprite that references
+ `assets/textures/particle.png`.
+- **Fireworks** (`src/systems/spark.ts`) spawn a one-shot burst emitter
+ (`burstCount` > 0, `looping: false`, a short `duration`); `isPointerOverUI()`
+ keeps button clicks from also firing one, and `cleanupSystem` despawns each
+ once `Particle.getAliveCount()` hits 0.
+
+Particles draw as additive quads sampling a soft radial dot, so overlaps bloom
+into glows.
## Files
```
assets/
- scenes/main.esscene # camera, dark backdrop, the follow emitter
+ scenes/main.esscene # camera, backdrop, UI (title + Prev/Next), TexHolder
textures/particle.png # soft radial particle sprite
src/
- main.ts # registers the four systems
- config.ts # the six presets, the burst, applyPreset()
- components.ts # Follow tag, Burst component
+ main.ts # registers the systems
+ config.ts # the six showcases, the firework, spawnShowcase()
+ components.ts # tags (buttons, TexHolder, ShowcaseEmitter) + Burst
+ state.ts # the current showcase index
systems/
- setup.ts # applies preset 0 to the follow emitter
- follow.ts # emitter tracks the cursor
- control.ts # presets / pause / click-to-burst input
- cleanup.ts # despawns fireworks once they finish
+ setup.ts # spawn the first showcase, set the title
+ switch.ts # buttons / keys page through the showcases
+ spark.ts # click empty space → firework
+ cleanup.ts # despawn fireworks once they finish
```
diff --git a/examples/particle-demo/assets/scenes/main.esscene b/examples/particle-demo/assets/scenes/main.esscene
index b1e5b1dba..307367833 100644
--- a/examples/particle-demo/assets/scenes/main.esscene
+++ b/examples/particle-demo/assets/scenes/main.esscene
@@ -67,66 +67,492 @@
},
{
"id": 2,
- "name": "Follow",
+ "name": "Canvas",
"parent": null,
+ "children": [
+ 3,
+ 4,
+ 5,
+ 7
+ ],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "Canvas",
+ "data": {
+ "designResolution": {
+ "x": 1280,
+ "y": 720
+ },
+ "scaleMode": 2,
+ "backgroundColor": {
+ "r": 0,
+ "g": 0,
+ "b": 0,
+ "a": 0
+ }
+ }
+ },
+ {
+ "type": "UINode",
+ "data": {}
+ }
+ ]
+ },
+ {
+ "id": 3,
+ "name": "Title",
+ "parent": 2,
"children": [],
"visible": true,
"components": [
{
"type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
"data": {
- "position": {
- "x": 0,
- "y": 0,
- "z": 0
+ "position": 1,
+ "width": {
+ "value": 600,
+ "unit": 0
+ },
+ "height": {
+ "value": 52,
+ "unit": 0
+ },
+ "insetLeft": {
+ "value": 0,
+ "unit": 1
+ },
+ "marginLeft": {
+ "value": 340,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 0,
+ "unit": 1
+ },
+ "marginTop": {
+ "value": 26,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "Campfire",
+ "fontSize": 34,
+ "color": {
+ "r": 0.95,
+ "g": 0.95,
+ "b": 1,
+ "a": 1
+ },
+ "align": 1,
+ "verticalAlign": 1
+ }
+ },
+ {
+ "type": "TitleLabel",
+ "data": {}
+ }
+ ]
+ },
+ {
+ "id": 4,
+ "name": "Hint",
+ "parent": 2,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "width": {
+ "value": 760,
+ "unit": 0
+ },
+ "height": {
+ "value": 24,
+ "unit": 0
+ },
+ "insetLeft": {
+ "value": 0,
+ "unit": 1
+ },
+ "marginLeft": {
+ "value": 260,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 0,
+ "unit": 1
+ },
+ "marginTop": {
+ "value": 690,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "Prev / Next | arrow keys or Space | click empty space for a firework",
+ "fontSize": 16,
+ "color": {
+ "r": 0.72,
+ "g": 0.76,
+ "b": 0.86,
+ "a": 0.9
+ },
+ "align": 1,
+ "verticalAlign": 1
+ }
+ }
+ ]
+ },
+ {
+ "id": 5,
+ "name": "PrevButton",
+ "parent": 2,
+ "children": [
+ 6
+ ],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "width": {
+ "value": 140,
+ "unit": 0
+ },
+ "height": {
+ "value": 54,
+ "unit": 0
+ },
+ "insetLeft": {
+ "value": 0,
+ "unit": 1
+ },
+ "marginLeft": {
+ "value": 480,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 0,
+ "unit": 1
+ },
+ "marginTop": {
+ "value": 626,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": {
+ "r": 0.18,
+ "g": 0.2,
+ "b": 0.28,
+ "a": 0.92
+ }
+ }
+ },
+ {
+ "type": "Button",
+ "data": {
+ "state": 0,
+ "transition": {
+ "normalColor": {
+ "r": 0.18,
+ "g": 0.2,
+ "b": 0.28,
+ "a": 0.92
+ },
+ "hoveredColor": {
+ "r": 0.28,
+ "g": 0.32,
+ "b": 0.44,
+ "a": 1
+ },
+ "pressedColor": {
+ "r": 0.12,
+ "g": 0.14,
+ "b": 0.2,
+ "a": 1
+ },
+ "disabledColor": {
+ "r": 0.2,
+ "g": 0.2,
+ "b": 0.2,
+ "a": 1
+ }
+ }
+ }
+ },
+ {
+ "type": "Interactable",
+ "data": {}
+ },
+ {
+ "type": "PrevButton",
+ "data": {}
+ }
+ ]
+ },
+ {
+ "id": 6,
+ "name": "PrevLabel",
+ "parent": 5,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "value": 0,
+ "unit": 1
+ },
+ "insetRight": {
+ "value": 0,
+ "unit": 1
+ },
+ "insetTop": {
+ "value": 0,
+ "unit": 1
+ },
+ "insetBottom": {
+ "value": 0,
+ "unit": 1
}
}
},
{
- "type": "ParticleEmitter",
- "data": {
- "rate": 90,
- "maxParticles": 600,
- "looping": true,
- "playOnStart": true,
- "simulationSpace": 0,
- "lifetimeMin": 0.7,
- "lifetimeMax": 1.4,
- "shape": 1,
- "shapeRadius": 14,
- "speedMin": 90,
- "speedMax": 190,
- "angleSpreadMin": 75,
- "angleSpreadMax": 105,
- "startSizeMin": 16,
- "startSizeMax": 26,
- "endSizeMin": 3,
- "endSizeMax": 6,
- "sizeEasing": 2,
- "startColor": {
+ "type": "Text",
+ "data": {
+ "content": "Prev",
+ "fontSize": 22,
+ "color": {
"r": 1,
- "g": 0.65,
- "b": 0.15,
+ "g": 1,
+ "b": 1,
"a": 1
},
- "endColor": {
+ "align": 1,
+ "verticalAlign": 1
+ }
+ }
+ ]
+ },
+ {
+ "id": 7,
+ "name": "NextButton",
+ "parent": 2,
+ "children": [
+ 8
+ ],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "width": {
+ "value": 140,
+ "unit": 0
+ },
+ "height": {
+ "value": 54,
+ "unit": 0
+ },
+ "insetLeft": {
+ "value": 0,
+ "unit": 1
+ },
+ "marginLeft": {
+ "value": 660,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 0,
+ "unit": 1
+ },
+ "marginTop": {
+ "value": 626,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": {
+ "r": 0.18,
+ "g": 0.2,
+ "b": 0.28,
+ "a": 0.92
+ }
+ }
+ },
+ {
+ "type": "Button",
+ "data": {
+ "state": 0,
+ "transition": {
+ "normalColor": {
+ "r": 0.18,
+ "g": 0.2,
+ "b": 0.28,
+ "a": 0.92
+ },
+ "hoveredColor": {
+ "r": 0.28,
+ "g": 0.32,
+ "b": 0.44,
+ "a": 1
+ },
+ "pressedColor": {
+ "r": 0.12,
+ "g": 0.14,
+ "b": 0.2,
+ "a": 1
+ },
+ "disabledColor": {
+ "r": 0.2,
+ "g": 0.2,
+ "b": 0.2,
+ "a": 1
+ }
+ }
+ }
+ },
+ {
+ "type": "Interactable",
+ "data": {}
+ },
+ {
+ "type": "NextButton",
+ "data": {}
+ }
+ ]
+ },
+ {
+ "id": 8,
+ "name": "NextLabel",
+ "parent": 7,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "value": 0,
+ "unit": 1
+ },
+ "insetRight": {
+ "value": 0,
+ "unit": 1
+ },
+ "insetTop": {
+ "value": 0,
+ "unit": 1
+ },
+ "insetBottom": {
+ "value": 0,
+ "unit": 1
+ }
+ }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "Next",
+ "fontSize": 22,
+ "color": {
"r": 1,
- "g": 0.12,
- "b": 0.02,
- "a": 0
+ "g": 1,
+ "b": 1,
+ "a": 1
},
- "colorEasing": 1,
- "gravity": {
+ "align": 1,
+ "verticalAlign": 1
+ }
+ }
+ ]
+ },
+ {
+ "id": 9,
+ "name": "TexHolder",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
"x": 0,
- "y": 60
+ "y": 0,
+ "z": -5
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 1,
+ "y": 1
+ },
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 0
},
- "blendMode": 1,
- "layer": 5,
- "texture": "@uuid:24cb4e0f-7c75-4df4-9a4d-58480ee405c0"
+ "texture": "@uuid:24cb4e0f-7c75-4df4-9a4d-58480ee405c0",
+ "layer": 0
}
},
{
- "type": "Follow",
+ "type": "TexHolder",
"data": {}
}
]
diff --git a/examples/particle-demo/project.esproject b/examples/particle-demo/project.esproject
index f0a635f8e..95b6592c5 100644
--- a/examples/particle-demo/project.esproject
+++ b/examples/particle-demo/project.esproject
@@ -1,7 +1,7 @@
{
"formatVersion": "1",
"name": "Particle Effects",
- "description": "An interactive particle playground: a mouse-follow emitter with six switchable presets and click-to-burst fireworks.",
+ "description": "A gallery of particle effects — page through Campfire, Fireworks, Magic Portal, Fountain, Snowfall and Sparkles with on-screen buttons, and click to throw fireworks.",
"tag": "Effects",
"version": "0.2.0",
"defaultScene": "assets/scenes/main.esscene",
diff --git a/examples/particle-demo/src/components.ts b/examples/particle-demo/src/components.ts
index 5229adc5e..99458cdbc 100644
--- a/examples/particle-demo/src/components.ts
+++ b/examples/particle-demo/src/components.ts
@@ -1,10 +1,23 @@
import { defineComponent, defineTag } from 'esengine';
-// The one emitter that tracks the mouse and whose preset the player switches.
-export const Follow = defineTag('Follow');
+// An invisible sprite that holds the particle texture, so runtime-spawned
+// emitters can read its resolved texture handle (Commands can't set a texture by
+// asset path/uuid — only a numeric handle).
+export const TexHolder = defineTag('TexHolder');
-// A one-shot firework emitter spawned on click. `age` gates the getAliveCount
-// despawn check so it isn't removed on the first frame, before it has emitted.
+// The heading text that shows the current showcase's name.
+export const TitleLabel = defineTag('TitleLabel');
+
+// The two on-screen buttons that page through the showcases.
+export const PrevButton = defineTag('PrevButton');
+export const NextButton = defineTag('NextButton');
+
+// Every emitter that belongs to the current showcase — despawned as a group when
+// the showcase changes.
+export const ShowcaseEmitter = defineTag('ShowcaseEmitter');
+
+// A one-shot firework spawned by clicking empty space. `age` gates the
+// getAliveCount despawn so it isn't removed before it has emitted.
export const Burst = defineComponent('Burst', {
age: 0,
});
diff --git a/examples/particle-demo/src/config.ts b/examples/particle-demo/src/config.ts
index 86b8a4af1..b3fd1dee0 100644
--- a/examples/particle-demo/src/config.ts
+++ b/examples/particle-demo/src/config.ts
@@ -1,138 +1,146 @@
-import { EmitterShape, BlendMode, ParticleEasing } from 'esengine';
-import type { ParticleEmitterData } from 'esengine';
+import {
+ EmitterShape, BlendMode, ParticleEasing,
+ Transform, ParticleEmitter,
+} from 'esengine';
+import type { ParticleEmitterData, CommandsInstance } from 'esengine';
+import { ShowcaseEmitter } from './components';
-// A particle "look" — the subset of ParticleEmitter fields the presets vary.
-// Lifecycle (looping/playOnStart/maxParticles), the texture, and the World
-// simulation space stay fixed on the follow emitter; a preset only changes how
-// it looks and moves. Angles are degrees measured from +x, so 90 = up.
-export interface Preset {
+// A showcase is a named set of emitters placed relative to the screen center.
+// Only the fields that differ from ParticleEmitter's defaults are listed; the
+// defaults already give looping, playOnStart, World space and additive blending.
+export interface EmitterSpec {
+ x: number;
+ y: number;
+ data: Partial<ParticleEmitterData>;
+}
+export interface Showcase {
name: string;
- rate: number;
- lifetimeMin: number;
- lifetimeMax: number;
- shape: number;
- shapeRadius: number;
- shapeAngle: number;
- speedMin: number;
- speedMax: number;
- angleSpreadMin: number;
- angleSpreadMax: number;
- startSizeMin: number;
- startSizeMax: number;
- endSizeMin: number;
- endSizeMax: number;
- sizeEasing: number;
- startColor: { r: number; g: number; b: number; a: number };
- endColor: { r: number; g: number; b: number; a: number };
- colorEasing: number;
- angularVelocityMin: number;
- angularVelocityMax: number;
- gravity: { x: number; y: number };
- damping: number;
- blendMode: number;
+ emitters: EmitterSpec[];
}
-export const PRESETS: Preset[] = [
+export const SHOWCASES: Showcase[] = [
{
- name: 'Fire', rate: 90, lifetimeMin: 0.7, lifetimeMax: 1.4,
- shape: EmitterShape.Circle, shapeRadius: 14, shapeAngle: 0,
- speedMin: 90, speedMax: 190, angleSpreadMin: 75, angleSpreadMax: 105,
- startSizeMin: 16, startSizeMax: 26, endSizeMin: 3, endSizeMax: 6, sizeEasing: ParticleEasing.EaseOut,
- startColor: { r: 1, g: 0.65, b: 0.15, a: 1 }, endColor: { r: 1, g: 0.12, b: 0.02, a: 0 }, colorEasing: ParticleEasing.EaseIn,
- angularVelocityMin: 0, angularVelocityMax: 0, gravity: { x: 0, y: 60 }, damping: 0, blendMode: BlendMode.Additive,
+ name: 'Campfire',
+ emitters: [
+ { x: 0, y: -150, data: {
+ rate: 100, maxParticles: 320, lifetimeMin: 0.7, lifetimeMax: 1.4,
+ shape: EmitterShape.Circle, shapeRadius: 16, speedMin: 90, speedMax: 180,
+ angleSpreadMin: 78, angleSpreadMax: 102, startSizeMin: 18, startSizeMax: 30,
+ endSizeMin: 3, endSizeMax: 6, sizeEasing: ParticleEasing.EaseOut,
+ startColor: { r: 1, g: 0.65, b: 0.15, a: 1 }, endColor: { r: 1, g: 0.12, b: 0.02, a: 0 },
+ colorEasing: ParticleEasing.EaseIn, gravity: { x: 0, y: 70 } } },
+ { x: 0, y: -70, data: {
+ rate: 22, maxParticles: 140, lifetimeMin: 2.0, lifetimeMax: 3.5,
+ shape: EmitterShape.Circle, shapeRadius: 14, speedMin: 30, speedMax: 55,
+ angleSpreadMin: 75, angleSpreadMax: 105, startSizeMin: 26, startSizeMax: 40,
+ endSizeMin: 90, endSizeMax: 130, sizeEasing: ParticleEasing.EaseOut,
+ startColor: { r: 0.5, g: 0.5, b: 0.53, a: 0.45 }, endColor: { r: 0.25, g: 0.25, b: 0.28, a: 0 },
+ gravity: { x: 0, y: 40 }, damping: 0.4, blendMode: BlendMode.Normal } },
+ { x: 0, y: -150, data: {
+ rate: 14, maxParticles: 90, lifetimeMin: 1.2, lifetimeMax: 2.2,
+ shape: EmitterShape.Circle, shapeRadius: 10, speedMin: 60, speedMax: 150,
+ angleSpreadMin: 60, angleSpreadMax: 120, startSizeMin: 3, startSizeMax: 6,
+ endSizeMin: 0, endSizeMax: 0, startColor: { r: 1, g: 0.8, b: 0.3, a: 1 },
+ endColor: { r: 1, g: 0.4, b: 0.1, a: 0 }, angularVelocityMin: -180, angularVelocityMax: 180,
+ gravity: { x: 0, y: 95 } } },
+ ],
},
{
- name: 'Sparks', rate: 70, lifetimeMin: 0.5, lifetimeMax: 1.0,
- shape: EmitterShape.Point, shapeRadius: 0, shapeAngle: 0,
- speedMin: 160, speedMax: 360, angleSpreadMin: 0, angleSpreadMax: 360,
- startSizeMin: 5, startSizeMax: 9, endSizeMin: 0, endSizeMax: 0, sizeEasing: ParticleEasing.Linear,
- startColor: { r: 1, g: 0.95, b: 0.6, a: 1 }, endColor: { r: 1, g: 0.4, b: 0.1, a: 0 }, colorEasing: ParticleEasing.Linear,
- angularVelocityMin: -220, angularVelocityMax: 220, gravity: { x: 0, y: -280 }, damping: 0.6, blendMode: BlendMode.Additive,
+ name: 'Fireworks',
+ emitters: [-260, 0, 260].map((x, i) => ({
+ x, y: [120, 185, 130][i], data: {
+ rate: 0, burstCount: 46, burstInterval: [1.1, 1.5, 1.9][i], maxParticles: 220,
+ lifetimeMin: 0.8, lifetimeMax: 1.6, shape: EmitterShape.Point, speedMin: 170, speedMax: 380,
+ startSizeMin: 5, startSizeMax: 10, endSizeMin: 0, endSizeMax: 0, sizeEasing: ParticleEasing.EaseOut,
+ startColor: [{ r: 1, g: 0.85, b: 0.3, a: 1 }, { r: 0.4, g: 0.9, b: 1, a: 1 }, { r: 1, g: 0.4, b: 0.9, a: 1 }][i],
+ endColor: { r: 1, g: 0.3, b: 0.1, a: 0 }, gravity: { x: 0, y: -150 }, damping: 0.3,
+ },
+ })),
},
{
- name: 'Smoke', rate: 26, lifetimeMin: 1.8, lifetimeMax: 3.2,
- shape: EmitterShape.Circle, shapeRadius: 12, shapeAngle: 0,
- speedMin: 25, speedMax: 55, angleSpreadMin: 70, angleSpreadMax: 110,
- startSizeMin: 22, startSizeMax: 34, endSizeMin: 70, endSizeMax: 110, sizeEasing: ParticleEasing.EaseOut,
- startColor: { r: 0.55, g: 0.55, b: 0.58, a: 0.5 }, endColor: { r: 0.28, g: 0.28, b: 0.30, a: 0 }, colorEasing: ParticleEasing.EaseIn,
- angularVelocityMin: -20, angularVelocityMax: 20, gravity: { x: 0, y: 35 }, damping: 0.4, blendMode: BlendMode.Normal,
+ name: 'Magic Portal',
+ emitters: [
+ { x: 0, y: 0, data: {
+ rate: 120, maxParticles: 420, lifetimeMin: 1.2, lifetimeMax: 2.4,
+ shape: EmitterShape.Circle, shapeRadius: 90, speedMin: 8, speedMax: 30,
+ startSizeMin: 8, startSizeMax: 16, endSizeMin: 0, endSizeMax: 0, sizeEasing: ParticleEasing.EaseInOut,
+ startColor: { r: 0.6, g: 0.35, b: 1, a: 1 }, endColor: { r: 0.35, g: 0.9, b: 1, a: 0 },
+ angularVelocityMin: -160, angularVelocityMax: 160, damping: 0.3 } },
+ { x: 0, y: 0, data: {
+ rate: 60, maxParticles: 220, lifetimeMin: 0.8, lifetimeMax: 1.6,
+ shape: EmitterShape.Circle, shapeRadius: 30, speedMin: 5, speedMax: 20,
+ startSizeMin: 6, startSizeMax: 12, endSizeMin: 0, endSizeMax: 0,
+ startColor: { r: 0.9, g: 0.7, b: 1, a: 1 }, endColor: { r: 0.5, g: 0.9, b: 1, a: 0 },
+ angularVelocityMin: 120, angularVelocityMax: 240 } },
+ ],
},
{
- name: 'Magic', rate: 80, lifetimeMin: 1.2, lifetimeMax: 2.2,
- shape: EmitterShape.Circle, shapeRadius: 30, shapeAngle: 0,
- speedMin: 30, speedMax: 90, angleSpreadMin: 0, angleSpreadMax: 360,
- startSizeMin: 8, startSizeMax: 16, endSizeMin: 0, endSizeMax: 0, sizeEasing: ParticleEasing.EaseInOut,
- startColor: { r: 0.65, g: 0.4, b: 1.0, a: 1 }, endColor: { r: 0.3, g: 0.9, b: 1.0, a: 0 }, colorEasing: ParticleEasing.Linear,
- angularVelocityMin: -120, angularVelocityMax: 120, gravity: { x: 0, y: 45 }, damping: 0.2, blendMode: BlendMode.Additive,
+ name: 'Fountain',
+ emitters: [
+ { x: 0, y: -170, data: {
+ rate: 130, maxParticles: 420, lifetimeMin: 1.2, lifetimeMax: 2.0,
+ shape: EmitterShape.Point, speedMin: 320, speedMax: 460, angleSpreadMin: 84, angleSpreadMax: 96,
+ startSizeMin: 6, startSizeMax: 12, endSizeMin: 3, endSizeMax: 5,
+ startColor: { r: 0.5, g: 0.8, b: 1, a: 1 }, endColor: { r: 0.2, g: 0.4, b: 1, a: 0 },
+ gravity: { x: 0, y: -430 } } },
+ { x: 0, y: -170, data: {
+ rate: 40, maxParticles: 160, lifetimeMin: 1.5, lifetimeMax: 2.5,
+ shape: EmitterShape.Circle, shapeRadius: 20, speedMin: 60, speedMax: 140,
+ angleSpreadMin: 70, angleSpreadMax: 110, startSizeMin: 8, startSizeMax: 16,
+ endSizeMin: 20, endSizeMax: 30, startColor: { r: 0.6, g: 0.85, b: 1, a: 0.5 },
+ endColor: { r: 0.4, g: 0.6, b: 1, a: 0 }, gravity: { x: 0, y: -120 }, damping: 0.5 } },
+ ],
},
{
- name: 'Snow', rate: 40, lifetimeMin: 2.5, lifetimeMax: 4.0,
- shape: EmitterShape.Circle, shapeRadius: 40, shapeAngle: 0,
- speedMin: 30, speedMax: 70, angleSpreadMin: 255, angleSpreadMax: 285,
- startSizeMin: 6, startSizeMax: 12, endSizeMin: 6, endSizeMax: 12, sizeEasing: ParticleEasing.Linear,
- startColor: { r: 1, g: 1, b: 1, a: 0.9 }, endColor: { r: 0.8, g: 0.9, b: 1.0, a: 0.25 }, colorEasing: ParticleEasing.Linear,
- angularVelocityMin: -30, angularVelocityMax: 30, gravity: { x: 0, y: -15 }, damping: 0.1, blendMode: BlendMode.Normal,
+ name: 'Snowfall',
+ emitters: [
+ { x: 0, y: 380, data: {
+ rate: 90, maxParticles: 800, lifetimeMin: 5, lifetimeMax: 8,
+ shape: EmitterShape.Rectangle, shapeSize: { x: 1320, y: 12 },
+ speedMin: 40, speedMax: 90, angleSpreadMin: 250, angleSpreadMax: 290,
+ startSizeMin: 5, startSizeMax: 11, endSizeMin: 5, endSizeMax: 11,
+ startColor: { r: 1, g: 1, b: 1, a: 0.9 }, endColor: { r: 0.85, g: 0.92, b: 1, a: 0.5 },
+ angularVelocityMin: -25, angularVelocityMax: 25, gravity: { x: 0, y: -12 },
+ damping: 0.05, blendMode: BlendMode.Normal } },
+ ],
},
{
- name: 'Fountain', rate: 120, lifetimeMin: 1.1, lifetimeMax: 1.9,
- shape: EmitterShape.Point, shapeRadius: 0, shapeAngle: 0,
- speedMin: 300, speedMax: 440, angleSpreadMin: 82, angleSpreadMax: 98,
- startSizeMin: 6, startSizeMax: 12, endSizeMin: 3, endSizeMax: 5, sizeEasing: ParticleEasing.Linear,
- startColor: { r: 0.5, g: 0.8, b: 1, a: 1 }, endColor: { r: 0.2, g: 0.4, b: 1, a: 0 }, colorEasing: ParticleEasing.Linear,
- angularVelocityMin: 0, angularVelocityMax: 0, gravity: { x: 0, y: -420 }, damping: 0, blendMode: BlendMode.Additive,
+ name: 'Sparkles',
+ emitters: [
+ { x: 0, y: 0, data: {
+ rate: 70, maxParticles: 320, lifetimeMin: 1.0, lifetimeMax: 2.2,
+ shape: EmitterShape.Rectangle, shapeSize: { x: 1120, y: 620 },
+ speedMin: 5, speedMax: 25, startSizeMin: 3, startSizeMax: 9,
+ endSizeMin: 0, endSizeMax: 0, sizeEasing: ParticleEasing.EaseInOut,
+ startColor: { r: 1, g: 1, b: 0.8, a: 1 }, endColor: { r: 0.6, g: 0.8, b: 1, a: 0 },
+ angularVelocityMin: -90, angularVelocityMax: 90 } },
+ ],
},
];
-// The pool size the follow emitter is authored with — big enough for the
-// highest-rate preset (Fountain: 120/s × ~2s life). Kept constant across presets
-// because changing maxParticles mid-run does not resize an existing pool.
-export const FOLLOW_MAX_PARTICLES = 600;
+export const SHOWCASE_COUNT = SHOWCASES.length;
-// A one-shot firework spawned at the cursor on left-click. duration must be > 0
-// (the sim only emits while elapsed < duration), and a huge burstInterval keeps
-// it to a single burst; getAliveCount() then drives despawn once it fades out.
+// A one-shot firework spawned at the cursor on a click in empty space. duration
+// must be > 0 (emission runs only while elapsed < duration); a huge burstInterval
+// keeps it to one burst; getAliveCount() then drives despawn once it fades.
export const BURST: Partial<ParticleEmitterData> = {
rate: 0, burstCount: 64, burstInterval: 999, duration: 0.1,
looping: false, playOnStart: true, maxParticles: 140,
shape: EmitterShape.Point, speedMin: 180, speedMax: 440,
- lifetimeMin: 0.7, lifetimeMax: 1.5, angleSpreadMin: 0, angleSpreadMax: 360,
- startSizeMin: 6, startSizeMax: 12, endSizeMin: 0, endSizeMax: 0, sizeEasing: ParticleEasing.EaseOut,
+ lifetimeMin: 0.7, lifetimeMax: 1.5, startSizeMin: 6, startSizeMax: 12,
+ endSizeMin: 0, endSizeMax: 0, sizeEasing: ParticleEasing.EaseOut,
startColor: { r: 1, g: 0.9, b: 0.4, a: 1 }, endColor: { r: 1, g: 0.3, b: 0.1, a: 0 },
- gravity: { x: 0, y: -160 }, damping: 0.4, blendMode: BlendMode.Additive, layer: 5,
+ gravity: { x: 0, y: -160 }, damping: 0.4, layer: 5,
};
-// Copy a preset's look onto a live emitter (scalar-by-scalar so the ECS proxy's
-// nested Vec2/Color fields are written in place). New particles pick it up next
-// frame; particles already alive keep the look they were born with.
-export function applyPreset(e: ParticleEmitterData, p: Preset): void {
- e.rate = p.rate;
- e.lifetimeMin = p.lifetimeMin;
- e.lifetimeMax = p.lifetimeMax;
- e.shape = p.shape;
- e.shapeRadius = p.shapeRadius;
- e.shapeAngle = p.shapeAngle;
- e.speedMin = p.speedMin;
- e.speedMax = p.speedMax;
- e.angleSpreadMin = p.angleSpreadMin;
- e.angleSpreadMax = p.angleSpreadMax;
- e.startSizeMin = p.startSizeMin;
- e.startSizeMax = p.startSizeMax;
- e.endSizeMin = p.endSizeMin;
- e.endSizeMax = p.endSizeMax;
- e.sizeEasing = p.sizeEasing;
- e.startColor.r = p.startColor.r;
- e.startColor.g = p.startColor.g;
- e.startColor.b = p.startColor.b;
- e.startColor.a = p.startColor.a;
- e.endColor.r = p.endColor.r;
- e.endColor.g = p.endColor.g;
- e.endColor.b = p.endColor.b;
- e.endColor.a = p.endColor.a;
- e.colorEasing = p.colorEasing;
- e.angularVelocityMin = p.angularVelocityMin;
- e.angularVelocityMax = p.angularVelocityMax;
- e.gravity.x = p.gravity.x;
- e.gravity.y = p.gravity.y;
- e.damping = p.damping;
- e.blendMode = p.blendMode;
+// Spawn every emitter of a showcase, tagged so they can be despawned together.
+// `layer: 5` keeps particles above the backdrop; `texture` is the handle read
+// from the scene's TexHolder sprite.
+export function spawnShowcase(cmds: CommandsInstance, index: number, texture: number): void {
+ for (const emitter of SHOWCASES[index].emitters) {
+ cmds.spawn()
+ .insert(Transform, { position: { x: emitter.x, y: emitter.y, z: 0 } })
+ .insert(ParticleEmitter, { layer: 5, texture, ...emitter.data })
+ .insert(ShowcaseEmitter, {});
+ }
}
diff --git a/examples/particle-demo/src/main.ts b/examples/particle-demo/src/main.ts
index 8254437c3..9e3feb5e7 100644
--- a/examples/particle-demo/src/main.ts
+++ b/examples/particle-demo/src/main.ts
@@ -1,25 +1,23 @@
-// Particle Effects — an interactive tour of the ParticleEmitter component and
-// the `Particle` runtime API.
+// Particle Effects — a gallery of the engine's ParticleEmitter, paged with
+// on-screen buttons.
//
-// • Move the mouse — a World-space emitter follows the cursor, leaving trails.
-// • 1–6 / Space — switch its preset: Fire, Sparks, Smoke, Magic, Snow,
-// Fountain (each remixes the emitter's shape, velocity, colour, size, gravity
-// and blend mode live).
-// • Left-click — spawn a one-shot firework burst at the cursor.
-// • P — pause / resume the follow stream (Particle.stop / play).
+// • Prev / Next buttons (or ← / → / Space) switch between six composed
+// showcases: Campfire, Fireworks, Magic Portal, Fountain, Snowfall, Sparkles.
+// • Left-click empty space — throw a one-shot firework at the cursor.
//
-// Emitters are plain ECS components simulated by the built-in ParticleSystem;
-// systems here only start them, mutate their fields, and use the `Particle`
-// resource for play/stop and getAliveCount-driven cleanup.
+// Each showcase is a group of ParticleEmitter entities spawned on switch and
+// despawned on the next switch — one scene, no reloads, so the UI and camera
+// persist. Buttons are plain UI entities; a click surfaces as a 'click' event
+// the switch system reads. See systems/switch.ts.
import { addStartupSystem, addSystemToSchedule, Schedule } from 'esengine';
import './components';
import { setupSystem } from './systems/setup';
-import { followSystem } from './systems/follow';
-import { controlSystem } from './systems/control';
+import { switchSystem } from './systems/switch';
+import { sparkSystem } from './systems/spark';
import { cleanupSystem } from './systems/cleanup';
addStartupSystem(setupSystem);
-addSystemToSchedule(Schedule.Update, followSystem);
-addSystemToSchedule(Schedule.Update, controlSystem);
+addSystemToSchedule(Schedule.Update, switchSystem);
+addSystemToSchedule(Schedule.Update, sparkSystem);
addSystemToSchedule(Schedule.Update, cleanupSystem);
diff --git a/examples/particle-demo/src/state.ts b/examples/particle-demo/src/state.ts
new file mode 100644
index 000000000..0117b67b0
--- /dev/null
+++ b/examples/particle-demo/src/state.ts
@@ -0,0 +1,3 @@
+// Which showcase is on screen. Shared between the setup system (spawns the first
+// one) and the switch system (pages through them), so it lives in one module.
+export const state = { current: 0 };
diff --git a/examples/particle-demo/src/systems/control.ts b/examples/particle-demo/src/systems/control.ts
deleted file mode 100644
index b1b755581..000000000
--- a/examples/particle-demo/src/systems/control.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-import {
- defineSystem, Query, Mut, Res, Commands,
- Input, UICameraInfo, Transform, Particle, ParticleAPI, ParticleEmitter,
-} from 'esengine';
-import type { UICameraData } from 'esengine';
-import { Follow, Burst } from '../components';
-import { PRESETS, BURST, applyPreset } from '../config';
-
-// Current preset index and whether the stream is paused — module state, since a
-// keypress this frame changes what the follow emitter does next frame.
-let current = 0;
-let paused = false;
-
-// All the input for the demo: 1–6 / Space pick a preset (applied live to the
-// follow emitter), P toggles emission via the Particle resource, and left-click
-// spawns a firework at the cursor that reuses the follow emitter's texture.
-export const controlSystem = defineSystem(
- [Res(Input), Res(Particle), Res(UICameraInfo), Query(Mut(ParticleEmitter), Follow), Commands()],
- (input, particles: ParticleAPI, camera: UICameraData, follows, cmds) => {
- let next = -1;
- if (input.isKeyPressed('Space')) next = (current + 1) % PRESETS.length;
- for (let i = 0; i < PRESETS.length; i++) {
- if (input.isKeyPressed(`Digit${i + 1}`)) next = i;
- }
- const togglePause = input.isKeyPressed('KeyP');
- const click = camera.valid && input.isMouseButtonPressed(0);
-
- for (const [entity, emitter] of follows) {
- if (next >= 0) {
- current = next;
- applyPreset(emitter, PRESETS[current]);
- }
- if (togglePause) {
- paused = !paused;
- if (paused) particles.stop(entity); else particles.play(entity);
- }
- if (click) {
- cmds.spawn()
- .insert(Transform, { position: { x: camera.worldMouseX, y: camera.worldMouseY, z: 0 } })
- .insert(ParticleEmitter, { ...BURST, texture: emitter.texture })
- .insert(Burst, { age: 0 });
- }
- }
- },
- { name: 'ControlSystem' },
-);
diff --git a/examples/particle-demo/src/systems/follow.ts b/examples/particle-demo/src/systems/follow.ts
deleted file mode 100644
index d2888f4a7..000000000
--- a/examples/particle-demo/src/systems/follow.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import {
- defineSystem, Query, Mut, Res, Transform, UICameraInfo,
-} from 'esengine';
-import type { UICameraData } from 'esengine';
-import { Follow } from '../components';
-
-// Pin the follow emitter to the world-space cursor. Because it simulates in
-// World space, particles stay where they were born and streak out behind the
-// moving cursor.
-export const followSystem = defineSystem(
- [Query(Mut(Transform), Follow), Res(UICameraInfo)],
- (follows, camera: UICameraData) => {
- if (!camera.valid) return;
- for (const [, transform] of follows) {
- transform.position.x = camera.worldMouseX;
- transform.position.y = camera.worldMouseY;
- }
- },
- { name: 'FollowSystem' },
-);
diff --git a/examples/particle-demo/src/systems/setup.ts b/examples/particle-demo/src/systems/setup.ts
index a5d1f9507..baf65f566 100644
--- a/examples/particle-demo/src/systems/setup.ts
+++ b/examples/particle-demo/src/systems/setup.ts
@@ -1,15 +1,17 @@
-import { defineSystem, Query, Mut, ParticleEmitter } from 'esengine';
-import { Follow } from '../components';
-import { PRESETS, applyPreset } from '../config';
+import { defineSystem, Query, Mut, Commands, Sprite, Text } from 'esengine';
+import { TexHolder, TitleLabel } from '../components';
+import { SHOWCASES, spawnShowcase } from '../config';
+import { state } from '../state';
-// Give the scene's follow emitter its starting look (the first preset) once at
-// startup, so config.ts is the single source of truth for how a preset looks.
+// At startup: read the particle texture handle off the invisible TexHolder
+// sprite, spawn the first showcase's emitters, and set the title.
export const setupSystem = defineSystem(
- [Query(Mut(ParticleEmitter), Follow)],
- (follows) => {
- for (const [, emitter] of follows) {
- applyPreset(emitter, PRESETS[0]);
- }
+ [Query(Sprite, TexHolder), Query(Mut(Text), TitleLabel), Commands()],
+ (holders, titles, cmds) => {
+ let texture = 0;
+ for (const [, sprite] of holders) texture = sprite.texture;
+ spawnShowcase(cmds, state.current, texture);
+ for (const [, text] of titles) text.content = SHOWCASES[state.current].name;
},
{ name: 'SetupSystem' },
);
diff --git a/examples/particle-demo/src/systems/spark.ts b/examples/particle-demo/src/systems/spark.ts
new file mode 100644
index 000000000..6b12e9d97
--- /dev/null
+++ b/examples/particle-demo/src/systems/spark.ts
@@ -0,0 +1,23 @@
+import {
+ defineSystem, Query, Res, Commands,
+ Input, UICameraInfo, Transform, Sprite, ParticleEmitter,
+} from 'esengine';
+import type { UICameraData } from 'esengine';
+import { TexHolder, Burst } from '../components';
+import { BURST } from '../config';
+
+// Clicking empty space (not a button — isPointerOverUI gates that out) throws a
+// one-shot firework at the cursor, reusing the shared particle texture.
+export const sparkSystem = defineSystem(
+ [Res(Input), Res(UICameraInfo), Query(Sprite, TexHolder), Commands()],
+ (input, camera: UICameraData, holders, cmds) => {
+ if (!camera.valid || !input.isMouseButtonPressed(0) || input.isPointerOverUI()) return;
+ let texture = 0;
+ for (const [, sprite] of holders) texture = sprite.texture;
+ cmds.spawn()
+ .insert(Transform, { position: { x: camera.worldMouseX, y: camera.worldMouseY, z: 0 } })
+ .insert(ParticleEmitter, { ...BURST, texture })
+ .insert(Burst, { age: 0 });
+ },
+ { name: 'SparkSystem' },
+);
diff --git a/examples/particle-demo/src/systems/switch.ts b/examples/particle-demo/src/systems/switch.ts
new file mode 100644
index 000000000..cf3c0e3f5
--- /dev/null
+++ b/examples/particle-demo/src/systems/switch.ts
@@ -0,0 +1,40 @@
+import {
+ defineSystem, Query, Mut, Res, Commands,
+ Input, UIEvents, Sprite, Text,
+} from 'esengine';
+import type { UIEventQueue } from 'esengine';
+import { TexHolder, TitleLabel, PrevButton, NextButton, ShowcaseEmitter } from '../components';
+import { SHOWCASES, SHOWCASE_COUNT, spawnShowcase } from '../config';
+import { state } from '../state';
+
+// Page through the showcases with the Prev/Next buttons or the arrow keys /
+// Space. A click on a button surfaces as a UI 'click' event targeting it. On a
+// change, despawn the whole current showcase and spawn the next one, then
+// retitle.
+export const switchSystem = defineSystem(
+ [
+ Res(Input), Res(UIEvents),
+ Query(PrevButton), Query(NextButton),
+ Query(Sprite, TexHolder), Query(ShowcaseEmitter), Query(Mut(Text), TitleLabel),
+ Commands(),
+ ],
+ (input, events: UIEventQueue, prevs, nexts, holders, emitters, titles, cmds) => {
+ let dir = 0;
+ if (input.isKeyPressed('ArrowRight') || input.isKeyPressed('Space')) dir = 1;
+ else if (input.isKeyPressed('ArrowLeft')) dir = -1;
+
+ const clicks = events.query('click');
+ for (const [entity] of nexts) if (clicks.some((c) => c.target === entity)) dir = 1;
+ for (const [entity] of prevs) if (clicks.some((c) => c.target === entity)) dir = -1;
+ if (dir === 0) return;
+
+ state.current = (state.current + dir + SHOWCASE_COUNT) % SHOWCASE_COUNT;
+ for (const [entity] of emitters) cmds.despawn(entity);
+
+ let texture = 0;
+ for (const [, sprite] of holders) texture = sprite.texture;
+ spawnShowcase(cmds, state.current, texture);
+ for (const [, text] of titles) text.content = SHOWCASES[state.current].name;
+ },
+ { name: 'SwitchSystem' },
+);
diff --git a/examples/particle-demo/thumbnail.png b/examples/particle-demo/thumbnail.png
index ff7dac802..8b501062b 100644
Binary files a/examples/particle-demo/thumbnail.png and b/examples/particle-demo/thumbnail.png differ