DrawableParticles

Extends: Drawable

Emits and simulates lightweight particles (lines, rectangles, or images) with randomized velocity, constant acceleration, and lifetime-driven fade/color/size interpolation. Draws through a single SceneObjectParticle per emitter rather than one SceneObject per particle, so spawning/expiring particles never touches Renderer.addSceneObject/removeSceneObject - see specs/2026-08-18-particle-system-design.md for why that matters for depth-sort performance.

Properties

shape (ParticleShape) — Shape drawn for every particle. See BGE.ParticleShape.
image (dynamic) — Bitmap or region drawn for each particle when shape = BGE.ParticleShape.Image.
cellWidth (integer) — Width/height (pixels) of one animation cell if image is a sprite sheet, the
cellHeight (integer)
regions (Array.<roRegion>)
spawnRate (float) — Particles spawned per second while emitting (see start()/stop()).
lifetime (float) — Base lifetime in seconds each particle survives, randomized by +/- lifetimeSpread.
lifetimeSpread (float)
velocity (BGE.Math.Vector) — Base emission velocity (world units/second) shared by every particle before
velocitySpreadAngleDegrees (float) — Randomizes each particle's velocity direction by +/- this many degrees around
velocitySpreadMagnitude (float) — Randomizes each particle's velocity magnitude by +/- this amount. If velocity
acceleration (BGE.Math.Vector) — Constant acceleration (world units/second^2) applied to every particle every
startColor (integer) — Packed RGB (0xRRGGBB) color interpolated over each particle's lifetime.
endColor (integer)
startAlpha (float) — Alpha (0-255) interpolated over each particle's lifetime.
endAlpha (float)
startSize (float) — Size interpolated over each particle's lifetime - a line's length, a rectangle's
endSize (float)
rotationSpeed (float) — Degrees/second of rotation applied to each particle. Only used when
maxParticles (integer) — Hard cap on live particles. Once reached, further spawns (continuous emission or
particles (Array.<BGE.ParticleRecord>) — Live particle records. See BGE.ParticleRecord.
emitting (boolean)
spawnAccumulator (float)
timer (dynamic)

Constructor

new DrawableParticles(
owner: GameEntity,
shape: ParticleShape,
args?: roAssociativeArray,
): DrawableParticles

Parameters

owner (GameEntity)
shape (ParticleShape)
args (roAssociativeArray, optional, default: "{}")

Instance Methods

`start(): void`

Starts continuous emission at spawnRate particles/second.

Returns

void

`stop(): void`

Stops continuous emission. Already-live particles keep simulating and drawing until they expire naturally.

Returns

void

`burst(count: integer): void`

Immediately spawns count particles, regardless of start()/stop() state.

Parameters

count (integer) — number of particles to spawn right now

Returns

void

`addToRenderer(renderer: Renderer): BGE.SceneObject`

Parameters

renderer (Renderer)

Returns

BGE.SceneObject

`update(): void`

Returns

void

`getFrameRegions(): Array.<roRegion>`

Lazily slices image into a row-major grid of cellWidth x cellHeight regions (built once, cached) - mirrors Sprite.setCellRegions()'s exact slicing convention.

Caches on first call - reassigning image/cellWidth/cellHeight after that has no effect on an already-built cache.

Returns

Array.<roRegion> — the per-frame regions, or invalid if this emitter isn't configured as a sprite sheet (cellWidth/cellHeight are 0) or image isn't set yet