Sparkles

Makes sparkles on geometry vertices, optionally guided by directional light.

<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 } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 3, 5]" />
    <TresMesh>
      <TresSphereGeometry />
      <Sparkles />
    </TresMesh>
    <TresAmbientLight />
  </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 } from '@tresjs/core'
import { Sparkles } from '@tresjs/cientos'
import { shallowRef } from 'vue'

const directionalLightRef = shallowRef()
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 3, 5]" />
    <TresMesh>
      <TresSphereGeometry />
      <Sparkles :directional-light="directionalLightRef" />
    </TresMesh>
    <TresDirectionalLight
      ref="directionalLightRef"
      :position="[3, 3, 3]"
      :intensity="2"
    />
    <TresAmbientLight />
  </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 } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 3, 5]" />
    <TresMesh>
      <TresSphereGeometry />
      <Sparkles
        :sequence-color="['red', 'blue', 'green']"
        :sequence-alpha="[[0.0, 0.0], [0.10, 1.0], [0.5, 1.0], [0.9, 0.0]]"
        :sequence-size="[0.0, 1.0, 0.5]"
      />
    </TresMesh>
    <TresAmbientLight />
  </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.

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 } from '@tresjs/core'
import { Sparkles } from '@tresjs/cientos'
import { shallowRef } from 'vue'

const directionalLightRef = shallowRef()
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 3, 5]" />
    <TresMesh>
      <TresSphereGeometry />
      <Sparkles
        :directional-light="directionalLightRef"
        :mix-color="0.8"
        :mix-alpha="0.5"
        :mix-size="0.2"
      />
    </TresMesh>
    <TresDirectionalLight
      ref="directionalLightRef"
      :position="[3, 3, 3]"
    />
    <TresAmbientLight />
  </TresCanvas>
</template>

WebGPU

Import Sparkles from @tresjs/cientos/webgpu on a TresCanvas from @tresjs/core/webgpu. That version has the same props. See WebGPU.

import { Sparkles } from '@tresjs/cientos/webgpu'

WebGPU draws point primitives at 1 pixel. Thus the WebGPU version draws each sparkle as one instance of a Sprite quad with a PointsNodeMaterial, and the instance it exposes is a Sprite, not Points. Raycasts and pointer events do not hit the sparkles in this version.

The glow of each sparkle is wider and softer than under WebGLRenderer. The WebGL version blends in sRGB, and WebGPURenderer blends in linear and converts the sum. Thus the faint edge of the texture shows more. The positions, sizes and colors are the same.

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

Smoke

Beautiful smoke, cloud, and fog effect using textures and transparency.

Stage

Creates a complete stage setup with lighting, shadows, and environment.