Class SolidParticleSystem
Hierarchy
- SolidParticleSystem
Implements
Index
Constructors
Properties
Accessors
Methods
- add
Shape - after
Update Particles - before
Update Particles - build
Mesh - compute
Sub Meshes - digest
- dispose
- get
Particle By Id - get
Particles By Shape Id - get
Particles By Shape Id To Ref - init
Particles - insert
Particles From Array - picked
Particle - rebuild
Mesh - recycle
Particle - refresh
Visible Size - remove
Particles - set
Multi Material - set
Particles - set
Visibility Box - update
Particle - update
Particle Vertex
Constructors
constructor
Creates a SPS (Solid Particle System) object.
Parameters
name: string
(String) is the SPS name, this will be the underlying mesh name.
scene: Scene
(Scene) is the scene in which the SPS is added.
Optional options: { autoFixFaceOrientation?: boolean; bSphereRadiusFactor?: number; boundingSphereOnly?: boolean; computeBoundingBox?: boolean; enableDepthSort?: boolean; enableMultiMaterial?: boolean; expandable?: boolean; isPickable?: boolean; particleIntersection?: boolean; updatable?: boolean; useModelMaterial?: boolean }
defines the options of the sps e.g.
- updatable (optional boolean, default true) : if the SPS must be updatable or immutable.
- isPickable (optional boolean, default false) : if the solid particles must be pickable.
- enableDepthSort (optional boolean, default false) : if the solid particles must be sorted in the geometry according to their distance to the camera.
- useModelMaterial (optional boolean, default false) : if the model materials must be used to create the SPS multimaterial. This enables the multimaterial supports of the SPS.
- enableMultiMaterial (optional boolean, default false) : if the solid particles can be given different materials.
- expandable (optional boolean, default false) : if particles can still be added after the initial SPS mesh creation.
- particleIntersection (optional boolean, default false) : if the solid particle intersections must be computed.
- boundingSphereOnly (optional boolean, default false) : if the particle intersection must be computed only with the bounding sphere (no bounding box computation, so faster).
- bSphereRadiusFactor (optional float, default 1.0) : a number to multiply the bounding sphere radius by in order to reduce it for instance.
- computeBoundingBox (optional boolean, default false): if the bounding box of the entire SPS will be computed (for occlusion detection, for example). If it is false, the bounding box will be the bounding box of the first particle.
- autoFixFaceOrientation (optional boolean, default false): if the particle face orientations will be flipped for transformations that change orientation (scale (-1, 1, 1), for example)
Optional auto
Fix Face Orientation?: boolean Optional b
Sphere Radius Factor?: number Optional bounding
Sphere Only?: boolean Optional compute
Bounding Box?: boolean Optional enable
Depth Sort?: boolean Optional enable
Multi Material?: boolean Optional expandable?: boolean
Optional is
Pickable?: boolean Optional particle
Intersection?: boolean Optional updatable?: boolean
Optional use
Model Material?: boolean
Returns SolidParticleSystem
Properties
billboardSearch playground for billboard
If the particles must ever face the camera (default false). Useful for planar particles.
counterSearch playground for counter
This a counter ofr your own usage. It's not set by any SPS functions.
depth Sorted ParticlesSearch playground for depthSortedParticles
This array is populated when enableDepthSort
is set to true.
Each element of this array is an instance of the class DepthSortedParticle.
meshSearch playground for mesh
The SPS mesh. It's a standard BJS Mesh, so all the methods from the Mesh class are available.
nameSearch playground for name
The SPS name. This name is also given to the underlying mesh.
nb ParticlesSearch playground for nbParticles
The SPS total number of particles. Read only. Use SPS.counter instead if you need to set your own value.
particlesSearch playground for particles
The SPS array of Solid Particle objects. Just access each particle as with any classic array. Example : var p = SPS.particles[i];
picked By Sub MeshSearch playground for pickedBySubMesh
This array is populated when the SPS is set as 'pickable'
Each key of this array is a submesh index.
Each element of this array is a second array defined like this :
Each key of this second array is a faceId
value that you can get from a pickResult object.
Each element of this second array is an object {idx: int, faceId: int}
.
idx
is the picked particle index in the SPS.particles
array
faceId
is the picked face index counted within this particle.
It's better to use the method SPS.pickedParticle(pickingInfo) rather than using directly this array.
Please read : https://doc.babylonjs.com/features/featuresDeepDive/particles/solid_particle_system/picking_sps
picked ParticlesSearch playground for pickedParticles
This array is populated when the SPS is set as 'pickable'.
Each key of this array is a faceId
value that you can get from a pickResult object.
Each element of this array is an object {idx: int, faceId: int}
.
idx
is the picked particle index in the SPS.particles
array
faceId
is the picked face index counted within this particle.
This array is the first element of the pickedBySubMesh array : sps.pickBySubMesh[0].
It's not pertinent to use it when using a SPS with the support for MultiMaterial enabled.
Use the method SPS.pickedParticle(pickingInfo) instead.
Please read : https://doc.babylonjs.com/features/featuresDeepDive/particles/solid_particle_system/picking_sps
recompute NormalsSearch playground for recomputeNormals
Recompute normals when adding a shape
varsSearch playground for vars
This empty object is intended to store some SPS specific or temporary values in order to lower the Garbage Collector activity. Please read : https://doc.babylonjs.com/features/featuresDeepDive/particles/solid_particle_system/optimize_sps#limit-garbage-collection
Accessors
auto Update Sub Meshes
If the subMeshes must be updated on the next call to setParticles()
Returns boolean
If the subMeshes must be updated on the next call to setParticles()
Parameters
val: boolean
Returns void
compute Bounding Box
Gets if
setParticles()
computes or not the mesh bounding box when computing the particle positions.Returns boolean
Tells to
setParticles()
to compute or not the mesh bounding box when computing the particle positions.Parameters
val: boolean
Returns void
compute Particle Color
Gets if
setParticles()
computes the particle colors or not. Default value : true. The SPS is faster when it's set to false. Note : the particle colors are stored values, so settingcomputeParticleColor
to false will keep yet the last colors set.Returns boolean
Tells to
setParticles()
to compute the particle colors or not. Default value : true. The SPS is faster when it's set to false. Note : the particle colors are stored values, so settingcomputeParticleColor
to false will keep yet the last colors set.Parameters
val: boolean
Returns void
compute Particle Rotation
Gets if
setParticles()
computes the particle rotations or not. Default value : true. The SPS is faster when it's set to false. Note : the particle rotations aren't stored values, so settingcomputeParticleRotation
to false will prevents the particle to rotate.Returns boolean
Tells to
setParticles()
to compute the particle rotations or not. Default value : true. The SPS is faster when it's set to false. Note : the particle rotations aren't stored values, so settingcomputeParticleRotation
to false will prevents the particle to rotate.Parameters
val: boolean
Returns void
compute Particle Texture
Gets if
setParticles()
computes the particle textures or not. Default value : true. The SPS is faster when it's set to false. Note : the particle textures are stored values, so settingcomputeParticleTexture
to false will keep yet the last colors set.Returns boolean
Parameters
val: boolean
Returns void
compute Particle Vertex
Gets if
setParticles()
calls the vertex function for each vertex of each particle, or not. Default value : false. The SPS is faster when it's set to false. Note : the particle custom vertex positions aren't stored values.Returns boolean
Tells to
setParticles()
to call the vertex function for each vertex of each particle, or not. Default value : false. The SPS is faster when it's set to false. Note : the particle custom vertex positions aren't stored values.Parameters
val: boolean
Returns void
depth Sort Particles
Gets if
setParticles()
sorts or not the distance between each particle and the camera. Skipped whenenableDepthSort
is set tofalse
(default) at construction time. Default :true
Returns boolean
Tells to
setParticles()
to sort or not the distance between each particle and the camera. Skipped whenenableDepthSort
is set tofalse
(default) at construction time. Default :true
Parameters
val: boolean
Returns void
expandable
Gets if the SPS is created as expandable at construction time. Default :
false
Returns boolean
is Always Visible
Gets whether the SPS as always visible or not doc : https://doc.babylonjs.com/features/featuresDeepDive/particles/solid_particle_system/sps_visibility
Returns boolean
Sets the SPS as always visible or not doc : https://doc.babylonjs.com/features/featuresDeepDive/particles/solid_particle_system/sps_visibility
Parameters
val: boolean
Returns void
is Visibility Box Locked
Gets if the SPS visibility box as locked or not. This enables/disables the underlying mesh bounding box updates. doc : https://doc.babylonjs.com/features/featuresDeepDive/particles/solid_particle_system/sps_visibility
Returns boolean
Sets the SPS visibility box as locked or not. This enables/disables the underlying mesh bounding box updates. doc : https://doc.babylonjs.com/features/featuresDeepDive/particles/solid_particle_system/sps_visibility
Parameters
val: boolean
Returns void
materials
The SPS used material array.
Returns Material[]
multimaterial
The SPS computed multimaterial object
Returns MultiMaterial
The SPS computed multimaterial object
Parameters
mm: MultiMaterial
Returns void
multimaterial Enabled
Gets if the SPS supports the Multi Materials
Returns boolean
use Model Material
Gets if the SPS uses the model materials for its own multimaterial.
Returns boolean
Methods
add ShapeSearch playground for addShape
Adds some particles to the SPS from the model shape. Returns the shape id. Please read the doc : https://doc.babylonjs.com/features/featuresDeepDive/particles/solid_particle_system/immutable_sps
Parameters
mesh: Mesh
is any Mesh object that will be used as a model for the solid particles.
nb: number
(positive integer) the number of particles to be created from this model
Optional options: { positionFunction?: any; storage?: []; vertexFunction?: any }
is an optional javascript function to called for each particle on SPS creation. {vertexFunction} is an optional javascript function to called for each vertex of each particle on SPS creation {storage} (optional existing array) is an array where the particles will be stored for a further use instead of being inserted in the SPS.
Optional position
Function?: any Optional storage?: []
Optional vertex
Function?: any
Returns number
the number of shapes in the system
after Update ParticlesSearch playground for afterUpdateParticles
This will be called by
setParticles()
after all the other treatments and just before the actual mesh update. This will be passed three parameters. This does nothing and may be overwritten by the user.Parameters
Optional start: number
the particle index in the particle array where to stop to iterate, same than the value passed to setParticle()
Optional stop: number
the particle index in the particle array where to stop to iterate, same than the value passed to setParticle()
Optional update: boolean
the boolean update value actually passed to setParticles()
Returns void
before Update ParticlesSearch playground for beforeUpdateParticles
This will be called before any other treatment by
setParticles()
and will be passed three parameters. This does nothing and may be overwritten by the user.Parameters
Optional start: number
the particle index in the particle array where to stop to iterate, same than the value passed to setParticle()
Optional stop: number
the particle index in the particle array where to stop to iterate, same than the value passed to setParticle()
Optional update: boolean
the boolean update value actually passed to setParticles()
Returns void
build MeshSearch playground for buildMesh
Builds the SPS underlying mesh. Returns a standard Mesh. If no model shape was added to the SPS, the returned mesh is just a single triangular plane.
Returns Mesh
the created mesh
compute Sub MeshesSearch playground for computeSubMeshes
Computes the required SubMeshes according the materials assigned to the particles.
Returns SolidParticleSystem
the solid particle system. Does nothing if called before the SPS mesh is built.
digestSearch playground for digest
Digests the mesh and generates as many solid particles in the system as wanted. Returns the SPS. These particles will have the same geometry than the mesh parts and will be positioned at the same localisation than the mesh original places. Thus the particles generated from
digest()
have their propertyposition
set yet.Parameters
mesh: Mesh
( Mesh ) is the mesh to be digested
Optional options: { delta?: number; facetNb?: number; number?: number; storage?: [] }
(optional integer, default 1) is the number of mesh facets per particle, this parameter is overridden by the parameter
number
if any {delta} (optional integer, default 0) is the random extra number of facets per particle , each particle will have betweenfacetNb
andfacetNb + delta
facets {number} (optional positive integer) is the wanted number of particles : each particle is built withmesh_total_facets / number
facets {storage} (optional existing array) is an array where the particles will be stored for a further use instead of being inserted in the SPS.Optional delta?: number
Optional facet
Nb?: number Optional number?: number
Optional storage?: []
Returns SolidParticleSystem
the current SPS
disposeSearch playground for dispose
Disposes the SPS.
Returns void
get Particle By IdSearch playground for getParticleById
Returns a SolidParticle object from its identifier : particle.id
Parameters
id: number
(integer) the particle Id
Returns Nullable<SolidParticle>
the searched particle or null if not found in the SPS.
get Particles By Shape IdSearch playground for getParticlesByShapeId
Returns a new array populated with the particles having the passed shapeId.
Parameters
shapeId: number
(integer) the shape identifier
Returns SolidParticle[]
a new solid particle array
get Particles By Shape Id To RefSearch playground for getParticlesByShapeIdToRef
Populates the passed array "ref" with the particles having the passed shapeId.
Parameters
shapeId: number
the shape identifier
ref: SolidParticle[]
Returns SolidParticleSystem
the SPS
init ParticlesSearch playground for initParticles
This function does nothing. It may be overwritten to set all the particle first values. The SPS doesn't call this function, you may have to call it by your own. doc : https://doc.babylonjs.com/features/featuresDeepDive/particles/solid_particle_system/manage_sps_particles
Returns void
insert Particles From ArraySearch playground for insertParticlesFromArray
Inserts some pre-created particles in the solid particle system so that they can be managed by setParticles().
Parameters
solidParticleArray: SolidParticle[]
an array populated with Solid Particles objects
Returns SolidParticleSystem
the SPS
picked ParticleSearch playground for pickedParticle
Returns an object {idx: number faceId: number} for the picked particle from the passed pickingInfo object. idx is the particle index in the SPS faceId is the picked face index counted within this particle. Returns null if the pickInfo can't identify a picked particle.
Parameters
pickingInfo: PickingInfo
(PickingInfo object)
Returns Nullable<{ faceId: number; idx: number }>
or null
rebuild MeshSearch playground for rebuildMesh
Rebuilds the whole mesh and updates the VBO : custom positions and vertices are recomputed if needed.
Parameters
Optional reset: boolean
boolean, default false : if the particles must be reset at position and rotation zero, scaling 1, color white, initial UVs and not parented.
Returns SolidParticleSystem
the SPS.
recycle ParticleSearch playground for recycleParticle
This function does nothing. It may be overwritten to recycle a particle. The SPS doesn't call this function, you may have to call it by your own. doc : https://doc.babylonjs.com/features/featuresDeepDive/particles/solid_particle_system/manage_sps_particles
Parameters
particle: SolidParticle
The particle to recycle
Returns SolidParticle
the recycled particle
refresh Visible SizeSearch playground for refreshVisibleSize
Visibility helper : Recomputes the visible size according to the mesh bounding box doc : https://doc.babylonjs.com/features/featuresDeepDive/particles/solid_particle_system/sps_visibility
Returns SolidParticleSystem
the SPS.
remove ParticlesSearch playground for removeParticles
Removes the particles from the start-th to the end-th included from an expandable SPS (required). Returns an array with the removed particles. If the number of particles to remove is lower than zero or greater than the global remaining particle number, then an empty array is returned. The SPS can't be empty so at least one particle needs to remain in place. Under the hood, the VertexData array, so the VBO buffer, is recreated each call.
Parameters
start: number
index of the first particle to remove
end: number
index of the last particle to remove (included)
Returns SolidParticle[]
an array populated with the removed particles
set Multi MaterialSearch playground for setMultiMaterial
Sets the SPS MultiMaterial from the passed materials. Note : the passed array is internally copied and not used then by reference.
Parameters
materials: Material[]
an array of material objects. This array indexes are the materialIndex values of the particles.
Returns void
set ParticlesSearch playground for setParticles
Sets all the particles : this method actually really updates the mesh according to the particle positions, rotations, colors, textures, etc. This method calls
updateParticle()
for each particle of the SPS. For an animated SPS, it is usually called within the render loop. This methods does nothing if called on a non updatable or not yet built SPS. Example : buildMesh() not called after having added or removed particles from an expandable SPS.Parameters
Optional start: number
The particle index in the particle array where to start to compute the particle property values (default 0)
Optional end: number
The particle index in the particle array where to stop to compute the particle property values (default nbParticle - 1)
Optional update: boolean
If the mesh must be finally updated on this call after all the particle computations (default true)
Returns SolidParticleSystem
the SPS.
set Visibility BoxSearch playground for setVisibilityBox
Visibility helper : Sets the size of a visibility box, this sets the underlying mesh bounding box.
Parameters
size: number
the size (float) of the visibility box note : this doesn't lock the SPS mesh bounding box. doc : https://doc.babylonjs.com/features/featuresDeepDive/particles/solid_particle_system/sps_visibility
Returns void
update ParticleSearch playground for updateParticle
Updates a particle : this function should be overwritten by the user. It is called on each particle by
setParticles()
. This is the place to code each particle behavior. doc : https://doc.babylonjs.com/features/featuresDeepDive/particles/solid_particle_system/manage_sps_particlesParameters
particle: SolidParticle
The particle to update
Returns SolidParticle
the updated particle
update Particle VertexSearch playground for updateParticleVertex
Updates a vertex of a particle : it can be overwritten by the user. This will be called on each vertex particle by
setParticles()
ifcomputeParticleVertex
is set to true only.Parameters
particle: SolidParticle
the current particle
vertex: SolidParticleVertex
the current vertex of the current particle : a SolidParticleVertex object
pt: number
the index of the current vertex in the particle shape doc : https://doc.babylonjs.com/features/featuresDeepDive/particles/solid_particle_system/sps_vertices
Returns SolidParticleSystem
the sps
The SPS is a single updatable mesh. The solid particles are simply separate parts or faces of this big mesh. As it is just a mesh, the SPS has all the same properties than any other BJS mesh : not more, not less. It can be scaled, rotated, translated, enlighted, textured, moved, etc. The SPS is also a particle system. It provides some methods to manage the particles. However it is behavior agnostic. This means it has no emitter, no particle physics, no particle recycler. You have to implement your own behavior.
Full documentation here : https://doc.babylonjs.com/features/featuresDeepDive/particles/solid_particle_system/sps_intro