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.

feat(editor): particle emitter gizmo - see + aim emitters on the canvas

yhhab7a2a12a8aa
diff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.ts
index 2303cceb6..e6f0b8a35 100644
--- a/desktop/src/engine/ViewportController.ts
+++ b/desktop/src/engine/ViewportController.ts
@@ -2,6 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import {
Camera, CameraView, EditorView, Light2D, Sprite, Transform, Canvas, BoxCollider, CircleCollider,
+ ParticleEmitter,
UINode, UICameraInfo, screenToUiWorld, uiWorldToScreen, uiPickAllWorld, type UICameraData,
} from 'esengine';
import type { EntityId } from '@/types';
@@ -501,4 +502,80 @@ export const ViewportController = {
if (!center || !edge) return null;
return { kind: 'circle', cx: center.x, cy: center.y, r: Math.hypot(edge.x - center.x, edge.y - center.y) };
},
+
+ /** Ids of entities carrying a ParticleEmitter — the emitter-gizmo set. */
+ particleEmitterIds(): EntityId[] {
+ const world = EngineHost.world;
+ if (!world) return [];
+ const out: EntityId[] = [];
+ for (const e of world.getAllEntities()) {
+ if (world.has(e, ParticleEmitter) && world.has(e, Transform)) out.push(e);
+ }
+ return out;
+ },
+
+ /**
+ * Screen-space gizmo geometry for a ParticleEmitter's SPAWN shape. Particles don't
+ * simulate in edit mode, so the emitter is otherwise invisible on the canvas — this
+ * outlines WHERE particles are born (and, for a Cone, which way they aim): a marker
+ * (Point), a radius circle (Circle), an oriented box (Rectangle), or an aim wedge
+ * (Cone, local up ±shapeAngle/2 out to shapeRadius). Sizes are world pixels
+ * (shapeRadius/shapeSize match world position — NO pixelsPerUnit, unlike colliders),
+ * projected through the camera like the collider gizmo. `on` folds the enable so a
+ * disabled emitter dims.
+ */
+ getParticleEmitterGizmo(
+ id: EntityId,
+ ): { cx: number; cy: number; kind: 'point' | 'circle' | 'poly'; r: number; pts: Array<{ x: number; y: number }>; on: boolean } | null {
+ const world = EngineHost.world;
+ if (!world || !world.valid(id) || !world.has(id, ParticleEmitter) || !world.has(id, Transform)) return null;
+ const t = world.get(id, Transform);
+ const p = world.get(id, ParticleEmitter) as {
+ shape: number; shapeRadius: number; shapeSize: { x: number; y: number }; shapeAngle: number; enabled: boolean;
+ };
+ const center = this.worldToClient(t.worldPosition.x, t.worldPosition.y);
+ if (!center) return null;
+ const on = p.enabled !== false;
+ const rot = quatAngleZ(t.worldRotation as { w: number; x: number; y: number; z: number });
+ const cos = Math.cos(rot);
+ const sin = Math.sin(rot);
+ // Rotate an emitter-local offset (world px) into world space — mirrors the sim's
+ // world-space direction rotation (ParticleSystem::emitParticles).
+ const toWorld = (lx: number, ly: number) => ({
+ x: t.worldPosition.x + lx * cos - ly * sin,
+ y: t.worldPosition.y + lx * sin + ly * cos,
+ });
+
+ switch (p.shape) {
+ case 1: { // Circle — spawn disk of shapeRadius
+ const edge = this.worldToClient(t.worldPosition.x + p.shapeRadius, t.worldPosition.y);
+ const r = edge ? Math.hypot(edge.x - center.x, edge.y - center.y) : 0;
+ return { cx: center.x, cy: center.y, kind: 'circle', r, pts: [], on };
+ }
+ case 2: { // Rectangle — oriented spawn box of shapeSize
+ const corners = obbCorners({
+ cx: t.worldPosition.x, cy: t.worldPosition.y,
+ hw: Math.abs(p.shapeSize.x) * 0.5, hh: Math.abs(p.shapeSize.y) * 0.5, rot,
+ }).map(([wx, wy]) => this.worldToClient(wx, wy));
+ if (corners.some((s) => !s)) return null;
+ return { cx: center.x, cy: center.y, kind: 'poly', r: 0, pts: corners.map((s) => ({ x: s!.x, y: s!.y })), on };
+ }
+ case 3: { // Cone — aim wedge: local up (0,1) swept ±shapeAngle/2, out to shapeRadius
+ const half = Math.max(0, p.shapeAngle) * 0.5 * (Math.PI / 180);
+ const rad = p.shapeRadius > 0 ? p.shapeRadius : 60;
+ const STEPS = 12;
+ const pts: Array<{ x: number; y: number }> = [{ x: center.x, y: center.y }]; // apex
+ for (let i = 0; i <= STEPS; i++) {
+ const a = -half + (2 * half) * (i / STEPS);
+ const w = toWorld(Math.sin(a) * rad, Math.cos(a) * rad);
+ const s = this.worldToClient(w.x, w.y);
+ if (!s) return null;
+ pts.push({ x: s.x, y: s.y });
+ }
+ return { cx: center.x, cy: center.y, kind: 'poly', r: 0, pts, on };
+ }
+ default: // Point (0) — a marker at the emitter (the clickable icon)
+ return { cx: center.x, cy: center.y, kind: 'point', r: 0, pts: [], on };
+ }
+ },
};
diff --git a/desktop/src/panels/Viewport.tsx b/desktop/src/panels/Viewport.tsx
index f90670984..f626aeac5 100644
--- a/desktop/src/panels/Viewport.tsx
+++ b/desktop/src/panels/Viewport.tsx
@@ -4,7 +4,7 @@ import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'reac
import type { PointerEvent as ReactPointerEvent, DragEvent as ReactDragEvent, ReactNode } from 'react';
import {
MousePointer2, Move, RotateCw, Scale3d, Grid3x3, Eye, Frame,
- Camera, Check, ChevronDown, Loader2, TriangleAlert, Lightbulb, Globe, Crosshair, type LucideIcon,
+ Camera, Check, ChevronDown, Loader2, TriangleAlert, Lightbulb, Sparkles, Globe, Crosshair, type LucideIcon,
} from 'lucide-react';
import { useEditorStore } from '@/store/editorStore';
import { useSelection } from '@/store/selectionStore';
@@ -329,6 +329,14 @@ export function Viewport() {
() => (engine.status === 'ready' && showColliders ? ViewportController.colliderIds() : []),
[structRev, engine.status, showColliders],
);
+ // Particle emitters don't simulate in edit mode — outline each emitter's spawn
+ // shape (point / circle / rect / cone) + a clickable icon, positioned by the rAF.
+ const particleRefs = useRef(new Map<number, HTMLDivElement | null>());
+ const particleShapeRefs = useRef(new Map<number, SVGSVGElement | null>());
+ const particleIds = useMemo(
+ () => (engine.status === 'ready' ? ViewportController.particleEmitterIds() : []),
+ [structRev, engine.status],
+ );
// Mount the live engine canvas into the stage; it survives panel re-docking.
useEffect(() => {
@@ -579,6 +587,41 @@ export function Viewport() {
wrap.style.visibility = 'hidden'; // an invisible bulb must not swallow clicks
}
}
+
+ // Particle-emitter gizmos — a clickable icon at the emitter + its spawn-shape
+ // outline (cone wedge / circle / box / point), so an otherwise-invisible emitter
+ // is placeable and aimable in edit mode. Same edit-mode + gizmos-on gate.
+ for (const [pid, wrap] of particleRefs.current) {
+ if (!wrap) continue;
+ const pg = camsOn ? ViewportController.getParticleEmitterGizmo(pid) : null;
+ const svg = particleShapeRefs.current.get(pid);
+ const poly = svg ? (svg.querySelector('.pe-poly') as SVGPolygonElement | null) : null;
+ const circ = svg ? (svg.querySelector('.pe-circle') as SVGCircleElement | null) : null;
+ if (pg) {
+ wrap.style.opacity = pg.on ? '1' : '0.4';
+ wrap.style.visibility = 'visible';
+ wrap.style.transform = `translate(${pg.cx}px, ${pg.cy}px)`;
+ if (pg.kind === 'poly' && poly) {
+ poly.setAttribute('points', pg.pts.map((p) => `${p.x},${p.y}`).join(' '));
+ poly.style.opacity = pg.on ? '0.9' : '0.4';
+ if (circ) circ.style.opacity = '0';
+ } else if (pg.kind === 'circle' && circ) {
+ circ.setAttribute('cx', String(pg.cx));
+ circ.setAttribute('cy', String(pg.cy));
+ circ.setAttribute('r', String(pg.r));
+ circ.style.opacity = pg.on ? '0.9' : '0.4';
+ if (poly) poly.style.opacity = '0';
+ } else {
+ if (poly) poly.style.opacity = '0';
+ if (circ) circ.style.opacity = '0';
+ }
+ } else {
+ wrap.style.opacity = '0';
+ wrap.style.visibility = 'hidden';
+ if (poly) poly.style.opacity = '0';
+ if (circ) circ.style.opacity = '0';
+ }
+ }
PerfMonitor.mark('gizmo.update', perfT0);
};
raf = requestAnimationFrame(tick);
@@ -860,6 +903,50 @@ export function Viewport() {
</svg>
))}
+ {/* Particle-emitter gizmos: a clickable icon (select-to-identify, like a light)
+ + a spawn-shape overlay SVG (cone wedge / circle / box), positioned by the rAF. */}
+ {particleIds.map((id) => {
+ const src = SceneModel.sourceFor(id);
+ const name = src != null ? SceneModel.entityBySource(src)?.name : undefined;
+ return (
+ <div
+ key={id}
+ ref={(el) => {
+ if (el) particleRefs.current.set(id, el);
+ else particleRefs.current.delete(id);
+ }}
+ className="viewport__particle-gizmo"
+ >
+ <span
+ className="viewport__particle-hit"
+ role="button"
+ title={name}
+ onPointerDown={(e) => {
+ if (e.button !== 0 || src == null) return;
+ e.stopPropagation();
+ useSelection.getState().select(src);
+ }}
+ >
+ <Sparkles className="viewport__particle-icon" size={14} strokeWidth={1.9} />
+ </span>
+ </div>
+ );
+ })}
+ {particleIds.map((id) => (
+ <svg
+ key={id}
+ ref={(el) => {
+ if (el) particleShapeRefs.current.set(id, el);
+ else particleShapeRefs.current.delete(id);
+ }}
+ className="viewport__particle-shape"
+ aria-hidden="true"
+ >
+ <polygon className="pe-poly" points="" />
+ <circle className="pe-circle" cx="0" cy="0" r="0" />
+ </svg>
+ ))}
+
{/* Play In Viewport: the realm iframe fills the stage; a thin badge marks PIE. */}
{playInViewport && (
<div className="viewport__play">
diff --git a/desktop/src/theme/app.css b/desktop/src/theme/app.css
index 307193331..75164f61f 100644
--- a/desktop/src/theme/app.css
+++ b/desktop/src/theme/app.css
@@ -774,6 +774,56 @@ body.thumb-capture .viewport__play-stop {
opacity: 0;
}
+/* Particle-emitter gizmo: a clickable icon at the emitter + its spawn-shape overlay.
+ The icon wrapper is translate()'d to the emitter; the shape SVG spans the viewport
+ and the rAF writes absolute canvas-relative px into the polygon/circle. */
+.viewport__particle-gizmo {
+ position: absolute;
+ left: 0;
+ top: 0;
+ z-index: 2;
+ pointer-events: none;
+ will-change: transform;
+ transition: opacity 0.1s;
+ color: #ffb454;
+}
+.viewport__particle-hit {
+ position: absolute;
+ left: 0;
+ top: 0;
+ margin: -11px 0 0 -11px;
+ width: 22px;
+ height: 22px;
+ display: grid;
+ place-items: center;
+ pointer-events: auto;
+ cursor: pointer;
+}
+.viewport__particle-icon {
+ display: block;
+ filter: drop-shadow(0 0 2px rgba(0, 0, 0, 0.8));
+ transition: transform 0.1s;
+}
+.viewport__particle-hit:hover .viewport__particle-icon {
+ transform: scale(1.2);
+}
+.viewport__particle-shape {
+ position: absolute;
+ inset: 0;
+ width: 100%;
+ height: 100%;
+ z-index: 2;
+ pointer-events: none;
+ overflow: visible;
+}
+.viewport__particle-shape .pe-poly,
+.viewport__particle-shape .pe-circle {
+ fill: rgba(255, 180, 84, 0.05);
+ stroke: #ffb454;
+ stroke-width: 1.5;
+ opacity: 0;
+}
+
.viewport__overlay {
position: absolute;
display: flex;
diff --git a/examples/particle-demo/assets/scenes/static-emitters.esscene b/examples/particle-demo/assets/scenes/static-emitters.esscene
new file mode 100644
index 000000000..f400a5207
--- /dev/null
+++ b/examples/particle-demo/assets/scenes/static-emitters.esscene
@@ -0,0 +1,84 @@
+{
+ "version": "1.0",
+ "name": "Static Emitters",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },
+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0, "backgroundColor": { "r": 0.06, "g": 0.07, "b": 0.10, "a": 1 } } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "ConeFountain",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": -210, "y": -150, "z": 0 } } },
+ {
+ "type": "ParticleEmitter",
+ "data": {
+ "texture": "@uuid:24cb4e0f-7c75-4df4-9a4d-58480ee405c0",
+ "shape": 3, "shapeAngle": 28, "shapeRadius": 110,
+ "rate": 60, "lifetimeMin": 1.4, "lifetimeMax": 2.0,
+ "speedMin": 220, "speedMax": 320, "gravity": { "x": 0, "y": -380 },
+ "startSizeMin": 22, "startSizeMax": 30, "endSizeMin": 4, "endSizeMax": 8,
+ "startColor": { "r": 1.0, "g": 0.72, "b": 0.24, "a": 1 },
+ "endColor": { "r": 1.0, "g": 0.22, "b": 0.12, "a": 0 }
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 2,
+ "name": "CircleBurst",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 20, "y": 10, "z": 0 } } },
+ {
+ "type": "ParticleEmitter",
+ "data": {
+ "texture": "@uuid:24cb4e0f-7c75-4df4-9a4d-58480ee405c0",
+ "shape": 1, "shapeRadius": 80,
+ "rate": 50, "lifetimeMin": 1.2, "lifetimeMax": 1.8,
+ "speedMin": 90, "speedMax": 150, "gravity": { "x": 0, "y": 0 },
+ "startSizeMin": 16, "startSizeMax": 24, "endSizeMin": 2, "endSizeMax": 6,
+ "startColor": { "r": 0.35, "g": 0.82, "b": 1.0, "a": 1 },
+ "endColor": { "r": 0.12, "g": 0.34, "b": 0.92, "a": 0 }
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 3,
+ "name": "RectRain",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 220, "y": 170, "z": 0 } } },
+ {
+ "type": "ParticleEmitter",
+ "data": {
+ "texture": "@uuid:24cb4e0f-7c75-4df4-9a4d-58480ee405c0",
+ "shape": 2, "shapeSize": { "x": 190, "y": 24 },
+ "rate": 55, "lifetimeMin": 1.6, "lifetimeMax": 2.4,
+ "speedMin": 40, "speedMax": 90, "angleSpreadMin": 250, "angleSpreadMax": 290,
+ "gravity": { "x": 0, "y": -140 },
+ "startSizeMin": 12, "startSizeMax": 18, "endSizeMin": 3, "endSizeMax": 6,
+ "startColor": { "r": 0.56, "g": 1.0, "b": 0.46, "a": 1 },
+ "endColor": { "r": 0.2, "g": 0.62, "b": 0.24, "a": 0 }
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/examples/particle-demo/assets/scenes/static-emitters.esscene.meta b/examples/particle-demo/assets/scenes/static-emitters.esscene.meta
new file mode 100644
index 000000000..4f30fcea7
--- /dev/null
+++ b/examples/particle-demo/assets/scenes/static-emitters.esscene.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "2ab1e400-7c75-4df4-9a4d-58480ee40501",
+ "version": "2.0",
+ "type": "scene",
+ "importer": { "autoMigrate": true }
+}
diff --git a/examples/particle-demo/src/systems/setup.ts b/examples/particle-demo/src/systems/setup.ts
index baf65f566..f1771483d 100644
--- a/examples/particle-demo/src/systems/setup.ts
+++ b/examples/particle-demo/src/systems/setup.ts
@@ -9,7 +9,13 @@ export const setupSystem = defineSystem(
[Query(Sprite, TexHolder), Query(Mut(Text), TitleLabel), Commands()],
(holders, titles, cmds) => {
let texture = 0;
- for (const [, sprite] of holders) texture = sprite.texture;
+ let hasHolder = false;
+ for (const [, sprite] of holders) { texture = sprite.texture; hasHolder = true; }
+ // The code-driven gallery depends on the main scene's TexHolder (particle
+ // texture) + UI. A scene without them — e.g. the static-emitters showcase,
+ // which authors its own ParticleEmitter entities — skips the gallery so the
+ // two paths don't overlap.
+ if (!hasHolder) return;
spawnShowcase(cmds, state.current, texture);
for (const [, text] of titles) text.content = SHOWCASES[state.current].name;
},