Particles

This section provides guidance on setting up Particles. Studio has a built-in particle system component intended for rendering common visual effects found in games and animations.

Particles can be added to the entity via the Studio interface or in code. Adding them in Studio is done via the "New Component" button.

Like most particle engines, parameters fall into two categories, emission and simulation.

Emission

Emission attributes define the way particles are placed into the world and some of the global attributes that affect every particle equally.

• Stopped: If checked the emitter will not emit.
• Emitter Life: Defines the lifetime of the emitter
• Particles Per Shot: How many particles are placed every time the emitter fires.
• Emit Delay: delay between emissions in seconds.
• Lifespan: Sets a range representing the time particles remain in the scene before despawning.
• Mass: the mass of each particle, only relevant when simulating physics
• Gravity: adds a force downwards that makes particles fall.
• Forces: simple forces in the X, Y and Z relative axis that are applied to every particle.
• Spread: is the angle the particles move in relation to the emitter.
• Radial Velocity: if set above 0, the emitter velocity type will change to radial. Radial Velocity is calculated relative to the observer and vectorial forces are influenced by radial force.

Spawn Area Type

Spawn areas change the starting coordinate of the particles.

• Point: Spawn is set to the coordinates of the emitter.
• Box: Defines a box using width, height and depth.
• Sphere: Defines a spawn area of a sphere with a defined radius.

note

These spawn areas won't work properly if dimensions are set to 0.

Bounding zone Type

Bounding boxes dictate the spatial boundaries within which particles are generated.

• Box: Defines a box using width, height and depth.
• Sphere: Defines a spawn area of a sphere with a defined radius.

note

These bounding zones won’t work properly if dimensions are set to 0 or negative. If using Spawn Area, the bounding zone needs to occupy a bigger volume than the Spawn Area.

Resource Type

This system is able to render glb assets and simple sprites. Choose a model for 3D or sprite for 2D sprites. Use a publicly accessible url to load the asset to the emitter.

• Sprites: They have blending options that work similarly to basic photoshop layer effects. These are very handy when creating visual effects like fire, stars or smoke.

Simulation

These parameters will affect the way particles behave on their own after being placed in the world.

• Color: If sprites are set as a resource type then sprites can change color. Input a hex value of the starting and ending color for them to shift gradually.
• Random drift: particles will randomly drift in accordance with the random drift range parameter.
• Collision: If particles get near each other an opposite force will be applied between them.

Parameters

Name	Type	Description
stopped	bool	Switching states will reset emitterLife.
emitterLife number	The life of the emitter in seconds
particlesPerShot	number	Particles each emission
emitDelay	number	Delay between emissions
minimumLifespan	number	Min. range for particle lifetime
maximumLifespan	number	Max. range for particle lifetime
mass	number	Mass of the entity
gravity	number	Gravity
scale	number	Scale in every dimension
forceX	number	Force applied to particle in X
forceY	number	Force applied to particle in Y
forceZ	number	Force applied to particle in Z
spread	number	Area and direction where the particle spawns relative to its origin
radialVelocity	number	Can be set to 0, else changes the force type applied to each particle to radial velocity
spawnAreaType	[point, box, sphere]	Point: from origin
spawnAreaWidth	number	SpawnArea width for box type
spawnAreaHeight	number	Spawn Area Height for box type
spawnAreaDepth	number	Spawn Area Depth for box type
spawnAreaRadius	number	Spawn Area radius for sphere type
boundingZoneType	[none, box, sphere]	Bounding Zone type
boundingZoneWidth	number	Bounding Zone width for box type
boundingZoneHeight	number	Bounding Zone height for box type
boundingZoneDepth	number	Bounding Zone depth for box type
boundingZoneRadius	number	Bounding Zone radius for sphere type
resourceType	[sprite, model]	Sprite: an image, Model: 3d model
resourceUrl	string	URL
blendingMode	[none, normal, add, multiply, subtract]	Only works for sprite. See examples here
animateColor	bool	Enables color animation
colorStart	Color String in hex, example: #fcba03	Starting color
colorEnd	Color String in hex, example: #fcba03	Ending color
randomDrift	bool	Enable Drift
randomDriftRange	number	Drift range and speed
collisions	bool	Enable collisions

Examples

GLB emitter

ecs.ParticleEmitter.set(world, component.eid, {
    stopped: false,
    emitterLife: 10,
    particlesPerShot: 5,
    emitDelay: 1,
    minimumLifespan: 1,
    maximumLifespan: 3,
    mass: 1,
    gravity: 1,
    scale: 1,
    forceX: 0,
    forceY: 60,
    forceZ: 0,
    spread: 120,
    radialVelocity: 0,
    spawnAreaType: 'point',
    resourceType: 'model',
    resourceUrl: 'https://static.8thwall.app/assets/Moon-lowpoly-v3-yg6nmdc1uj.glb',
})

Turn the emitter on after creation

If we want to initialize an emitter with the attribute ‘stopped’ set to true like so:

ecs.ParticleEmitter.set(world, component.eid, {
    stopped: true,
	//....,
})

We can manually turn it back on like this:

ecs.ParticleEmitter.set(world, component.eid, {stopped: false})