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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
examples(particle-demo): page through effect showcases with UI buttons
yhhf55051d94d52
diff --git a/examples/particle-demo/README.md b/examples/particle-demo/README.mdindex 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), TexHoldertextures/particle.png # soft radial particle spritesrc/- 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 indexsystems/- 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.essceneindex 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.esprojectindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsdeleted file mode 100644index 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.tsdeleted file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.pngindex ff7dac802..8b501062b 100644Binary files a/examples/particle-demo/thumbnail.png and b/examples/particle-demo/thumbnail.png differ