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
#include "ParticleSystem.hpp"
#include "ParticleNoise.hpp"
#include <algorithm>
#include <chrono>
#include <cmath>
#include "../core/RandomSource.hpp"
#include "../ecs/components/Camera.hpp"
#include "ParticleSpeedLimit.hpp"
namespace esengine::particle {
ParticleSystem::ParticleSystem() : rng_(RandomSource().stream(kRandomStream)) {
}
void ParticleSystem::reseedFrom(const esengine::RandomSource& source) {
rng_ = source.stream(kRandomStream);
}
void ParticleSystem::update(ecs::Registry& registry, f32 frameDt) {
collision_queries_.clear(); collision_pending_.clear(); collision_events_.clear();
collision_stats_.clear(); collision_cameras_.clear();
event_attempts_ = 0; collision_child_bursts_ = 0;
if (!std::isfinite(frameDt) || frameDt < 0) return;
auto cameras = registry.activeView<ecs::Camera, ecs::Transform>();
for (auto entity : cameras) {
if (!cameras.get<ecs::Camera>(entity).isActive) continue;
auto& transform = cameras.get<ecs::Transform>(entity);
transform.ensureDecomposed();
collision_cameras_.push_back(transform.worldPosition);
}
if (!destroyConn_.isConnected()) {
destroyConn_ = registry.onDestroy([this](Entity entity) {
states_.erase(entity);
pending_play_.erase(entity);
colorLuts_.erase(entity);
sizeLuts_.erase(entity);
speedLuts_.erase(entity);
burstSchedules_.erase(entity);
});
}
// Flatten the active force fields once so the per-particle loop touches no
// components. Fields are world objects, applied to world-space particles.
force_fields_.clear();
auto ffView = registry.activeView<ecs::Transform, ecs::ParticleForceField>();
for (auto ffEntity : ffView) {
const auto& ff = ffView.get<ecs::ParticleForceField>(ffEntity);
if (!ff.enabled || ff.strength == 0.0f) continue;
auto& ffTransform = ffView.get<ecs::Transform>(ffEntity);
ffTransform.ensureDecomposed();
f32 dl = std::sqrt(ff.direction.x * ff.direction.x + ff.direction.y * ff.direction.y
+ ff.direction.z * ff.direction.z);
ForceFieldInstance inst;
inst.type = ff.type;
inst.position = ffTransform.worldPosition;
inst.direction = dl > 1e-6f ? ff.direction / dl : glm::vec3(1.0f, 0.0f, 0.0f);
inst.strength = ff.strength;
inst.radius = ff.radius;
inst.radiusSq = ff.radius * ff.radius;
inst.falloff = ff.falloff;
force_fields_.push_back(inst);
}
sdf_colliders_.clear();
auto colliderView = registry.activeView<ecs::Transform, ecs::ParticleCollider>();
for (auto colliderEntity : colliderView) {
const auto& collider = colliderView.get<ecs::ParticleCollider>(colliderEntity);
if (!collider.enabled) continue;
auto& colliderTransform = colliderView.get<ecs::Transform>(colliderEntity);
colliderTransform.ensureDecomposed();
const glm::vec3 scale = colliderTransform.worldScale;
SdfColliderInstance inst;
inst.position = colliderTransform.worldPosition;
inst.rotation = colliderTransform.worldRotation;
inst.shape = static_cast<f32>(collider.shape);
inst.inverted = collider.inverted ? 1.0f : 0.0f;
inst.mask = collider.mask & 0xffffu;
// A distance function cannot be stretched and stay one, so a round shape takes the largest of its scale.
const f32 round = std::max({std::abs(scale.x), std::abs(scale.y), std::abs(scale.z)});
if (collider.shape == static_cast<i32>(ecs::ParticleColliderShape::Box)) {
inst.ext[0] = collider.halfExtents.x * std::abs(scale.x);
inst.ext[1] = collider.halfExtents.y * std::abs(scale.y);
inst.ext[2] = collider.halfExtents.z * std::abs(scale.z);
} else {
inst.ext[0] = collider.radius * round;
inst.ext[1] = collider.halfHeight * std::abs(scale.y);
}
sdf_colliders_.push_back(inst);
}
auto view = registry.activeView<ecs::Transform, ecs::ParticleEmitter>();
// A GPU parent's events feed its child in the kernel; the child cannot know how many slots that lights.
for (auto& [stateEntity, childState] : states_) childState.gpuFed = false;
for (auto parentEntity : view) {
const auto& parent = view.get<ecs::ParticleEmitter>(parentEntity);
if (parent.subEmitter == 0 || !parent.enabled) continue;
auto parentState = states_.find(parentEntity), childState = states_.find(Entity::fromRaw(parent.subEmitter));
if (parentState != states_.end() && childState != states_.end() && parentState->second.gpu && childState->second.gpu) {
childState->second.gpuFed = true;
}
}
// Share the App cap across active scene emitters. Rotate remainder slots so
// a budget smaller than the emitter count never permanently starves a tail.
collision_quotas_.clear();
std::vector<Entity> sceneEmitters;
for (auto entity : view) {
const auto& e = view.get<ecs::ParticleEmitter>(entity);
if (e.enabled && e.collisionEnabled && e.collisionMode != 0) sceneEmitters.push_back(entity);
}
const u32 n = static_cast<u32>(sceneEmitters.size());
for (u32 i = 0; i < n; ++i) {
const u32 rank = (i + n - collision_frame_ % n) % n;
collision_quotas_[sceneEmitters[i]] = query_budget_ / n + (rank < query_budget_ % n ? 1u : 0u);
}
++collision_frame_;
for (auto entity : view) {
const auto& emitter = view.get<ecs::ParticleEmitter>(entity);
const auto& transform = view.get<ecs::Transform>(entity);
if (!emitter.enabled) {
continue;
}
// The emitter's own time: it runs at its simulation speed, so everything below (emission, ageing, motion) follows it.
const f32 dt = frameDt * std::max(emitter.simulationSpeed, 0.0f);
// A GPU emitter keeps no pool: its particles live in a GPU ring. Where the device cannot compute it
// is an ordinary emitter, capped so a million-particle setup cannot take the CPU down with it.
const bool useGpu = emitter.gpuSimulation && gpu_available_;
u32 capacity = static_cast<u32>(std::clamp(emitter.maxParticles, 0, 1'000'000));
if (emitter.gpuSimulation && !gpu_available_) capacity = std::min(capacity, kGpuFallbackCapacity);
if (useGpu) capacity = static_cast<u32>(std::clamp(emitter.maxParticles, 0, static_cast<i32>(kGpuMaxCapacity)));
auto it = states_.find(entity);
if (it != states_.end() && (it->second.gpu != useGpu || (useGpu && it->second.gpuCapacity != capacity))) {
// Changed how it simulates (or how big): the schedule carries over, so a burst already spent is not spent
// twice. The device is only known once the renderer has run, a frame after the first update, so an emitter
// that began on the CPU is moved to the GPU with as many particles as it had alive.
EmitterState old = std::move(it->second);
states_.erase(it);
auto [moved, _] = states_.emplace(entity, EmitterState(useGpu ? 0u : capacity));
EmitterState& next = moved->second;
next.emission_accumulator = old.emission_accumulator;
next.elapsed_time = old.elapsed_time;
next.burst_timer = old.burst_timer;
next.burst_clock = old.burst_clock;
next.noise_time = old.noise_time;
next.playing = old.playing;
next.first_update = old.first_update;
next.gpu = useGpu;
next.gpuCapacity = useGpu ? capacity : 0;
if (useGpu) next.gpuBurst = std::min(old.pool.aliveCount(), capacity);
it = moved;
}
if (it == states_.end()) {
auto [insertIt, _] = states_.emplace(
entity,
// Clamp defensively: maxParticles is inspector-constrained (min=1)
// but a script, scene file, or replicated value bypasses that — a
// negative cast to u32 (or a multi-billion count) would resize the
// pool into a bad_alloc.
EmitterState(useGpu ? 0u : capacity)
);
it = insertIt;
it->second.gpu = useGpu;
it->second.gpuCapacity = useGpu ? capacity : 0;
if (emitter.playOnStart) {
it->second.playing = true;
}
// Apply a play() that arrived before this first update (playOnStart=false
// + an immediate trigger) instead of dropping it.
if (pending_play_.erase(entity) > 0) {
it->second.playing = true;
it->second.elapsed_time = 0.0f;
}
}
auto& state = it->second;
// Size the per-particle trail history the first time this emitter uses
// trails (kept free when they're off). Sized before emission so a spawn
// this frame can reset its slot.
if (emitter.trailEnabled && state.trail_count.size() != state.pool.capacity()) {
state.trail_count.assign(state.pool.capacity(), 0);
state.trail_pos.assign(static_cast<std::size_t>(state.pool.capacity()) * kMaxTrailPoints,
glm::vec3(0.0f));
}
if (state.first_update && emitter.playOnStart) {
state.playing = true;
state.first_update = false;
}
// The delay is time the emitter plays without emitting; the duration is counted from its end.
const f32 startDelay = std::max(emitter.startDelay, 0.0f);
bool emitting = state.playing;
if (!emitter.looping && state.elapsed_time >= startDelay + emitter.duration) {
emitting = false;
}
// The schedule is one thing whoever runs the particles: a GPU emitter only counts what is born.
auto emit = [&](u32 count, bool burst) {
if (!state.gpu) { emitParticles(emitter, transform, state, count); return; }
u32& pending = burst ? state.gpuBurst : state.gpuSmooth;
pending = std::min(pending + count, state.gpuCapacity);
};
if (emitting) {
state.elapsed_time += dt;
}
if (emitting && state.elapsed_time >= startDelay) {
if (auto schedule = burstSchedules_.find(entity); schedule != burstSchedules_.end()) {
const f32 clock = state.elapsed_time - startDelay;
const u32 due = burstsDue(schedule->second, state.burst_clock, clock, emitter.duration, emitter.looping);
state.burst_clock = clock;
if (due > 0) emit(due, true);
}
if (emitter.rate > 0.0f) {
state.emission_accumulator += emitter.rate * dt;
u32 toEmit = static_cast<u32>(state.emission_accumulator);
if (toEmit > 0) {
state.emission_accumulator -= static_cast<f32>(toEmit);
emit(toEmit, false);
}
}
if (emitter.burstCount > 0) {
if (state.burst_timer <= 0.0f) {
emit(static_cast<u32>(emitter.burstCount), true);
state.burst_timer = emitter.burstInterval;
}
state.burst_timer -= dt;
}
}
if (state.gpu) {
// The kernel does what updateParticles would; this side only keeps the clocks it needs.
state.noise_time += dt;
state.gpuDt += dt;
if (emitter.collisionEnabled) {
CollisionStats stats; stats.emitter = entity.raw;
stats.mode = static_cast<u32>(emitter.collisionMode);
for (const GpuCollisions& reported : gpu_collisions_) {
if (reported.entity != entity) continue;
stats.hits += reported.total;
stats.events += static_cast<u32>(reported.events.size());
stats.eventDropped += reported.total - static_cast<u32>(reported.events.size());
collision_events_.insert(collision_events_.end(), reported.events.begin(), reported.events.end());
}
collision_stats_.push_back(stats);
}
continue;
}
const EmitterFrame frame{transform.worldPosition, transform.worldRotation,
transform.worldScale};
bool isWorldSpace = emitter.simulationSpace ==
static_cast<i32>(ecs::SimulationSpace::World);
collision_emitter_ = entity;
collision_stats_index_ = collision_stats_.size();
if (emitter.collisionEnabled) {
CollisionStats stats; stats.emitter = entity.raw;
stats.mode = static_cast<u32>(emitter.collisionMode);
collision_stats_.push_back(stats);
}
auto lutIt = colorLuts_.find(entity);
auto sizeIt = sizeLuts_.find(entity);
auto speedIt = speedLuts_.find(entity);
updateParticles(emitter, state, dt,
lutIt != colorLuts_.end() ? &lutIt->second : nullptr,
sizeIt != sizeLuts_.end() ? &sizeIt->second : nullptr,
speedIt != speedLuts_.end() ? &speedIt->second : nullptr,
frame, isWorldSpace);
if (state.pool.capacity() > 0) {
const u32 step = std::max(1u, std::min(static_cast<u32>(std::clamp(emitter.collisionQueryBudget, 0, 4096)), collision_quotas_[entity]));
state.collisionCursor = (state.collisionCursor + step) % std::max(1u,state.pool.aliveCount());
}
// Fire the child sub-emitter's burst at every birth/death queued this frame.
if (emitter.subEmitter != 0 && !subemit_requests_.empty()) {
drainSubEmitters(registry, entity, Entity::fromRaw(emitter.subEmitter),
emitter.subEmitterInheritVelocity, emitter.subEmitterChance);
}
}
gpu_collisions_.clear();
}
void ParticleSystem::play(Entity entity) {
auto it = states_.find(entity);
if (it != states_.end()) {
it->second.playing = true;
it->second.elapsed_time = 0.0f;
} else {
// State is created lazily on the first update; remember the trigger so it
// isn't lost when play() runs before this emitter's first update.
pending_play_.insert(entity);
}
}
void ParticleSystem::stop(Entity entity) {
pending_play_.erase(entity);
auto it = states_.find(entity);
if (it != states_.end()) {
it->second.playing = false;
}
}
void ParticleSystem::reset(Entity entity) {
pending_play_.erase(entity);
auto it = states_.find(entity);
if (it != states_.end()) {
it->second.pool.clear();
if (it->second.gpu) {
it->second.gpuSmooth = it->second.gpuBurst = it->second.gpuSpawned = 0;
it->second.gpuDt = 0.0f;
it->second.gpuReset = true;
}
it->second.emission_accumulator = 0.0f;
it->second.elapsed_time = 0.0f;
it->second.burst_timer = 0.0f;
it->second.burst_clock = -1.0f;
it->second.playing = false;
}
}
void ParticleSystem::setColorLut(Entity entity, const f32* rgba, i32 count) {
if (count != kColorLutSize || rgba == nullptr) {
colorLuts_.erase(entity); // 0 (or a mismatched bake) clears → fall back to start/end
return;
}
ColorLut& lut = colorLuts_[entity];
for (std::size_t i = 0; i < kColorLutSize; ++i) {
lut[i] = glm::vec4(rgba[i * 4], rgba[i * 4 + 1], rgba[i * 4 + 2], rgba[i * 4 + 3]);
}
}
void ParticleSystem::setSizeLut(Entity entity, const f32* values, i32 count) {
if (count != kColorLutSize || values == nullptr) {
sizeLuts_.erase(entity);
return;
}
SizeLut& lut = sizeLuts_[entity];
for (std::size_t i = 0; i < kColorLutSize; ++i) lut[i] = values[i];
}
void ParticleSystem::setSpeedLut(Entity entity, const f32* values, i32 count) {
if (count != kColorLutSize || values == nullptr) {
speedLuts_.erase(entity);
return;
}
SizeLut& lut = speedLuts_[entity];
for (std::size_t i = 0; i < kColorLutSize; ++i) lut[i] = values[i];
}
void ParticleSystem::setBursts(Entity entity, const f32* values, i32 count) {
if (count <= 0 || values == nullptr) {
burstSchedules_.erase(entity);
return;
}
std::vector<ScheduledBurst>& schedule = burstSchedules_[entity];
schedule.clear();
for (i32 i = 0; i < count && i < 64; ++i) {
schedule.push_back({values[i * 2], static_cast<u32>(std::max(values[i * 2 + 1], 0.0f))});
}
}
u32 ParticleSystem::aliveCount(Entity entity) const {
auto it = states_.find(entity);
if (it != states_.end()) {
// The GPU keeps the truth; what this side can say is how many slots have ever held one, an upper bound.
if (it->second.gpu) return std::min(it->second.gpuSpawned, it->second.gpuCapacity);
return it->second.pool.aliveCount();
}
return 0;
}
bool ParticleSystem::peekGpuStep(Entity entity, GpuStep& out) const {
auto it = states_.find(entity);
if (it == states_.end() || !it->second.gpu) return false;
const EmitterState& state = it->second;
out = {};
out.capacity = state.gpuCapacity;
// A frame that went long (a stall, a hidden tab) is not simulated as one huge step.
out.dt = std::min(state.gpuDt, 0.1f);
out.noiseTime = state.noise_time;
out.reset = state.gpuReset;
out.smoothCount = std::min(state.gpuSmooth, state.gpuCapacity);
out.spawnCount = std::min(out.smoothCount + state.gpuBurst, state.gpuCapacity);
out.firstIndex = state.gpuSpawned;
out.drawCount = std::min(state.gpuSpawned + out.spawnCount, state.gpuCapacity);
out.fed = state.gpuFed;
if (state.gpuFed) out.drawCount = state.gpuCapacity;
return true;
}
void ParticleSystem::commitGpuStep(Entity entity, const GpuStep& step) {
auto it = states_.find(entity);
if (it == states_.end() || !it->second.gpu) return;
EmitterState& state = it->second;
// A stall longer than a step is not replayed, and births past the ring's size were never going to be seen.
state.gpuDt = 0.0f;
state.gpuSmooth = state.gpuBurst = 0;
state.gpuSpawned += step.spawnCount;
if (step.reset) state.gpuReset = false;
}
u32 ParticleSystem::totalAliveParticles() const {
u32 total = 0;
for (const auto& [_, state] : states_) {
total += state.pool.aliveCount();
}
return total;
}
void ParticleSystem::forEachParticle(Entity entity,
const std::function<void(const Particle&)>& fn) const {
auto it = states_.find(entity);
if (it != states_.end()) {
it->second.pool.forEachAlive(fn);
}
}
EmitterState* ParticleSystem::getState(Entity entity) {
auto it = states_.find(entity);
return it != states_.end() ? &it->second : nullptr;
}
const EmitterState* ParticleSystem::getState(Entity entity) const {
auto it = states_.find(entity);
return it != states_.end() ? &it->second : nullptr;
}
void ParticleSystem::emitParticles(const ecs::ParticleEmitter& emitter,
const ecs::Transform& transform,
EmitterState& state, u32 count) {
const EmitterFrame frame{transform.worldPosition, transform.worldRotation,
transform.worldScale};
bool isWorldSpace = emitter.simulationSpace ==
static_cast<i32>(ecs::SimulationSpace::World);
emitInto(emitter, state, frame, isWorldSpace, glm::vec3(0.0f), count,
/*allowBirthTrigger=*/true);
}
void ParticleSystem::emitInto(const ecs::ParticleEmitter& emitter, EmitterState& state,
const EmitterFrame& frame, bool isWorldSpace,
glm::vec3 velocityBias, u32 count, bool allowBirthTrigger, u32 depth,
const EmitterFrame* storageFrame) {
// Record each spawned particle for a Birth-triggered sub-emitter (in world
// space, since a sub-burst is a world event).
bool recordBirth = allowBirthTrigger &&
emitter.subEmitter != 0 &&
emitter.subEmitterTrigger ==
static_cast<i32>(ecs::SubEmitterTrigger::Birth);
if (particle_limit_ != 0xffffffffu) {
const u32 alive = totalAliveParticles();
count = std::min(count, alive < particle_limit_ ? particle_limit_ - alive : 0u);
}
for (u32 i = 0; i < count; ++i) {
Particle* p = state.pool.allocate();
if (!p) {
break;
}
// A reused pool slot must start with an empty trail, not the dead
// particle's history.
if (emitter.trailEnabled && !state.trail_count.empty()) {
auto idx = static_cast<std::size_t>(p - state.pool.particles().data());
if (idx < state.trail_count.size()) state.trail_count[idx] = 0;
}
p->lifetime = randomRange(emitter.lifetimeMin, emitter.lifetimeMax);
p->age = 0.0f;
p->start_size = randomRange(emitter.startSizeMin, emitter.startSizeMax);
p->end_size = randomRange(emitter.endSizeMin, emitter.endSizeMax);
p->size = p->start_size;
p->start_color = emitter.startColor;
p->end_color = emitter.endColor;
p->color = p->start_color;
p->rotation = randomRange(emitter.rotationMin, emitter.rotationMax);
p->angular_velocity = randomRange(emitter.angularVelocityMin,
emitter.angularVelocityMax);
// ONE question to the shape, and the simulation asks nothing else: a new
// shape cannot teach the integrator a new kind of aim.
const SpawnSample sample =
sampleShape(emitter, [this](f32 a, f32 b) { return randomRange(a, b); });
p->position = isWorldSpace ? worldPointOf(sample.position, frame)
: sample.position * frame.scale;
const f32 speed = randomRange(emitter.speedMin, emitter.speedMax);
const glm::vec3 dir = isWorldSpace ? worldDirOf(sample.direction, frame)
: sample.direction;
p->velocity = dir * speed + velocityBias;
p->added_velocity = glm::vec3(randomRange(emitter.addedVelocityMin.x, emitter.addedVelocityMax.x),
randomRange(emitter.addedVelocityMin.y, emitter.addedVelocityMax.y),
randomRange(emitter.addedVelocityMin.z, emitter.addedVelocityMax.z));
p->sprite_frame = 0;
p->subEmitterDepth = depth;
if (recordBirth) {
glm::vec3 worldPos = isWorldSpace ? p->position
: frame.position + frame.rotation * p->position;
glm::vec3 worldVel = isWorldSpace ? p->velocity : frame.rotation * p->velocity;
subemit_requests_.push_back({worldPos, worldVel, p->subEmitterDepth});
}
if (storageFrame) {
const auto inverseRotation = glm::inverse(storageFrame->rotation);
p->position = inverseRotation * (p->position - storageFrame->position);
p->velocity = inverseRotation * p->velocity;
}
}
}
u32 ParticleSystem::emitAt(ecs::Registry& registry, Entity entity, u32 count, const glm::vec3& position,
const glm::vec3& normal, const glm::vec3& velocity) {
if (count == 0 || !registry.valid(entity) || !registry.has<ecs::ParticleEmitter>(entity)) return 0;
const auto& emitter = registry.get<ecs::ParticleEmitter>(entity);
if (emitter.gpuSimulation && gpu_available_) return 0;
auto it = states_.find(entity);
if (it == states_.end()) {
it = states_.emplace(entity, EmitterState(static_cast<u32>(std::clamp(emitter.maxParticles, 0, 1'000'000)))).first;
}
EmitterState& state = it->second;
if (state.gpu) return 0;
glm::quat rotation(1.0f, 0.0f, 0.0f, 0.0f);
glm::vec3 scale(1.0f);
EmitterFrame storage;
if (registry.has<ecs::Transform>(entity)) {
const auto& t = registry.get<ecs::Transform>(entity);
rotation = t.worldRotation;
scale = t.worldScale;
storage = {t.worldPosition, t.worldRotation, t.worldScale};
}
const f32 n = glm::length(normal);
if (n > 1e-6f) {
// The shortest turn from +Y onto the normal; straight down is a half turn about X.
const glm::vec3 to = normal / n;
const f32 d = glm::dot(glm::vec3(0.0f, 1.0f, 0.0f), to);
if (d < -0.9999f) rotation = glm::quat(0.0f, 1.0f, 0.0f, 0.0f);
else {
const glm::vec3 axis = glm::cross(glm::vec3(0.0f, 1.0f, 0.0f), to);
rotation = glm::normalize(glm::quat(1.0f + d, axis.x, axis.y, axis.z));
}
}
const bool local = emitter.simulationSpace == static_cast<i32>(ecs::SimulationSpace::Local);
const u32 before = state.pool.aliveCount();
emitInto(emitter, state, EmitterFrame{position, rotation, scale}, /*isWorldSpace=*/true, velocity, count,
/*allowBirthTrigger=*/true, 0, local ? &storage : nullptr);
return state.pool.aliveCount() - before;
}
void ParticleSystem::drainSubEmitters(ecs::Registry& registry, Entity parent, Entity child,
f32 inheritVelocity, f32 chance) {
// Take ownership of the queue up front: emitInto below spawns into the child
// with allowBirthTrigger=false, so it never re-enters this buffer, but swapping
// also leaves the member clean if the child reference is stale.
std::vector<SubEmitRequest> requests;
requests.swap(subemit_requests_);
if (child == parent || !registry.valid(child) || !registry.has<ecs::ParticleEmitter>(child)) {
return; // a deleted/retargeted child just drops its bursts
}
const auto& childEmitter = registry.get<ecs::ParticleEmitter>(child);
// The child's own state may not exist yet (it's created lazily when the main
// loop reaches it); make it on demand so a burst is never lost.
auto it = states_.find(child);
if (it == states_.end()) {
auto [insertIt, _] = states_.emplace(
child, EmitterState(static_cast<u32>(std::clamp(childEmitter.maxParticles, 0, 1'000'000))));
it = insertIt;
}
EmitterState& childState = it->second;
EmitterFrame storageFrame;
const bool local = childEmitter.simulationSpace == static_cast<i32>(ecs::SimulationSpace::Local);
if (local && registry.has<ecs::Transform>(child)) {
const auto& transform = registry.get<ecs::Transform>(child);
storageFrame = {transform.worldPosition, transform.worldRotation, transform.worldScale};
}
// The child's burstCount sizes each sub-burst (fall back to 1 so a misconfigured
// template still shows something).
u32 count = childEmitter.burstCount > 0 ? static_cast<u32>(childEmitter.burstCount) : 1;
count = std::min(count, childState.pool.capacity());
for (const auto& req : requests) {
if (req.depth >= 8) continue;
if (chance < 1.0f && randomRange(0.0f, 1.0f) >= chance) {
continue;
}
// A sub-burst happens where the parent particle died, unrotated and
// unscaled: the child's own shape is what aims it, and a particle carries
// no orientation to inherit.
emitInto(childEmitter, childState, EmitterFrame{req.position, glm::quat(1, 0, 0, 0),
glm::vec3(1.0f)}, /*isWorldSpace=*/true,
req.velocity * inheritVelocity, count, /*allowBirthTrigger=*/false, req.depth + 1,
local ? &storageFrame : nullptr);
}
}
// Sample a baked color-over-life LUT at t∈[0,1] with linear interpolation between
// the two nearest entries — the editor authors a gradient, TS bakes it to this.
static glm::vec4 sampleColorLut(const ColorLut& lut, f32 t) {
f32 f = std::clamp(t, 0.0f, 1.0f) * static_cast<f32>(kColorLutSize - 1);
auto i = static_cast<std::size_t>(f);
std::size_t j = std::min(i + 1, static_cast<std::size_t>(kColorLutSize - 1));
return math::lerp(lut[i], lut[j], f - static_cast<f32>(i));
}
static f32 sampleSizeLut(const SizeLut& lut, f32 t) {
f32 f = std::clamp(t, 0.0f, 1.0f) * static_cast<f32>(kColorLutSize - 1);
auto i = static_cast<std::size_t>(f);
std::size_t j = std::min(i + 1, static_cast<std::size_t>(kColorLutSize - 1));
return math::lerp(lut[i], lut[j], f - static_cast<f32>(i));
}
// Fold one force field into a world-space particle's velocity.
static void applyForceField(const ForceFieldInstance& ff, Particle& p, f32 dt) {
glm::vec3 toField = ff.position - p.position; // field ← particle
// The zone is a ball: a radius that drops depth pulls on particles a room away.
f32 distSq = toField.x * toField.x + toField.y * toField.y + toField.z * toField.z;
f32 factor = 1.0f;
if (ff.radius > 0.0f) {
if (distSq > ff.radiusSq) return; // outside the zone
if (ff.falloff) factor = 1.0f - std::sqrt(distSq) / ff.radius;
}
switch (static_cast<ecs::ForceFieldType>(ff.type)) {
case ecs::ForceFieldType::Directional:
p.velocity += ff.direction * (ff.strength * factor * dt);
break;
case ecs::ForceFieldType::Point: {
f32 d = std::sqrt(distSq);
if (d > 1e-4f) p.velocity += (toField / d) * (ff.strength * factor * dt);
break;
}
case ecs::ForceFieldType::Vortex: {
f32 d = std::sqrt(distSq);
if (d > 1e-4f) {
glm::vec3 radial = -toField / d; // field → particle
// A vortex needs an axis to swirl about, and the field's own
// direction is the one it has; world up when it names none.
glm::vec3 axis = glm::length(ff.direction) > 1e-6f
? glm::normalize(ff.direction) : glm::vec3(0.0f, 0.0f, 1.0f);
glm::vec3 perp = glm::cross(axis, radial);
f32 pl = glm::length(perp);
if (pl > 1e-6f) p.velocity += (perp / pl) * (ff.strength * factor * dt);
}
break;
}
case ecs::ForceFieldType::Drag:
p.velocity *= (1.0f - std::min(ff.strength * factor * dt, 1.0f));
break;
}
}
void ParticleSystem::updateParticles(const ecs::ParticleEmitter& emitter,
EmitterState& state, f32 dt,
const ColorLut* colorLut, const SizeLut* sizeLut,
const SizeLut* speedLut,
const EmitterFrame& frame,
bool isWorldSpace) {
auto sizeEasing = static_cast<EasingType>(emitter.sizeEasing);
auto colorEasing = static_cast<EasingType>(emitter.colorEasing);
i32 totalFrames = emitter.spriteColumns * emitter.spriteRows;
// Record dying particles for a Death-triggered sub-emitter (world space — a
// sub-burst is a world event). cos/sin convert a local-space death to world.
bool recordDeath = emitter.subEmitter != 0 &&
emitter.subEmitterTrigger ==
static_cast<i32>(ecs::SubEmitterTrigger::Death);
// Noise/Turbulence: a curl-noise flow field advected onto position. Strength 0
// samples nothing (the whole module is free when unused). The scroll offset
// drifts the field over a monotonic clock so pausing emission never snaps it.
state.noise_time += dt;
bool noiseOn = emitter.noiseStrength > 0.0f && emitter.noiseFrequency > 0.0f;
glm::vec2 noiseScroll(emitter.noiseScrollSpeed * state.noise_time *
emitter.noiseFrequency);
bool trailOn = emitter.trailEnabled && !state.trail_count.empty();
int trailKeep = std::clamp(emitter.trailPoints, 2, kMaxTrailPoints);
f32 trailMinDistSq = emitter.trailMinDistance * emitter.trailMinDistance;
bool collisionOn = emitter.collisionEnabled;
dead_particle_indices_.clear();
state.collisionOrdinal = 0;
state.pool.forEachAlive([&](Particle& p) {
p.age += dt;
if (p.age >= p.lifetime) {
if (recordDeath) {
glm::vec3 worldPos = isWorldSpace ? p.position
: frame.position + frame.rotation * p.position;
glm::vec3 worldVel = isWorldSpace ? p.velocity : frame.rotation * p.velocity;
subemit_requests_.push_back({worldPos, worldVel, p.subEmitterDepth});
}
u32 idx = static_cast<u32>(&p - &state.pool.particles()[0]);
dead_particle_indices_.push_back(idx);
return;
}
f32 t = p.age / p.lifetime;
p.velocity += emitter.gravity * dt;
if (isWorldSpace && !force_fields_.empty()) {
for (const auto& ff : force_fields_) applyForceField(ff, p, dt);
}
if (emitter.damping > 0.0f) {
p.velocity *= (1.0f - emitter.damping * dt);
}
if (emitter.speedLimit > 0.0f) {
p.velocity = limitedVelocity(p.velocity, emitter.speedLimit, emitter.limitDampen, dt);
}
// Applied to the STEP, not to velocity, so speed-over-life cannot become
// a second force system: gravity, damping and noise still accumulate into
// velocity exactly as before.
const glm::vec3 collisionFrom = p.position;
p.position += (p.velocity * (speedLut ? sampleSizeLut(*speedLut, t) : 1.0f) + p.added_velocity) * dt;
if (noiseOn) {
// The curl field is a 2D flow, sampled on the plane the particle is
// over. Depth passes through it: turbulence that also pushed on z
// would be a different field, not this one read further.
glm::vec2 sample = glm::vec2(p.position) * emitter.noiseFrequency + noiseScroll;
glm::vec2 flow = noise::curl(sample, emitter.noiseOctaves);
p.position += glm::vec3(flow, 0.0f) * emitter.noiseStrength * dt;
}
if (collisionOn) {
collisionStep(emitter, state, p, collisionFrom, frame, isWorldSpace);
if (p.age >= p.lifetime) {
dead_particle_indices_.push_back(static_cast<u32>(&p - state.pool.particles().data()));
return;
}
}
// Record the settled position into this particle's trail ring (oldest→newest),
// gated by trailMinDistance so a slow particle doesn't pile up coincident points.
if (trailOn) {
auto idx = static_cast<std::size_t>(&p - state.pool.particles().data());
u8& cnt = state.trail_count[idx];
glm::vec3* ring = &state.trail_pos[idx * kMaxTrailPoints];
bool record = cnt == 0;
if (!record) {
glm::vec3 d = p.position - ring[cnt - 1];
record = glm::dot(d, d) >= trailMinDistSq;
}
if (record) {
if (cnt < trailKeep) {
ring[cnt++] = p.position;
} else {
for (int k = 1; k < trailKeep; ++k) ring[k - 1] = ring[k];
ring[trailKeep - 1] = p.position;
}
}
}
p.rotation += p.angular_velocity * dt;
if (sizeLut) {
p.size = p.start_size * sampleSizeLut(*sizeLut, t);
} else {
f32 sizeT = applyEasing(sizeEasing, t);
p.size = math::lerp(p.start_size, p.end_size, sizeT);
}
if (colorLut) {
p.color = sampleColorLut(*colorLut, t);
} else {
f32 colorT = applyEasing(colorEasing, t);
p.color = math::lerp(p.start_color, p.end_color, colorT);
}
if (totalFrames > 1 && emitter.spriteFPS > 0.0f) {
f32 frameDuration = 1.0f / emitter.spriteFPS;
f32 rawFrame = p.age / frameDuration;
// Compute the wrap on the float (fmod) so a looping sheet actually
// cycles: clamping to [0,totalFrames-1] first would make the modulo an
// identity and freeze every particle on the last frame after one pass.
u16 frame;
if (emitter.spriteLoop) {
frame = static_cast<u16>(std::fmod(rawFrame, static_cast<f32>(totalFrames)));
} else {
frame = static_cast<u16>(std::min(rawFrame, static_cast<f32>(totalFrames - 1)));
}
p.sprite_frame = frame;
}
});
for (u32 idx : dead_particle_indices_) {
state.pool.deallocateByIndex(idx);
}
}
f32 ParticleSystem::randomRange(f32 min, f32 max) {
if (min >= max) {
return min;
}
std::uniform_real_distribution<f32> dist(min, max);
return dist(rng_);
}
// An aim in the emitter's own plane: an angle names a direction there, and the
// emitter's rotation is what turns the plane. Aiming out of it is the emitter's
// job to be turned, not this one's to invent a second angle nobody authored.
namespace {
bool finitePoint(glm::vec3 p) { return std::isfinite(p.x) && std::isfinite(p.y) && std::isfinite(p.z); }
f32 unitValue(f32 x) { return std::isfinite(x) ? std::clamp(x, 0.0f, 1.0f) : 0.0f; }
}
void ParticleSystem::collisionStep(const ecs::ParticleEmitter& emitter, EmitterState& state,
Particle& p, glm::vec3 from, const EmitterFrame& frame, bool world) {
const u32 ordinal = state.collisionOrdinal++;
if (emitter.collisionMode == 0) { floorCollision(emitter, state, p, frame, world); return; }
if (emitter.collisionMode == static_cast<i32>(ecs::ParticleCollisionMode::Sdf)) { sdfCollision(emitter, state, p, frame, world); return; }
auto& stats = collision_stats_[collision_stats_index_];
auto fallback = [&] {
if (emitter.collisionFallback == 0) { ++stats.fallbacks; floorCollision(emitter, state, p, frame, world); }
};
// Depth is a picture only the GPU keeps; here it is what it is on any other unknown mode.
if (emitter.collisionMode != 1 && emitter.collisionMode != 2) { ++stats.unavailable; fallback(); return; }
const glm::vec3 start = world ? from : frame.position + frame.rotation * from;
const glm::vec3 end = world ? p.position : frame.position + frame.rotation * p.position;
glm::vec3 delta = end - start;
if (emitter.collisionMode == 1) delta.z = 0; // 2D queries never invent depth.
if ((emitter.collisionMask & 0xffffu) == 0) return;
if (!finitePoint(start) || !finitePoint(end) || !std::isfinite(glm::dot(delta,delta)) || glm::dot(delta, delta) < 1e-12f) return;
if (std::isfinite(emitter.collisionMaxDistance) && emitter.collisionMaxDistance > 0 && !collision_cameras_.empty()) {
const f32 maxSq = emitter.collisionMaxDistance * emitter.collisionMaxDistance;
bool near = false;
for (auto camera : collision_cameras_) {
const auto offset = end - camera;
if (glm::dot(offset, offset) <= maxSq) { near = true; break; }
}
if (!near) { ++stats.distanceSkipped; fallback(); return; }
}
const u32 slot = static_cast<u32>(&p - state.pool.particles().data());
const u32 limit = std::min(static_cast<u32>(std::clamp(emitter.collisionQueryBudget, 0, 4096)), collision_quotas_[collision_emitter_]);
const u32 alive = std::max(1u,state.pool.aliveCount());
const u32 rank = (ordinal + alive - state.collisionCursor % alive) % alive;
if (rank >= limit || stats.queries >= limit || collision_queries_.size() >= query_budget_) {
++stats.budgetSkipped; fallback(); return;
}
collision_queries_.push_back({collision_emitter_.raw, slot, static_cast<u32>(emitter.collisionMode),
emitter.collisionMask & 0xffffu, start.x,start.y,start.z,delta.x,delta.y,delta.z});
collision_pending_.push_back({collision_emitter_, p.generation, frame, world, collision_stats_index_});
++stats.queries;
}
void ParticleSystem::floorCollision(const ecs::ParticleEmitter& emitter, EmitterState& state,
Particle& p, const EmitterFrame& frame, bool world) {
const glm::vec3 point = world ? p.position : frame.position + frame.rotation * p.position;
const glm::vec3 velocity = world ? p.velocity : frame.rotation * p.velocity;
if (std::isfinite(emitter.collisionFloor) && point.y < emitter.collisionFloor && velocity.y < 0) {
collide(emitter, state, p, {point.x,emitter.collisionFloor,point.z}, {0,1,0}, 0xffffffffu, frame, world);
}
}
f32 sdfDistance(const SdfColliderInstance& c, const glm::vec3& point) {
const glm::vec3 q = glm::inverse(c.rotation) * (point - c.position);
f32 d = 0.0f;
if (c.shape > 1.5f) {
const f32 along = std::clamp(q.y, -c.ext[1], c.ext[1]);
d = glm::length(glm::vec3(q.x, q.y - along, q.z)) - c.ext[0];
} else if (c.shape > 0.5f) {
const glm::vec3 over = glm::abs(q) - glm::vec3(c.ext[0], c.ext[1], c.ext[2]);
d = glm::length(glm::max(over, glm::vec3(0.0f))) + std::min(std::max({over.x, over.y, over.z}), 0.0f);
} else {
d = glm::length(q) - c.ext[0];
}
return c.inverted > 0.5f ? -d : d;
}
void ParticleSystem::sdfCollision(const ecs::ParticleEmitter& emitter, EmitterState& state, Particle& p,
const EmitterFrame& frame, bool world) {
const glm::vec3 point = world ? p.position : frame.position + frame.rotation * p.position;
const glm::vec3 velocity = world ? p.velocity : frame.rotation * p.velocity;
const SdfColliderInstance* nearest = nullptr;
f32 least = 0.0f;
for (const SdfColliderInstance& c : sdf_colliders_) {
if ((c.mask & emitter.collisionMask) == 0) continue;
const f32 d = sdfDistance(c, point);
if (d < least) { least = d; nearest = &c; }
}
if (!nearest) return;
// The way out of the shape, measured: the same answer whichever shape it is.
const f32 e = std::max(0.01f, -least * 0.1f);
const glm::vec3 gradient(
sdfDistance(*nearest, point + glm::vec3(e, 0, 0)) - sdfDistance(*nearest, point - glm::vec3(e, 0, 0)),
sdfDistance(*nearest, point + glm::vec3(0, e, 0)) - sdfDistance(*nearest, point - glm::vec3(0, e, 0)),
sdfDistance(*nearest, point + glm::vec3(0, 0, e)) - sdfDistance(*nearest, point - glm::vec3(0, 0, e)));
const f32 size = glm::length(gradient);
if (size < 1e-6f) return;
const glm::vec3 normal = gradient / size;
if (glm::dot(velocity, normal) >= 0.0f) return;
collide(emitter, state, p, point - normal * least, normal, 0xffffffffu, frame, world);
}
void ParticleSystem::addGpuCollisions(Entity entity, u32 total, const CollisionEvent* events, u32 count) {
gpu_collisions_.push_back({entity, total, std::vector<CollisionEvent>(events, events + count)});
}
void ParticleSystem::collide(const ecs::ParticleEmitter& emitter, EmitterState& state, Particle& p,
glm::vec3 point, glm::vec3 normal, u32 body, const EmitterFrame& frame, bool world) {
auto& stats = collision_stats_[collision_stats_index_];
const u32 slot = static_cast<u32>(&p - state.pool.particles().data());
glm::vec3 velocity = world ? p.velocity : frame.rotation * p.velocity;
const glm::vec3 incoming = velocity;
const f32 approach = glm::dot(velocity, normal);
if (approach < 0) {
velocity = (velocity - normal * approach) * (1 - unitValue(emitter.collisionFriction))
- normal * approach * unitValue(emitter.collisionBounce);
}
p.position = world ? point : glm::inverse(frame.rotation) * (point - frame.position);
p.velocity = world ? velocity : glm::inverse(frame.rotation) * velocity;
p.age += unitValue(emitter.collisionLifetimeLoss) * p.lifetime;
++stats.hits;
const bool child = emitter.subEmitter != 0 && emitter.subEmitterTrigger == static_cast<i32>(ecs::SubEmitterTrigger::Collision);
if (emitter.collisionEvents || child || collision_debug_) {
const u32 perEmitter = static_cast<u32>(std::clamp(emitter.collisionEventBudget, 0, 1024));
if (stats.events < perEmitter && event_attempts_ < event_budget_) {
++stats.events; ++event_attempts_;
if (emitter.collisionEvents || collision_debug_) collision_events_.push_back({collision_emitter_.raw,slot,body,stats.mode,
point.x,point.y,point.z,normal.x,normal.y,normal.z,incoming.x,incoming.y,incoming.z,emitter.collisionEvents ? 1u : 0u});
if (child && p.subEmitterDepth < 8 && collision_child_bursts_ < event_budget_) {
subemit_requests_.push_back({point,velocity,p.subEmitterDepth}); ++collision_child_bursts_;
}
} else ++stats.eventDropped;
}
if (p.age >= p.lifetime && emitter.subEmitter != 0 && emitter.subEmitterTrigger == static_cast<i32>(ecs::SubEmitterTrigger::Death))
subemit_requests_.push_back({point,velocity,p.subEmitterDepth});
}
void ParticleSystem::resolveCollisions(ecs::Registry& registry, const CollisionReply* replies, u32 count) {
// Consume once. A stale/repeated reply cannot bounce a particle twice.
for (std::size_t i = 0; i < collision_queries_.size(); ++i) {
const auto& query = collision_queries_[i]; const auto& pending = collision_pending_[i];
if (!registry.valid(pending.emitter) || !registry.has<ecs::ParticleEmitter>(pending.emitter)) continue;
auto stateIt = states_.find(pending.emitter);
if (stateIt == states_.end() || query.slot >= stateIt->second.pool.capacity()) continue;
auto& state = stateIt->second; auto& p = state.pool.particles()[query.slot];
if (!p.alive || p.generation != pending.generation) continue;
const auto& emitter = registry.get<ecs::ParticleEmitter>(pending.emitter);
if (!emitter.enabled || !emitter.collisionEnabled) continue;
collision_emitter_ = pending.emitter; collision_stats_index_ = pending.stats;
auto& stats = collision_stats_[pending.stats];
const CollisionReply reply = replies && i < count ? replies[i] : CollisionReply{2,0,0,0,0,0,0,0};
if (reply.status == 1) {
glm::vec3 normal(reply.nx,reply.ny,reply.nz), point(reply.x,reply.y,reply.z);
if (query.mode == 1) { normal.z = 0; point.z = pending.world ? p.position.z : (pending.frame.position + pending.frame.rotation * p.position).z; }
const f32 normSq = glm::dot(normal,normal);
const glm::vec3 from(query.ox,query.oy,query.oz), delta(query.dx,query.dy,query.dz);
// A provider must report a finite point on this segment; invalid replies
// are unavailable queries (same explicit fallback), never teleports.
const f32 deltaSq = glm::dot(delta,delta);
const f32 fraction = glm::dot(point - from,delta) / deltaSq;
glm::vec3 offset = point - (from + delta * fraction);
if (query.mode == 1) offset.z = 0;
if (finitePoint(normal) && finitePoint(point) && std::isfinite(normSq) && normSq > 1e-12f &&
fraction >= -1e-4f && fraction <= 1.0001f && glm::dot(offset,offset) <= std::max(1e-6f,deltaSq*1e-6f)) {
normal /= std::sqrt(normSq);
if (glm::dot(delta,normal) > 0) normal = -normal;
collide(emitter,state,p,point + normal * 1e-4f,normal,reply.body,pending.frame,pending.world);
} else { ++stats.unavailable; if (emitter.collisionFallback == 0) { ++stats.fallbacks; floorCollision(emitter,state,p,pending.frame,pending.world); } }
} else if (reply.status != 0) {
++stats.unavailable;
if (emitter.collisionFallback == 0) { ++stats.fallbacks; floorCollision(emitter,state,p,pending.frame,pending.world); }
}
if (query.slot < state.trail_count.size() && state.trail_count[query.slot] > 0) {
const auto last = static_cast<std::size_t>(query.slot)*kMaxTrailPoints + state.trail_count[query.slot]-1;
state.trail_pos[last] = p.position;
}
if (p.age >= p.lifetime) state.pool.deallocateByIndex(query.slot);
if (!subemit_requests_.empty()) drainSubEmitters(registry,pending.emitter,Entity::fromRaw(emitter.subEmitter),emitter.subEmitterInheritVelocity,emitter.subEmitterChance);
}
collision_queries_.clear(); collision_pending_.clear();
}
} // namespace esengine::particle