API
API|
@babylonjs/core|
SolidParticleSystem

Class SolidParticleSystem

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

Implements

Index
constructor
billboard counter depthSortedParticles mesh name nbParticles particles pickedBySubMesh pickedParticles recomputeNormals updateSpeed vars
autoUpdateSubMeshes computeBoundingBox computeParticleColor computeParticleRotation computeParticleTexture computeParticleVertex depthSortParticles expandable isAlwaysVisible isVisibilityBoxLocked materials multimaterial multimaterialEnabled started stopped useModelMaterial
addShape afterUpdateParticles beforeUpdateParticles buildMesh computeSubMeshes digest dispose getParticleById getParticlesByShapeId getParticlesByShapeIdToRef initParticles insertParticlesFromArray pickedParticle rebuildMesh recycleParticle refreshVisibleSize removeParticles setMultiMaterial setParticles setVisibilityBox start stop updateParticle updateParticleVertex

  • 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.

    • Optionaloptions: {
          autoFixFaceOrientation?: boolean;
          boundingSphereOnly?: boolean;
          bSphereRadiusFactor?: number;
          camera?: TargetCamera;
          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)
      • camera (optional Camera) : the camera to use with the particule system. If not provided, use the scene active camera.

    Returns SolidParticleSystem

    bSphereRadiusFactor = 1.0 / Math.sqrt(3.0) => the bounding sphere exactly matches a spherical mesh.
billboard: boolean = false

If the particles must ever face the camera (default false). Useful for planar particles.

counter: number = 0

This a counter ofr your own usage. It's not set by any SPS functions.

depthSortedParticles: DepthSortedParticle[]

This array is populated when enableDepthSort is set to true. Each element of this array is an instance of the class DepthSortedParticle.

mesh: Mesh

The SPS mesh. It's a standard BJS Mesh, so all the methods from the Mesh class are available.

name: string

The SPS name. This name is also given to the underlying mesh.

nbParticles: number = 0

The SPS total number of particles. Read only. Use SPS.counter instead if you need to set your own value.

particles: SolidParticle[] = ...

The SPS array of Solid Particle objects. Just access each particle as with any classic array. Example : var p = SPS.particles[i];

pickedBySubMesh: { faceId: number; idx: number }[][]

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

pickedParticles: { faceId: number; idx: number }[]

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

recomputeNormals: boolean = false

Recompute normals when adding a shape

updateSpeed: number = 0.01

The overall motion speed (0.01 is default update speed, faster updates = faster animation)

vars: any = {}

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

  • get computeParticleColor(): boolean

    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 setting computeParticleColor to false will keep yet the last colors set.

    Returns boolean

  • set computeParticleColor(val: boolean): void

    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 setting computeParticleColor to false will keep yet the last colors set.

    Parameters

    • val: boolean

    Returns void

  • get computeParticleRotation(): boolean

    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 setting computeParticleRotation to false will prevents the particle to rotate.

    Returns boolean

  • set computeParticleRotation(val: boolean): void

    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 setting computeParticleRotation to false will prevents the particle to rotate.

    Parameters

    • val: boolean

    Returns void

  • get computeParticleVertex(): boolean

    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

  • set computeParticleVertex(val: boolean): void

    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

  • get depthSortParticles(): boolean

    Gets if setParticles() sorts or not the distance between each particle and the camera. Skipped when enableDepthSort is set to false (default) at construction time. Default : true

    Returns boolean

  • set depthSortParticles(val: boolean): void

    Tells to setParticles() to sort or not the distance between each particle and the camera. Skipped when enableDepthSort is set to false (default) at construction time. Default : true

    Parameters

    • val: boolean

    Returns void

  • 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: AbstractMesh

      is any Mesh object that will be used as a model for the solid particles. If the mesh does not have vertex normals, it will turn on the recomputeNormals attribute.

    • nb: number

      (positive integer) the number of particles to be created from this model

    • Optionaloptions: { positionFunction?: any; storage?: []; vertexFunction?: any }

      {positionFunction} 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.

    Returns number

    the number of shapes in the system

  • 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

    • Optionalstart: number

      the particle index in the particle array where to stop to iterate, same than the value passed to setParticle()

    • Optionalstop: number

      the particle index in the particle array where to stop to iterate, same than the value passed to setParticle()

    • Optionalupdate: boolean

      the boolean update value actually passed to setParticles()

    Returns void

  • 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

    • Optionalstart: number

      the particle index in the particle array where to stop to iterate, same than the value passed to setParticle()

    • Optionalstop: number

      the particle index in the particle array where to stop to iterate, same than the value passed to setParticle()

    • Optionalupdate: boolean

      the boolean update value actually passed to setParticles()

    Returns void

  • 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 property position set yet.

    Parameters

    • mesh: Mesh

      ( Mesh ) is the mesh to be digested

    • Optionaloptions: {
          delta?: number;
          facetNb?: number;
          number?: number;
          storage?: [];
          uvKind?: number;
      }

      {facetNb} (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 between facetNb and facetNb + delta facets {number} (optional positive integer) is the wanted number of particles : each particle is built with mesh_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. {uvKind} (optional positive integer, default 0) is the kind of UV to read from. Use -1 to deduce it from the diffuse/albedo texture (if any) of the mesh material

    Returns SolidParticleSystem

    the current SPS

  • 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

    Returns Nullable<{ faceId: number; idx: number }>

    or null

  • 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

  • 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

  • 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

    • start: number = 0

      The particle index in the particle array where to start to compute the particle property values (default 0)

    • end: number = ...

      The particle index in the particle array where to stop to compute the particle property values (default nbParticle - 1)

    • update: boolean = true

      If the mesh must be finally updated on this call after all the particle computations (default true)

    Returns SolidParticleSystem

    the SPS.

  • Starts the particle system and begins to emit. This will call buildMesh(), initParticles(), setParticles() and register the update loop.

    Parameters

    • delay: number = 0

      defines the delay in milliseconds before starting the system (0 by default)

    Returns void