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 "../math/Math.hpp"
#include "../ecs/Registry.hpp"
#include "../ecs/components/Transform.hpp"
#include "../ecs/components/ParticleEmitter.hpp"
#include "../ecs/components/ParticleForceField.hpp"
#include "../ecs/components/ParticleCollider.hpp"
#include "Particle.hpp"
#include "ParticleBursts.hpp"
#include "ParticleEasing.hpp"
#include "ParticleShapes.hpp"
#include <unordered_map>
#include <unordered_set>
#include <functional>
#include <random>
#include <array>
#include <algorithm>
#include "../core/Reflection.hpp"
namespace esengine { class RandomSource; }
namespace esengine::particle {
// Resolution of the per-emitter over-life lookup tables (baked in TS from a
// gradient/curve, sampled here per particle). 32 keeps them smooth and small.
ES_CONST(ts=GRADIENT_LUT_SIZE)
inline constexpr int kColorLutSize = 32;
using ColorLut = std::array<glm::vec4, kColorLutSize>;
// Size-over-life: a scalar multiplier curve × the particle's start size.
using SizeLut = std::array<f32, kColorLutSize>;
// Hard cap on a per-particle trail's recorded points (the ribbon has one segment
// less). Bounds the per-emitter history buffer; the component's trailPoints picks
// how many of these to actually keep.
inline constexpr int kMaxTrailPoints = 12;
// A scene force field flattened to what the per-particle inner loop needs, gathered
// once per update() so the hot loop touches no components.
struct ForceFieldInstance {
i32 type = 0;
glm::vec3 position{0.0f};
glm::vec3 direction{1.0f, 0.0f, 0.0f}; // pre-normalized (Directional only)
f32 strength = 0.0f;
f32 radius = 0.0f; // 0 = unbounded
f32 radiusSq = 0.0f;
bool falloff = true;
};
// A scene ParticleCollider flattened to what a distance function needs, gathered once per update(). The GPU kernel
// reads the same record: three vec4s and four words, so the layout is the same in both languages.
struct SdfColliderInstance {
glm::vec3 position{0.0f};
f32 shape = 0.0f;
glm::quat rotation{1.0f, 0.0f, 0.0f, 0.0f};
f32 ext[3] = {0.0f, 0.0f, 0.0f}; // sphere: radius. box: half extents. capsule: radius, half height.
f32 inverted = 0.0f;
u32 mask = 0xffffu;
u32 pad[3] = {0, 0, 0};
};
/// How far a world point is outside a collider, negative inside; what the kernel's sdfOne answers.
f32 sdfDistance(const SdfColliderInstance& c, const glm::vec3& point);
// Fixed-width batch records shared by Web and native heaps. Integers keep their
// bits (including generational entity IDs); they are not converted through float.
struct CollisionQuery {
u32 emitter, slot, mode, mask;
f32 ox, oy, oz, dx, dy, dz;
};
struct CollisionReply {
u32 status, body; // 0 miss, 1 hit, 2 backend unavailable
f32 x, y, z, nx, ny, nz;
};
struct CollisionEvent {
u32 emitter, slot, body, mode;
f32 x, y, z, nx, ny, nz, vx, vy, vz;
u32 publish;
};
struct CollisionStats {
u32 emitter = 0, queries = 0, hits = 0, budgetSkipped = 0, distanceSkipped = 0;
u32 unavailable = 0, events = 0, eventDropped = 0, fallbacks = 0, mode = 0;
};
static_assert(sizeof(CollisionQuery) == 40 && sizeof(CollisionReply) == 32);
static_assert(sizeof(CollisionEvent) == 56 && sizeof(CollisionStats) == 40);
/// What one frame asks of a GPU-simulated emitter: how long to advance, how many to spawn and where in the ring they go.
struct GpuStep {
f32 dt = 0.0f;
f32 noiseTime = 0.0f;
u32 capacity = 0;
u32 firstIndex = 0; ///< Absolute index of the first particle born this step (slot = index % capacity).
u32 spawnCount = 0; ///< Born this step: `smoothCount` spread across dt, then the rest as one burst.
u32 smoothCount = 0;
u32 drawCount = 0; ///< Slots that may hold a live particle once this step has run.
bool reset = false; ///< Kill everything first (a reset() since the last step).
bool fed = false; ///< A GPU parent's events spawn into it, so any slot may be live whatever was scheduled.
};
struct EmitterState {
ParticlePool pool;
f32 emission_accumulator = 0.0f;
f32 elapsed_time = 0.0f;
f32 burst_timer = 0.0f;
/// Where the scheduled bursts last looked: the emitting clock of the previous step, below zero before the first.
f32 burst_clock = -1.0f;
// Monotonic clock for the noise field's scroll — advances every update
// regardless of play/stop so the turbulence never snaps when emission pauses.
f32 noise_time = 0.0f;
bool playing = false;
bool first_update = true;
// Per-particle trail history, keyed by pool index and only sized once an emitter
// enables trails (free otherwise). trail_pos is a flat [capacity × kMaxTrailPoints]
// ring of raw particle-space positions (oldest→newest); trail_count is how many
// slots each particle has filled.
std::vector<glm::vec3> trail_pos;
std::vector<u8> trail_count;
u32 collisionCursor = 0, collisionOrdinal = 0;
// GPU simulation: the emitter keeps its schedule here (rate, bursts, duration) and the particles live in
// a GPU ring this state only counts. The pool stays empty, so a million-particle emitter costs no heap.
bool gpu = false;
u32 gpuCapacity = 0;
f32 gpuDt = 0.0f;
u32 gpuSmooth = 0, gpuBurst = 0;
u32 gpuSpawned = 0;
bool gpuReset = false;
bool gpuFed = false;
explicit EmitterState(u32 capacity) : pool(capacity) {}
};
class ParticleSystem {
public:
/** The engine stream this system draws from — see core/RandomSource.hpp. */
static constexpr const char* kRandomStream = "particles";
ParticleSystem();
/** Re-derive this system's generator from the engine's seed. Spawns after
* this point reproduce; particles already alive keep the values they got. */
void reseedFrom(const esengine::RandomSource& source);
void update(ecs::Registry& registry, f32 dt);
/// Whether emitters that ask for GPU simulation get it. Set by the renderer, which knows the device; false
/// means they run on the CPU, capped at kGpuFallbackCapacity.
void setGpuAvailable(bool available) { gpu_available_ = available; }
bool gpuAvailable() const { return gpu_available_; }
static constexpr u32 kGpuMaxCapacity = 2'000'000;
static constexpr u32 kGpuFallbackCapacity = 20'000;
/// What a GPU emitter has to do to catch up: the time, the births, where in the ring they go. False when the entity
/// is not simulated on the GPU. Nothing is consumed until commitGpuStep, so a step that was asked for and never run
/// (a collect whose frame did not reach the graph) is asked for again next time rather than lost.
bool peekGpuStep(Entity entity, GpuStep& out) const;
/// The kernel ran this step: the time and births it covered are spent.
void commitGpuStep(Entity entity, const GpuStep& step);
const std::vector<ForceFieldInstance>& forceFields() const { return force_fields_; }
const std::vector<SdfColliderInstance>& sdfColliders() const { return sdf_colliders_; }
/// Collisions a kernel reported, a frame or two late since they come back from the GPU; they reach the game as any others do.
void addGpuCollisions(Entity entity, u32 total, const CollisionEvent* events, u32 count);
// update() integrates; resolveCollisions() completes all queries in this same
// frame before rendering. No reply survives into the next update.
const std::vector<CollisionQuery>& collisionQueries() const { return collision_queries_; }
const std::vector<CollisionEvent>& collisionEvents() const { return collision_events_; }
const std::vector<CollisionStats>& collisionStats() const { return collision_stats_; }
void setCollisionBudget(u32 queries, u32 events, bool debug = false) {
collision_debug_ = debug;
query_budget_ = std::min(queries, 65536u); event_budget_ = std::min(events, 16384u);
}
void resolveCollisions(ecs::Registry& registry, const CollisionReply* replies, u32 count);
void play(Entity entity);
void stop(Entity entity);
void reset(Entity entity);
u32 aliveCount(Entity entity) const;
/**
* @brief Spawn @p count of @p entity's particles at a world point, now: an impact's sparks, a muzzle's flash, without
* moving the emitter or replaying it.
* @details The emitter's own settings make them (shape, speed, size, colour, life). Its shape stands at @p position,
* turned so its local +Y — a cone's or a hemisphere's axis — points along @p normal when one is given, and
* as the entity is turned otherwise; @p velocity is added to every particle. A Local-space emitter keeps them
* in its own frame, as a sub-emitter's burst is kept. CPU-simulated emitters only: a GPU one answers 0.
* @return How many were spawned (fewer than asked when the pool or the particle budget is full).
*/
u32 emitAt(ecs::Registry& registry, Entity entity, u32 count, const glm::vec3& position,
const glm::vec3& normal, const glm::vec3& velocity);
u32 totalAliveParticles() const;
void setParticleLimit(u32 limit) { particle_limit_ = limit; }
void forEachParticle(Entity entity, const std::function<void(const Particle&)>& fn) const;
EmitterState* getState(Entity entity);
const EmitterState* getState(Entity entity) const;
/** Set (count == kColorLutSize) or clear (count == 0) an entity's color-over-life
* LUT. When set, particle color is sampled from it instead of start/end+easing. */
void setColorLut(Entity entity, const f32* rgba, i32 count);
/** Set/clear an entity's size-over-life multiplier LUT (× the particle's start size). */
void setSizeLut(Entity entity, const f32* values, i32 count);
/** Set/clear an entity's speed-over-life multiplier LUT. It scales how fast a
* particle travels along the trajectory it already has — it is not a force,
* and gravity, damping and noise still accumulate into velocity as before. */
void setSpeedLut(Entity entity, const f32* values, i32 count);
/** Set/clear an entity's burst schedule: `count` pairs of (seconds, particles) in `values`. Each fires once per
* pass of the emitter's clock over its time, and a looping emitter passes every duration. */
void setBursts(Entity entity, const f32* values, i32 count);
/// The over-life curves an entity was given, for the GPU kernel to read; null where none was set.
const ColorLut* colorLut(Entity entity) const { auto it = colorLuts_.find(entity); return it == colorLuts_.end() ? nullptr : &it->second; }
const SizeLut* sizeLut(Entity entity) const { auto it = sizeLuts_.find(entity); return it == sizeLuts_.end() ? nullptr : &it->second; }
const SizeLut* speedLut(Entity entity) const { auto it = speedLuts_.find(entity); return it == speedLuts_.end() ? nullptr : &it->second; }
private:
void emitParticles(const ecs::ParticleEmitter& emitter,
const ecs::Transform& transform,
EmitterState& state, u32 count);
// Shared spawn core: seed `count` particles into `state` from `emitter`'s
// config at `frame`, adding `velocityBias` to each (a sub-emitter burst
// inherits the parent particle's motion that way).
// `allowBirthTrigger` records Birth events for a nested sub-emitter; false for a
// sub-burst's own spawn so a drain can't re-enter the request buffer it's reading.
void emitInto(const ecs::ParticleEmitter& emitter, EmitterState& state,
const EmitterFrame& frame, bool isWorldSpace,
glm::vec3 velocityBias, u32 count, bool allowBirthTrigger, u32 depth = 0,
const EmitterFrame* storageFrame = nullptr);
// Fire the referenced child emitter's burst at each pending sub-emit request.
void drainSubEmitters(ecs::Registry& registry, Entity parent, Entity child,
f32 inheritVelocity, f32 chance);
void updateParticles(const ecs::ParticleEmitter& emitter, EmitterState& state, f32 dt,
const ColorLut* colorLut, const SizeLut* sizeLut,
const SizeLut* speedLut,
const EmitterFrame& frame, bool isWorldSpace);
void collisionStep(const ecs::ParticleEmitter&, EmitterState&, Particle&, glm::vec3 from,
const EmitterFrame&, bool world);
void collide(const ecs::ParticleEmitter&, EmitterState&, Particle&, glm::vec3 point,
glm::vec3 normal, u32 body, const EmitterFrame&, bool world);
void floorCollision(const ecs::ParticleEmitter&, EmitterState&, Particle&, const EmitterFrame&, bool world);
void sdfCollision(const ecs::ParticleEmitter&, EmitterState&, Particle&, const EmitterFrame&, bool world);
f32 randomRange(f32 min, f32 max);
// A parent particle's birth/death position + velocity, queued during a parent's
// update and drained into its child sub-emitter right after.
struct SubEmitRequest { glm::vec3 position; glm::vec3 velocity; u32 depth = 0; };
std::vector<SubEmitRequest> subemit_requests_;
struct PendingCollision { Entity emitter; u32 generation; EmitterFrame frame; bool world; std::size_t stats; };
std::vector<CollisionQuery> collision_queries_;
std::vector<PendingCollision> collision_pending_;
std::vector<CollisionEvent> collision_events_;
std::vector<CollisionStats> collision_stats_;
std::vector<glm::vec3> collision_cameras_;
Entity collision_emitter_{};
std::size_t collision_stats_index_ = 0;
u32 query_budget_ = 4096, event_budget_ = 1024, event_attempts_ = 0;
u32 collision_child_bursts_ = 0;
u32 collision_frame_ = 0;
bool collision_debug_ = false;
std::unordered_map<Entity, u32> collision_quotas_;
std::unordered_map<Entity, EmitterState> states_;
// A play() that arrives before the emitter's first update (its state isn't
// created yet) is remembered here and applied on state creation, not dropped.
std::unordered_set<Entity> pending_play_;
std::unordered_map<Entity, ColorLut> colorLuts_;
std::unordered_map<Entity, SizeLut> sizeLuts_;
std::unordered_map<Entity, SizeLut> speedLuts_;
std::unordered_map<Entity, std::vector<ScheduledBurst>> burstSchedules_;
std::mt19937 rng_;
bool gpu_available_ = false;
u32 particle_limit_ = 0xffffffffu;
std::vector<u32> dead_particle_indices_;
// Active scene force fields, rebuilt each update() and applied to world-space
// particles during integration.
std::vector<ForceFieldInstance> force_fields_;
std::vector<SdfColliderInstance> sdf_colliders_;
struct GpuCollisions { Entity entity; u32 total; std::vector<CollisionEvent> events; };
std::vector<GpuCollisions> gpu_collisions_;
// RAII: auto-unregisters from the registry's onDestroy when this system is
// destroyed, so a torn-down system never leaves a dangling `this` behind.
Connection destroyConn_;
};
} // namespace esengine::particle