Sistema di particelle in JavaScript: burst, pool e culling

Documentazione – BeeEngine

v2.9.7

BeeParticleSystem — Documentazione Tecnica

Burst di cerchi: emit, pool senza reclaim, culling sul rettangolo vivo

📁 Panoramica

BeeParticleSystem è un burst di cerchi pieni. Estende BeeEntity. Vive in src/graphics/BeeParticleSystem.js. Lo crei e lo metti nel gioco con gioco.addEntity. Il loop chiama update e draw.

Ogni particella nasce in coordinate mondo, da worldX / worldY al momento di emit. Il disegno è un arc in quello stesso spazio, sul pass mondo (dopo camera.apply). Il pool interno non fa new né filter a ogni frame: i morti tornano in particlePool e l’array si compatta.

const burst = new BeeParticleSystem({ x: hero.worldX, y: hero.worldY }); gioco.addEntity(burst); burst.emit(24, { color: ‘#ffcc66’ });

📁 Vita

Angolo casuale sul cerchio intero. Velocità, vita e size escono dal range dell’emit. Un solo color per burst.

1. emitPrende dal pool. Oltre max non aggiunge (niente reclaim). destroyed, count non finito o ≤ 0: return.
2. updatelife -= dt, poi x/y += v * dt. life ≤ 0: release. active === false: freeze.
3. drawCerchio, alpha life / maxLife. maxLife ≤ 0: alpha 0. Il culling usa il box delle particelle vive.

📁 Dove è facile sbagliare

Il pool pieno non ruba. reclaim è false. Raggiunto max (default 512, prewarm initial 64), le emit in più non creano particelle. Quelle vive restano fino a fine vita.

Nascono in mondo e restano lì. Sposti l’emitter: il burst già uscito non lo segue. La prossima emit legge di nuovo worldX / worldY. Dopo la simulazione delle particelle gira BeeEntity.update: la gravità sull’emitter non piega i cerchi già emessi.

Pausa e teardown. active = false lascia vita e posizione com’erano. destroy e dispose svuotano particlePool e particles. Un emit dopo destroy non fa nulla.

Culling sul burst. getWorldAABB racchiude le particelle vive (centro ± size). Lista vuota: lati 0, e drawEntity chiama lo stesso draw (il loop non ha nulla da disegnare).

📁 Esempio: impatto

const burst = new BeeParticleSystem({ x: hero.worldX, y: hero.worldY, max: 128 }); gioco.addEntity(burst); burst.emit(24, { color: ‘#ffcc66’, speedMin: 40, speedMax: 180, lifeMin: 0.2, lifeMax: 0.6 });

dt non finito o ≤ 0 non sposta e non consuma vita. Le particelle già a life ≤ 0 vengono comunque rilasciate.

📁 Riepilogo API

Estende BeeEntity: x / y, worldX / worldY, active, visible, addEntity. Il pool è un BeePool con reclaim: false.

Membro	Ritorna	Scopo
`new BeeParticleSystem({ x, y, initial, max }?)`	`BeeParticleSystem`	`initial` 64, `max` 512. `particles` vuoto.
`emit(count?, options?)`		Default count 10. `speedMin` 30, `speedMax` 120, `lifeMin` 0.3, `lifeMax` 1, `sizeMin` 2, `sizeMax` 6, `color` `'orange'`. Origine: mondo dell’emitter.
`update(dt, input?, engine?)`		Moto rettilineo e vita. `destroyed` o `active === false`: return. Poi `super.update`.
`draw(ctx)`		Cerchio pieno. Alpha `life / maxLife`, oppure 0. `visible === false`: return.
`getWorldAABB()`	`{ x, y, width, height }`	Unione delle particelle vive, ± `size`. Lista vuota: lati 0. Stesso oggetto riusato.
`destroy()` / `dispose()`		`particlePool.clear()` e `particles.length = 0`, poi `BeeEntity`.
`particles` / `particlePool`	array / `BeePool`	Lista viva e pool. `inUse` / `available` sul pool.