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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { App, Plugin } from '../app/app';
import { defineSystem, Schedule } from '../ecs/system';
import { Res } from '../ecs/resource';
import { Time, type TimeData } from '../ecs/resource';
import { fxPreviewOrPlayMode } from '../ecs/env';
import type { CppRegistry } from '../wasm';
import { engineApi } from '../ecs/bridge/engineApi';
import { registerSceneComponentCodec } from '../scene/scene';
import { Particle, ParticleAPI } from './ParticleAPI';
import { particleQueryResolver } from './ParticleCollisionBridge';
import { ParticleCollisionEvent, type ParticleCollisionEventPayload } from './collision';
import { EventWriter, type EventWriterInstance } from '../ecs/event';
import { Draw } from '../render/draw';
import { registerScopedDrawCallback, unregisterDrawCallback } from '../render/customDraw';
import { bakeGradient, type Gradient } from './gradient';
import { bakeCurve, type Curve } from './curve';
let overlayId = 0;
export class ParticlePlugin implements Plugin {
name = 'particle';
/** Entity → authored color-over-life gradient (out-of-band; baked to the C++ LUT). */
private readonly gradients_ = new Map<number, Gradient>();
/** Entity → authored size-over-life curve (out-of-band; baked to the C++ LUT). */
private readonly sizeCurves_ = new Map<number, Curve>();
/** Entity → authored burst schedule (out-of-band; handed to the sim as (time, count) pairs). */
private readonly bursts_ = new Map<number, { time: number; count: number }[]>();
private overlay_: string | null = null;
private offDespawn_: (() => void) | null = null;
build(app: App): void {
// Whichever core is present; a core built without ES_ENABLE_PARTICLES simply
// answers no particle_* entry point, which the API already tolerates.
// `?? {}`: an app with no engine core (a test, a pure-logic host) still gets
// the resource, and every call through it no-ops.
const engine = engineApi(app) ?? {};
const registry = app.world.getCppRegistry() as CppRegistry;
const api = new ParticleAPI(engine, registry, particleQueryResolver(app));
app.insertResource(Particle, api);
this.overlay_ = `particle-collision:${++overlayId}`;
registerScopedDrawCallback(this.overlay_,registry,()=>{
if (!api.debugNormals) return;
for (const hit of api.collisionContacts) {
Draw.line3D({x:hit.x,y:hit.y,z:hit.z},
{x:hit.x+hit.normalX*20,y:hit.y+hit.normalY*20,z:hit.z+hit.normalZ*20},
{r:.2,g:.9,b:.7,a:1},1);
}
});
// The color gradient is authored as stops in the component data but isn't a
// C++ field — carry it out-of-band and bake it into the sim's LUT on load.
const gradients = this.gradients_;
const sizeCurves = this.sizeCurves_;
const bursts = this.bursts_;
this.offDespawn_ = app.world.onDespawn((entity) => {
if (gradients.delete(entity)) api.setColorLut(entity, null);
if (sizeCurves.delete(entity)) api.setSizeLut(entity, null);
if (bursts.delete(entity)) api.setBursts(entity, null);
});
registerSceneComponentCodec('ParticleEmitter', {
outOfBandFields: ['colorGradient', 'sizeCurve', 'bursts'],
importData: (entity, outOfBand) => {
const g = outOfBand.colorGradient as Gradient | undefined;
api.setColorLut(entity, bakeGradient(g));
if (g?.stops?.length) gradients.set(entity, g);
else gradients.delete(entity);
const c = outOfBand.sizeCurve as Curve | undefined;
api.setSizeLut(entity, bakeCurve(c));
if (c?.keys?.length) sizeCurves.set(entity, c);
else sizeCurves.delete(entity);
const b = outOfBand.bursts as { time: number; count: number }[] | undefined;
api.setBursts(entity, b ?? null);
if (b?.length) bursts.set(entity, b);
else bursts.delete(entity);
},
exportData: (entity, data) => {
const g = gradients.get(entity);
if (g) data.colorGradient = g;
const c = sizeCurves.get(entity);
if (c) data.sizeCurve = c;
const b = bursts.get(entity);
if (b) data.bursts = b;
},
});
// Particle advance is gameplay — frozen in editor edit mode, runs in
// play mode / standalone runtime (matches animation/physics/timeline).
// The FX edit-preview flag is the one authoring exception (env.ts).
app.addSystemToSchedule(Schedule.Update, defineSystem(
[Res(Time), Res(Particle), EventWriter(ParticleCollisionEvent)],
(time: TimeData, particle: ParticleAPI, events: EventWriterInstance<ParticleCollisionEventPayload>) => {
particle.update(time.delta);
for (const hit of particle.collisionEvents) events.send(hit);
},
{ name: 'ParticleSystem' }
), { runIf: fxPreviewOrPlayMode });
}
cleanup(): void {
if (this.overlay_) unregisterDrawCallback(this.overlay_);
this.overlay_ = null;
this.offDespawn_?.();
this.offDespawn_ = null;
this.gradients_.clear();
this.sizeCurves_.clear();
}
}
export const particlePlugin = new ParticlePlugin();