Sparkles

<Sparkles /> makes sparkles on your geometry's vertices – optionally guided by a directional light.

Usage

Basic

<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Sparkles, OrbitControls, TorusKnot } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas clear-color="#333">
    <TresPerspectiveCamera :position="[0, 0, 5]" />
    <TorusKnot :args="[1, 0.25, 128, 16]">
      <TresMeshBasicMaterial color="#222" />
      <Sparkles />
    </TorusKnot>
    <OrbitControls />
  </TresCanvas>
</template>

With TresDirectionalLight

By default, sparkles appear on the up-facing vertices. However, you can pass a directional light to the component. Moving the directional light will cause "lit" vertices to emit sparkles.

<script setup lang="ts">
import { TresCanvas, useRenderLoop } from '@tresjs/core'
import { Sparkles, OrbitControls, Torus, Sphere } from '@tresjs/cientos'
import { shallowRef } from 'vue'

const lightRef = shallowRef()

useRenderLoop().onLoop(({ elapsed }) => {
  if (lightRef.value) {
    lightRef.value.position.x = Math.cos(elapsed) * 2.5
    lightRef.value.position.y = Math.sin(elapsed) * 2.5
  }
})
</script>

<template>
  <TresCanvas clear-color="#333">
    <TresPerspectiveCamera :position="[0, 0, 8]" />
    <TresDirectionalLight ref="lightRef">
      <Sphere
        color="white"
        :scale="0.1"
      />
    </TresDirectionalLight>
    <Torus :args="[1, 0.25, 16, 48]">
      <TresMeshBasicMaterial color="#222" />
      <Sparkles :directional-light="lightRef" />
    </Torus>
    <OrbitControls />
  </TresCanvas>
</template>

Sequences

All props beginning with :sequence- are used to define how a particle changes as it progresses (See also: Mixes). :sequence- props are of the type Gradient<T>, which can be any one of:

• T: a single value
• [T, T, T, ...]: an evenly distributed series of values
• [[number, T], [number, T], ...]: an unevently distributed series of values, where number is a gradient "stop" from 0 to 1.

For example, all of these are acceptable values for Gradient<TresColor>:

• 'red'
• ['red', 'blue', 'green']
• [[0.1, 'red'], [0.25, 'blue'], [0.5, 'green']]

<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Sparkles, OrbitControls, Sphere } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas clear-color="#333">
    <TresPerspectiveCamera :position="[0, 0, 8]" />
    <Sphere>
      <TresMeshBasicMaterial color="#222" />
      <Sparkles 
        :sequence-alpha="[[0., 0.], [0.6, 1.0], [0.7, 0.0], [1.0, 1.0]]"
        :sequence-color="['yellow', 'white', 'orange', 'red', 'black']" 
        :sequence-offset="[[0.7, [0, 0, 0]], [0.75, [0, 0.1, 0]], [1.0, [0, 0.5, 0]]]" 
        :sequence-size="[[0.0, 0.0], [0.7, 1.0]]" 
        :sequence-surface-distance="[[0.0, 0.0], [0.7, 1.0]]" 
        :lifetime-sec="2.0"
        :size="2"
        :surface-distance="0.8"
        :mix-color="1.0"
      />
    </Sphere>
    <OrbitControls />
  </TresCanvas>
</template>

Mixes

All props beginning with :mix- allow you to specify how a particle "progresses" through a corresponding :sequence- prop. E.g., :mix-alpha affects :sequence-alpha.

• If the :mix- prop is 0.0, 'progress' through the :sequence- is determined entirely by the light shining on the surface of the sparkling mesh.¹
• If the :mix- prop is 1.0, 'progress' through the :sequence- is determined entirely by the particle's lifetime.

1) More precisely, the value is determined by the dot product of the directionalLight's inverted normalized position and each of the sparkling mesh's vertex normals.

<script setup lang="ts">
import { TresCanvas, useRenderLoop } from '@tresjs/core'
import { Sparkles, Sphere } from '@tresjs/cientos'
import { shallowRef } from 'vue'
import { useControls, TresLeches } from '@tresjs/leches'
import '@tresjs/leches/styles'

const lightRef = shallowRef()
const { value: mix } = useControls({
  mix: { value: 0, min: 0, max: 1, step: 0.01 },
})

useRenderLoop().onLoop(({ elapsed }) => {
  if (lightRef.value) {
    lightRef.value.position.x = Math.cos(elapsed) * 3
    lightRef.value.position.y = Math.sin(elapsed) * 3
  }
})
</script>

<template>
  <TresLeches class="top-0 important-left-4" />
  <TresCanvas clear-color="#333">
    <TresPerspectiveCamera :position="[-2.5, 0, 8]" />
    <TresDirectionalLight ref="lightRef">
      <Sphere
        color="white"
        :scale="0.1"
      />
    </TresDirectionalLight>
    <Sphere :args="[1, 16, 16]">
      <TresMeshBasicMaterial color="#222" />
      <Sparkles
        :directional-light="lightRef"
        :mix-alpha="mix"
        :mix-color="mix"
        :mix-offset="mix"
        :mix-size="mix"
        :mix-surface-distance="mix"
        :lifetime-sec="2"
        :sequence-alpha="[0.1, 1.0]"
        :sequence-surface-distance="[0.1, 0.5]"
      />
    </Sphere>
  </TresCanvas>
</template>

Props

Name	Description
map	Type: Texture | string Default: 'https://raw.githubusercontent.com/Tresjs/asset... Texture or image path for individual sparkles
geometry	Type: Object3D | BufferGeometry Default: undefined Vertices of the geometry will be used to emit sparkles. Geometry normals are used for sparkles' traveling direction and for responding to the directional light prop. If provided, the component will use the passed geometry. If no geometry is provided, the component will try to make a copy of the parent object's geometry. If no parent geometry exists, the component will create and use an IcosphereGeometry.
directionalLight	Type: Object3D Default: undefined Particles "light up" when their normal "faces" the light. If no directionalLight is provided, the default "up" vector will be used.
lifetimeSec	Type: number Default: 0.4 Particle lifetime in seconds
cooldownSec	Type: number Default: 2.0 Particle cooldown in seconds – time between lifetime end and respawn
normalThreshold	Type: number Default: 0.7 Number from 0-1 indicating how closely the particle needs to be faced towards the light to "light up". (Lower == more flexible)
noiseScale	Type: number Default: 3.0 Scale of the noise period (lower == more slowly cycling noise)
scaleNoise	Type: number Default: 1.0 Noise coefficient applied to particle scale
offsetNoise	Type: number Default: 0.1 Noise coefficient applied to particle offset
lifetimeNoise	Type: number Default: 0.0 Noise coefficient applied to particle lifetime
size	Type: number Default: 1.0 Particle scale multiplier
alpha	Type: number Default: 1.0 Opacity multiplier
offset	Type: number Default: 1.0 Offset multiplier
surfaceDistance	Type: number Default: 1.0 Surface distance multiplier
sequenceColor	Type: Gradient<TresColor> Default: [[0.7, '#82dbc5'], [0.8, '#fbb03b']] 'Sequence' props: specify how a particle changes as it "progresses". See also "mix" props. Color sequence as particles progress
sequenceAlpha	Type: Gradient<number> Default: [[0.0, 0.0], [0.10, 1.0], [0.5, 1.0], [0.9, 0.0]] Opacity sequence as particles progress
sequenceOffset	Type: Gradient<[number, number, number]> Default: [0.0, 0.0, 0.0] Distance sequence as particles progress
sequenceNoise	Type: Gradient<[number, number, number]> Default: [0.1, 0.1, 0.1] Noise sequence as particles progress
sequenceSize	Type: Gradient<number> Default: [0.0, 1.0] Size sequence as particles progress
sequenceSurfaceDistance	Type: Gradient<number> Default: [0.05, 0.08, 0.1] Distance from surface (along normal) as particles progress
mixColor	Type: number Default: 0.5 'mix*' props: A particle "progresses" with a mix of two factors: its normal "facing" the directionalLight its lifetime 'mix*' props specify the relationship between the two factors. How is a particle's progress for color calculated? (0: normal, 1: particle lifetime)
mixAlpha	Type: number Default: 1. How is a particle's progress for alpha calculated? (0: normal, 1: particle lifetime)
mixOffset	Type: number Default: 1. How is a particle's progress for offset calculated? (0: normal, 1: particle lifetime)
mixSize	Type: number Default: 0. How is a particle's progress for size calculated? (0: normal, 1: particle lifetime)
mixSurfaceDistance	Type: number Default: 1. How is a particle's progress for surface distance calculated? (0: normal, 1: particle lifetime)
mixNoise	Type: number Default: 1. How is a particle's progress for lifetime calculated? (0: normal, 1: particle lifetime)
blending	Type: Blending Default: AdditiveBlending Material blending
transparent	Type: boolean Default: true Material transparency
depthWrite	Type: boolean Default: false Material depth write

5-39