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
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.tsindex 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 Teamimport {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.tsxindex 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 'reacimport 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.cssindex 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.esscenenew file mode 100644index 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.metanew file mode 100644index 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.tsindex 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;},