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
#pragma once
#include "../../core/Types.hpp"
#include "../../core/Reflection.hpp"
#include "../../math/Math.hpp"
#include "../../resource/Handle.hpp"
namespace esengine::ecs {
// Local +Y is the axis every directed shape points along, so an unrotated
// emitter aims up — where every 2D cone has always aimed. Values are serialized.
ES_ENUM(stability=beta)
enum class EmitterShape : i32 {
Point = 0,
Circle = 1,
Box = 2,
Cone = 3,
Sphere = 4,
Hemisphere = 5,
};
// Single source of the easing choice serialized by sizeEasing/colorEasing; the
// particle sim consumes it as particle::EasingType (alias) and the editor
// dropdown + TS const are EHT-generated from here.
ES_ENUM(stability=beta)
enum class ParticleEasing : i32 {
Linear = 0,
EaseIn = 1,
EaseOut = 2,
EaseInOut = 3,
};
/// How a particle's quad is turned. Billboard faces the view and spins by its own rotation; Stretched lays the quad's
/// long axis along the particle's velocity and lengthens it with speed — sparks, rain, streaks.
ES_ENUM(stability=beta)
enum class ParticleRenderMode : i32 {
Billboard = 0,
Stretched = 1,
};
ES_ENUM(stability=beta)
enum class SimulationSpace : i32 {
World = 0,
Local = 1,
};
// When a sub-emitter fires the referenced child emitter's burst: as each parent
// particle is born, dies, or collides. Serialized values remain stable.
ES_ENUM(stability=beta)
enum class SubEmitterTrigger : i32 {
Death = 0,
Birth = 1,
Collision = 2,
};
ES_ENUM(stability=beta)
enum class ParticleCollisionMode : i32 {
Floor = 0,
Physics2D = 1,
Physics3D = 2,
Depth = 3,
Sdf = 4,
};
ES_ENUM(stability=beta)
enum class ParticleCollisionFallback : i32 {
Floor = 0,
Skip = 1,
};
ES_COMPONENT(renderable=enabled, stability=beta)
struct ParticleEmitter {
// Emission
ES_PROPERTY(min=0, category=Emission)
f32 rate{10.0f};
ES_PROPERTY(min=0, step=1, category=Emission)
i32 burstCount{0};
ES_PROPERTY(min=0, category=Emission)
f32 burstInterval{1.0f};
ES_PROPERTY(min=0, category=Emission)
f32 duration{5.0f};
ES_PROPERTY(min=0, category=Emission, tooltip="How fast this emitter's own time runs: 2 plays it twice as fast, 0.5 at half, 0 holds it. Scales emission, lifetimes and motion alike.")
f32 simulationSpeed{1.0f};
ES_PROPERTY(min=0, category=Emission, tooltip="Seconds after the emitter starts playing before it emits anything. The duration counts from the end of the delay.")
f32 startDelay{0.0f};
ES_PROPERTY(category=Emission)
bool looping{true};
ES_PROPERTY(category=Emission)
bool playOnStart{true};
ES_PROPERTY(min=1, step=1, category=Emission)
i32 maxParticles{1000};
// Simulated by a compute kernel (WebGPU); elsewhere the emitter runs on the CPU, capped. Gravity, damping,
// noise, force fields, over-life curves, the floor plane, depth and distance-function collision,
// sub-emitters and trails apply; a Physics2D/Physics3D scene query is CPU-only.
ES_PROPERTY(category=Emission, tooltip="Simulate on the GPU (WebGPU compute). Falls back to a capped CPU simulation elsewhere. Sub-emitters, trails and physics collision are CPU-only.")
bool gpuSimulation{false};
// Lifetime
ES_PROPERTY(min=0, category=Lifetime)
f32 lifetimeMin{5.0f};
ES_PROPERTY(min=0, category=Lifetime)
f32 lifetimeMax{5.0f};
// Shape kind — i32 storage, dropdown generated from the EmitterShape enum.
ES_PROPERTY(enum=EmitterShape, category=Shape)
i32 shape{static_cast<i32>(EmitterShape::Cone)};
ES_PROPERTY(min=0, category=Shape, shown_when=shape:Circle|Cone|Sphere|Hemisphere)
f32 shapeRadius{100.0f};
// A filled VOLUME, not a surface: shapeSize.z of 0 is the flat rectangle every
// 2D emitter spawned from, so one field spells both.
ES_PROPERTY(category=Shape, shown_when=shape:Box)
glm::vec3 shapeSize{100.0f, 100.0f, 0.0f};
ES_PROPERTY(unit="°", category=Shape, shown_when=shape:Cone)
f32 shapeAngle{25.0f};
// Velocity
ES_PROPERTY(category=Velocity)
f32 speedMin{500.0f};
ES_PROPERTY(category=Velocity)
f32 speedMax{500.0f};
// Aim for the shapes that HAVE no aim of their own (Point, Box): an angle in
// the emitter's local XY plane. Circle, Cone, Sphere and Hemisphere carry a
// direction intrinsically and ignore these.
ES_PROPERTY(unit="°", category=Velocity, shown_when=shape:Point|Box)
f32 angleSpreadMin{0.0f};
ES_PROPERTY(unit="°", category=Velocity, shown_when=shape:Point|Box)
f32 angleSpreadMax{360.0f};
// Size
ES_PROPERTY(min=0, category=Size)
f32 startSizeMin{100.0f};
ES_PROPERTY(min=0, category=Size)
f32 startSizeMax{100.0f};
ES_PROPERTY(min=0, category=Size)
f32 endSizeMin{100.0f};
ES_PROPERTY(min=0, category=Size)
f32 endSizeMax{100.0f};
// Easing — i32 storage, dropdown generated from the ParticleEasing enum.
ES_PROPERTY(enum=ParticleEasing, category=Size)
i32 sizeEasing{static_cast<i32>(ParticleEasing::Linear)};
// Color
ES_PROPERTY(category=Color)
glm::vec4 startColor{1.0f, 1.0f, 1.0f, 1.0f};
ES_PROPERTY(category=Color)
glm::vec4 endColor{1.0f, 1.0f, 1.0f, 0.0f};
ES_PROPERTY(enum=ParticleEasing, category=Color)
i32 colorEasing{static_cast<i32>(ParticleEasing::Linear)};
// Rotation
ES_PROPERTY(unit="°", category=Rotation)
f32 rotationMin{0.0f};
ES_PROPERTY(unit="°", category=Rotation)
f32 rotationMax{0.0f};
ES_PROPERTY(category=Rotation)
f32 angularVelocityMin{0.0f};
ES_PROPERTY(category=Rotation)
f32 angularVelocityMax{0.0f};
// Forces (grouped under the Velocity category in the inspector)
ES_PROPERTY(category=Velocity)
glm::vec3 gravity{0.0f, 0.0f, 0.0f};
ES_PROPERTY(min=0, category=Velocity)
f32 damping{0.0f};
ES_PROPERTY(category=Velocity, tooltip="A velocity each particle carries on top of its own, chosen between the two ends when it is born. Gravity, damping, noise and the speed limit do not act on it. Run by the CPU simulation.")
glm::vec3 addedVelocityMin{0.0f, 0.0f, 0.0f};
ES_PROPERTY(category=Velocity)
glm::vec3 addedVelocityMax{0.0f, 0.0f, 0.0f};
ES_PROPERTY(min=0, category=Velocity, tooltip="The fastest a particle may move under its own velocity; 0 is no limit. A faster particle is pulled back toward the limit. Run by the CPU simulation.")
f32 speedLimit{0.0f};
ES_PROPERTY(min=0, max=1, category=Velocity, tooltip="How much of the excess over the limit is removed per 1/60 s: 1 clamps at once, a small value brakes gently.")
f32 limitDampen{1.0f};
// Noise / Turbulence — a divergence-free curl-noise flow field advects each
// particle, layered on top of velocity/gravity. Strength 0 disables it (no
// field is sampled), so the module is free when unused.
ES_PROPERTY(min=0, category=Noise)
f32 noiseStrength{0.0f};
ES_PROPERTY(min=0, category=Noise)
f32 noiseFrequency{0.01f};
ES_PROPERTY(category=Noise)
f32 noiseScrollSpeed{0.0f};
ES_PROPERTY(min=1, max=8, step=1, category=Noise)
i32 noiseOctaves{1};
// Texture
ES_PROPERTY(asset = texture, category=Texture)
resource::TextureHandle texture;
ES_PROPERTY(min=1, step=1, category=Texture)
i32 spriteColumns{1};
ES_PROPERTY(min=1, step=1, category=Texture)
i32 spriteRows{1};
ES_PROPERTY(min=0, category=Texture)
f32 spriteFPS{10.0f};
ES_PROPERTY(category=Texture)
bool spriteLoop{true};
// Rendering — blendMode keeps a TS override (BlendMode is a renderer-side enum,
// not a component ES_ENUM); simulationSpace's dropdown is generated (see below).
ES_PROPERTY(category=Rendering)
i32 blendMode{1};
ES_PROPERTY(step=1, enum_source=sortingLayers, category=Rendering)
i32 layer{0};
ES_PROPERTY(asset = material, category=Rendering)
u32 material{0};
// Space — i32 storage, dropdown generated from the SimulationSpace enum.
ES_PROPERTY(enum=SimulationSpace, category=Rendering)
i32 simulationSpace{static_cast<i32>(SimulationSpace::World)};
ES_PROPERTY(enum=ParticleRenderMode, category=Rendering, tooltip="Billboard faces the view. Stretched lays the quad's long axis (its Y) along the particle's velocity and lengthens it with speed. Drawn by the CPU simulation; a GPU-simulated emitter draws as Billboard.")
i32 renderMode{static_cast<i32>(ParticleRenderMode::Billboard)};
ES_PROPERTY(min=0, category=Rendering, shown_when=renderMode:Stretched, tooltip="Stretched: how much of the particle's speed is added to the quad's length, in world units per unit of speed.")
f32 velocityScale{0.0f};
ES_PROPERTY(min=0, category=Rendering, shown_when=renderMode:Stretched, tooltip="Stretched: the quad's own length is its size times this.")
f32 lengthScale{1.0f};
// State
ES_PROPERTY()
bool enabled{true};
// Sub-emitter — on each parent particle's birth or death, fire the referenced
// child emitter's burst at that particle's position. The child is an ordinary
// ParticleEmitter entity used as a template (typically rate=0, playOnStart=false
// so it only emits when triggered); its burstCount sets the sub-burst size.
// `subEmitter` is the child entity's raw id (0 = none). It is stored as u32
// rather than Entity so the pointer layout keeps a heap accessor (Entity is
// truncated out of the layout); the entity_ref tag still drives the editor
// picker and the scene/prefab editor→runtime id remapping.
ES_PROPERTY(enum=SubEmitterTrigger, category=SubEmitter)
i32 subEmitterTrigger{static_cast<i32>(SubEmitterTrigger::Death)};
ES_PROPERTY(min=0, max=1, category=SubEmitter)
f32 subEmitterChance{1.0f};
ES_PROPERTY(min=0, max=1, category=SubEmitter)
f32 subEmitterInheritVelocity{0.0f};
ES_PROPERTY(entity_ref, category=SubEmitter)
u32 subEmitter{0};
// Per-particle trail — each particle drags a tapering ribbon along its recent
// path (comet tails, sparks, magic streaks). The ribbon reuses the same
// triangle-strip batch path as the standalone TrailRenderer; its head takes the
// particle's current colour and `trailWidth`, fading to a transparent point at
// the tail. Off by default (no history is recorded when disabled).
ES_PROPERTY(category=Trail)
bool trailEnabled{false};
ES_PROPERTY(min=0, category=Trail, shown_when=trailEnabled:true)
f32 trailWidth{8.0f};
ES_PROPERTY(min=2, max=12, step=1, category=Trail, shown_when=trailEnabled:true)
i32 trailPoints{6};
ES_PROPERTY(min=0, category=Trail, shown_when=trailEnabled:true)
f32 trailMinDistance{6.0f};
// Collision is opt-in. Floor remains the default for existing scenes; optional
// 2D/3D adapters query the swept segment in project world units.
ES_PROPERTY(category=Collision)
bool collisionEnabled{false};
ES_PROPERTY(category=Collision, shown_when=collisionEnabled:true)
f32 collisionFloor{0.0f};
// Scene queries use the same response/events as the legacy plane. Results are
// exchanged as a bounded batch, so the core depends on no physics backend.
ES_PROPERTY(enum=ParticleCollisionMode, category=Collision, shown_when=collisionEnabled:true)
i32 collisionMode{static_cast<i32>(ParticleCollisionMode::Floor)};
ES_PROPERTY(bitmask_source=collisionLayers, min=0, max=65535, step=1, category=Collision, shown_when=collisionEnabled:true)
u32 collisionMask{65535};
ES_PROPERTY(min=0, max=4096, step=1, category=Collision, shown_when=collisionEnabled:true)
i32 collisionQueryBudget{128};
// World units from the nearest active camera; 0 means no distance culling.
ES_PROPERTY(min=0, category=Collision, shown_when=collisionEnabled:true)
f32 collisionMaxDistance{0.0f};
ES_PROPERTY(enum=ParticleCollisionFallback, category=Collision, shown_when=collisionEnabled:true)
i32 collisionFallback{static_cast<i32>(ParticleCollisionFallback::Floor)};
ES_PROPERTY(category=Collision, shown_when=collisionEnabled:true)
bool collisionEvents{false};
ES_PROPERTY(min=0, max=1024, step=1, category=Collision, shown_when=collisionEnabled:true)
i32 collisionEventBudget{32};
// Depth mode: how far behind what the camera saw a particle still counts as having hit it, in world units.
// Past this it has gone round the back, and passes.
ES_PROPERTY(min=0, category=Collision, shown_when=collisionEnabled:true)
f32 collisionThickness{30.0f};
// Restitution: 0 = particles stop dead on the floor, 1 = a full elastic bounce.
ES_PROPERTY(min=0, max=1, category=Collision, shown_when=collisionEnabled:true)
f32 collisionBounce{0.5f};
// Tangential friction applied on each bounce (0 = frictionless slide, 1 = stop
// horizontal motion).
ES_PROPERTY(min=0, max=1, category=Collision, shown_when=collisionEnabled:true)
f32 collisionFriction{0.1f};
// Fraction of a particle's remaining life burned on each bounce (0 = none, 1 =
// dies on first contact) — fades splashes/sparks out as they settle.
ES_PROPERTY(min=0, max=1, category=Collision, shown_when=collisionEnabled:true)
f32 collisionLifetimeLoss{0.0f};
ParticleEmitter() = default;
};
} // namespace esengine::ecs