Class ParticleSystem

The ParticleSystem component efficiently handles the motion and rendering of many individual particles.

You can add custom behaviours to the particle system to fully customize the behaviour of the particles. See ParticleSystemBaseBehaviour and ParticleSystem.addBehaviour for more information.

Needle Engine uses three.quarks under the hood to handle particles.

Hierarchy (View Summary)

Implements

  • IParticleSystem

Properties

gameObject guid sourceId?

Accessors

activeAndEnabled behaviours cameraScale container context currentParticles deltaTime destroyed duration enabled forward isPlaying isSubsystem layer localspace matrixWorld maxParticles name particleSystem playOnAwake renderer right scale scene static tag time up worldEuler worldPos worldPosition worldQuaternion worldQuaternionInverted worldRotation worldScale worldspace

Methods

addBehaviour addEventListener destroy dispatchEvent earlyUpdate? emit lateUpdate? onAfterRender? onBeforeXR? onCollisionEnter? onCollisionExit? onCollisionStay? onDisable onEnterXR? onLeaveXR? onPausedChanged? onPointerClick? onPointerDown? onPointerEnter? onPointerExit? onPointerMove? onPointerUp? onTriggerEnter? onTriggerExit? onTriggerStay? onUpdateXR? onValidate? onXRControllerAdded? onXRControllerRemoved? pause play removeAllBehaviours removeBehaviour removeEventListener reset resolveGuids? setWorldPosition setWorldQuaternion setWorldRotation startCoroutine stop stopCoroutine supportsXR? update?

Properties

gameObject

gameObject: GameObject

the object this component is attached to. Note that this is a threejs Object3D with some additional features

guid

guid: string = "invalid"

the unique identifier for this component

OptionalsourceId

sourceId?: string

holds the source identifier this object was created with/from (e.g. if it was part of a glTF file the sourceId holds the url to the glTF)

Accessors

activeAndEnabled

  • get activeAndEnabled(): boolean

    Returns boolean

    true if the object is enabled and active in the hierarchy

behaviours

  • get behaviours(): null | Behavior[]

    Get the underlying three.quarks particle system behaviours. This can be used to fully customize the behaviour of the particles.

    Returns null | Behavior[]

cameraScale

  • get cameraScale(): number

    Returns number

container

  • get container(): Object3D

    Returns Object3D

context

  • get context(): Context

    Use the context to get access to many Needle Engine features and use physics, timing, access the camera or scene

    Returns Context

  • set context(context: Context): void

    Parameters

    Returns void

currentParticles

  • get currentParticles(): number

    Returns number

deltaTime

  • get deltaTime(): number

    Returns number

destroyed

  • get destroyed(): boolean

    Returns boolean

    true if this component was destroyed (this.destroy()) or the whole object this component was part of

duration

  • get duration(): number

    Returns number

enabled

  • get enabled(): boolean

    Returns boolean

  • set enabled(val: boolean): void

    Parameters

    • val: boolean

    Returns void

forward

  • get forward(): Vector3

    Forward (0,0,-1) vector in world space

    Returns Vector3

isPlaying

  • get isPlaying(): boolean

    Returns boolean

isSubsystem

  • get isSubsystem(): boolean

    Returns boolean

layer

  • get layer(): number

    Returns number

    the layer of the gameObject this component is attached to

localspace

  • get localspace(): boolean

    Returns boolean

matrixWorld

  • get matrixWorld(): Matrix4

    Returns Matrix4

maxParticles

  • get maxParticles(): number

    Returns number

name

  • get name(): string

    Returns string

    the name of the gameObject this component is attached to

  • set name(str: string): void

    Parameters

    • str: string

    Returns void

particleSystem

playOnAwake

  • get playOnAwake(): boolean

    Returns boolean

  • set playOnAwake(val: boolean): void

    Parameters

    • val: boolean

    Returns void

renderer

  • get renderer(): ParticleSystemRenderer

    Returns ParticleSystemRenderer

right

  • get right(): Vector3

    Right (1,0,0) vector in world space

    Returns Vector3

scale

  • get scale(): number

    Returns number

scene

  • get scene(): Scene

    shorthand for this.context.scene

    Returns Scene

    the scene of the context

static

  • get static(): boolean

    Is the gameObject marked as static

    Returns boolean

  • set static(value: boolean): void

    Parameters

    • value: boolean

    Returns void

tag

  • get tag(): string

    Returns string

    the tag of the gameObject this component is attached to

  • set tag(str: string): void

    Parameters

    • str: string

    Returns void

time

  • get time(): number

    Returns number

up

  • get up(): Vector3

    Up (0,1,0) vector in world space

    Returns Vector3

worldEuler

  • get worldEuler(): Euler

    Returns Euler

  • set worldEuler(val: Euler): void

    Parameters

    Returns void

worldPos

  • get worldPos(): Vector3

    Returns Vector3

worldPosition

  • get worldPosition(): Vector3

    Returns Vector3

  • set worldPosition(val: Vector3): void

    Parameters

    Returns void

worldQuaternion

  • get worldQuaternion(): Quaternion

    Returns Quaternion

worldQuaternionInverted

  • get worldQuaternionInverted(): Quaternion

    Returns Quaternion

worldRotation

  • get worldRotation(): Vector3

    Returns Vector3

  • set worldRotation(val: Vector3): void

    Parameters

    Returns void

worldScale

  • get worldScale(): Vector3

    Returns Vector3

worldspace

  • get worldspace(): boolean

    Returns boolean

Methods

addBehaviour

  • addBehaviour(
        particleSystemBehaviour: Behavior | ParticleSystemBaseBehaviour,
    ): boolean

    Add a custom quarks behaviour to the particle system.
    You can add a quarks.Behaviour type or derive from ParticleSystemBaseBehaviour

    Parameters

    Returns boolean

    Link

    https://github.com/Alchemist0823/three.quarks

    Example

    class MyBehaviour extends ParticleSystemBaseBehaviour {
       initialize(particle: Particle) {
          // initialize the particle
      }
       update(particle: Particle, delta: number) {  
           // do something with the particle
      }
    }

    const system = gameObject.getComponent(ParticleSystem);
    system.addBehaviour(new MyBehaviour());

addEventListener

  • addEventListener<T extends Event>(type: string, listener: (evt: T) => any): void

    Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.

    The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture.

    When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.

    When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.

    When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed.

    If an AbortSignal is passed for options's signal, then the event listener will be removed when signal is aborted.

    The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.

    MDN Reference

    Type Parameters

    Parameters

    • type: string
    • listener: (evt: T) => any

    Returns void

destroy

  • destroy(): void

    Destroys this component (and removes it from the object)

    Returns void

dispatchEvent

  • dispatchEvent(evt: Event): boolean

    Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.

    MDN Reference

    Parameters

    Returns boolean

OptionalearlyUpdate

  • earlyUpdate(): void

    first callback in a frame (called every frame when implemented)

    Returns void

emit

  • emit(count: number): void

    Parameters

    • count: number

    Returns void

OptionallateUpdate

  • lateUpdate(): void

    late callback in a frame (called every frame when implemented)

    Returns void

OptionalonAfterRender

OptionalonBeforeXR

  • onBeforeXR(mode: XRSessionMode, args: XRSessionInit): void

    Called before the XR session is requested. Use this callback if you want to modify the session init features

    Parameters

    • mode: XRSessionMode
    • args: XRSessionInit

    Returns void

OptionalonCollisionEnter

OptionalonCollisionExit

OptionalonCollisionStay

onDisable

  • onDisable(): void

    called every time the component gets disabled or if a parent object (or this.gameObject) gets set to invisible

    Returns void

OptionalonEnterXR

OptionalonLeaveXR

OptionalonPausedChanged

  • onPausedChanged(isPaused: boolean, wasPaused: boolean): void

    Called for all scripts when the context gets paused or unpaused

    Parameters

    • isPaused: boolean
    • wasPaused: boolean

    Returns void

OptionalonPointerClick

OptionalonPointerDown

OptionalonPointerEnter

OptionalonPointerExit

OptionalonPointerMove

OptionalonPointerUp

OptionalonTriggerEnter

OptionalonTriggerExit

OptionalonTriggerStay

OptionalonUpdateXR

OptionalonValidate

  • onValidate(prop?: string): void

    called when you decorate fields with the @validate() decorator

    Parameters

    • Optionalprop: string

      the name of the field that was changed

    Returns void

OptionalonXRControllerAdded

  • onXRControllerAdded(args: NeedleXRControllerEventArgs): void

    Callback when a controller is connected/added while in a XR session
    OR when the component joins a running XR session that has already connected controllers
    OR when the component becomes active during a running XR session that has already connected controllers

    Parameters

    Returns void

OptionalonXRControllerRemoved

pause

  • pause(includeChildren?: boolean): void

    Parameters

    • includeChildren: boolean = true

    Returns void

play

  • play(includeChildren?: boolean): void

    Parameters

    • includeChildren: boolean = false

    Returns void

removeAllBehaviours

  • removeAllBehaviours(): boolean

    Removes all behaviours from the particle system
    Note: this will also remove the default behaviours like SizeBehaviour, ColorBehaviour etc.

    Returns boolean

removeBehaviour

removeEventListener

  • removeEventListener<T extends Event>(
        type: string,
        listener: (arg: T) => any,
    ): void

    Removes the event listener in target's event listener list with the same type, callback, and options.

    MDN Reference

    Type Parameters

    Parameters

    • type: string
    • listener: (arg: T) => any

    Returns void

reset

  • reset(): void

    remove emitted particles and reset time

    Returns void

OptionalresolveGuids

  • resolveGuids(guidsMap: GuidsMap): void

    called on a component with a map of old to new guids (e.g. when instantiate generated new guids and e.g. timeline track bindings needs to remape them)

    Parameters

    • guidsMap: GuidsMap

    Returns void

setWorldPosition

  • setWorldPosition(x: number, y: number, z: number): void

    Parameters

    • x: number
    • y: number
    • z: number

    Returns void

setWorldQuaternion

  • setWorldQuaternion(x: number, y: number, z: number, w: number): void

    Parameters

    • x: number
    • y: number
    • z: number
    • w: number

    Returns void

setWorldRotation

  • setWorldRotation(x: number, y: number, z: number, degrees?: boolean): void

    Parameters

    • x: number
    • y: number
    • z: number
    • degrees: boolean = true

    Returns void

startCoroutine

  • startCoroutine(routine: Generator, evt?: FrameEvent): Generator

    starts a coroutine (javascript generator function)
    yield will wait for the next frame:

    • Use yield WaitForSeconds(1) to wait for 1 second.
    • Use yield WaitForFrames(10) to wait for 10 frames.
    • Use yield new Promise(...) to wait for a promise to resolve.

    Parameters

    • routine: Generator

      generator function to start

    • evt: FrameEvent = FrameEvent.Update

      event to register the coroutine for (default: FrameEvent.Update). Note that all coroutine FrameEvent callbacks are invoked after the matching regular component callbacks. For example FrameEvent.Update will be called after regular component update() methods)

    Returns Generator

    the generator function (use it to stop the coroutine with stopCoroutine)

    Example

    onEnable() { this.startCoroutine(this.myCoroutine()); }
    private *myCoroutine() {
       while(this.activeAndEnabled) {
          console.log("Hello World", this.context.time.frame);
          // wait for 5 frames
          for(let i = 0; i < 5; i++) yield;
       }
    }

stop

  • stop(includeChildren?: boolean, clear?: boolean): void

    clear=true removes all emitted particles

    Parameters

    • includeChildren: boolean = true
    • clear: boolean = false

    Returns void

stopCoroutine

  • stopCoroutine(routine: Generator, evt?: FrameEvent): void

    Stop a coroutine that was previously started with startCoroutine

    Parameters

    • routine: Generator

      the routine to be stopped

    • evt: FrameEvent = FrameEvent.Update

      the frame event to unregister the routine from (default: FrameEvent.Update)

    Returns void

OptionalsupportsXR

  • supportsXR(mode: XRSessionMode): boolean

    Optional callback, you can implement this to only get callbacks for VR or AR sessions if necessary.

    Parameters

    • mode: XRSessionMode

    Returns boolean

    true if the mode is supported (if false the mode is not supported by this component and it will not receive XR callbacks for this mode)

Optionalupdate

  • update(): void

    regular callback in a frame (called every frame when implemented)

    Returns void

Settings

Member Visibility

On This Page

Properties
Accessors
Methods