Three Vue3Three Vue3
Guide
Demo
AI Agents
  • English
  • 简体中文
GitHub
Guide
Demo
AI Agents
  • English
  • 简体中文
GitHub
    • Getting Started
    • Scene
    • Parameter Bus
    • SkyBox
    • Model Loader

      • Component Loader
      • Function Loader
    • Popup
    • Callout
    • Movable Element
    • Animation
    • Model Rotator
    • Picker
    • Fit Camera
    • Mesh

      • Wave Circle Mesh
      • Flow Line Mesh
    • Effect

      • Nature

        • Rain
        • Snow
        • Water
        • Water Pool
        • Sandy Beach
      • Sky & Atmosphere

        • Sky Dome
        • HeightFog
        • Nebula Galaxy
      • Light

        • Bloom
        • Sweep Light
        • Light Gradient
        • Light Pillar
        • Radar Sweep
        • Signal Wave
        • Force Shield
      • Particles & Sprites

        • Fireworks
          • Default Usage
          • Options
          • Class usage
        • Text Fireworks
        • Glow Sprite
    • GIS

      • Geographic Reference
      • GeoObject
      • GeoJsonLayer
      • Tile Layer

type

Class

Fireworks is a GPU-animated fireworks shell. A single launch streak rises from the origin, then bursts into a spherical spray of gravity-bent ribbon trails whose heads glow and whose tails dissolve through value noise. The whole motion lives in a TSL node material, so one shell is a single draw call and it runs on both WebGPU and WebGL.

The shell advances its own clock, so update(delta) is optional — call it only if you want to drive the timeline yourself. Each ribbon is a camera-facing quad strip built from an icosahedron that is projected onto a sphere, so detail controls how many bursts the shell produces.

Default Usage

Click me to view the codes
<template>
  <tv-scene class="scene" bg-color="#1a1a2e" @created="created"></tv-scene>
</template>

<script lang="ts" setup>
import { onBeforeUnmount } from 'vue'
import * as THREE from 'three'
import { Fireworks } from 'three-vue3'

let effects: Fireworks[] = []

// A small scripted show: each shell differs in color, burst height, spread,
// screen position and phase lengths so the shells desynchronise and keep
// popping instead of firing in a single synchronized volley.
const shells = [
  { color: 0xffd4a0, height: 6.6, scale: 3.6, offset: [-3.6, 0, -1.5], launch: 1.25, burst: 1.9 },
  { color: 0xff6b6b, height: 7.4, scale: 3.2, offset: [3.2, 0, -0.8], launch: 1.5, burst: 2.2 },
  { color: 0x7ad7ff, height: 5.9, scale: 3.9, offset: [-1.4, 0, 1.6], launch: 1.7, burst: 1.6 },
  { color: 0xffe14d, height: 8.1, scale: 3.1, offset: [1.8, 0, -2.4], launch: 1.35, burst: 2.4 },
  { color: 0xb98bff, height: 6.9, scale: 3.5, offset: [-4.4, 0, 1.2], launch: 1.6, burst: 1.8 },
  { color: 0x66ffb2, height: 7.7, scale: 3.3, offset: [4.1, 0, 1.8], launch: 1.2, burst: 2.1 },
  { color: 0xffffff, height: 6.2, scale: 3.8, offset: [0.2, 0, 0.4], launch: 1.45, burst: 1.7 },
  { color: 0xff8ad4, height: 8.4, scale: 3.0, offset: [-2.6, 0, -2.8], launch: 1.75, burst: 2.3 },
  { color: 0xffa54d, height: 7.1, scale: 3.4, offset: [2.7, 0, 2.6], launch: 1.3, burst: 1.95 },
  { color: 0x8ab4ff, height: 6.8, scale: 3.7, offset: [-0.9, 0, -1.1], launch: 1.55, burst: 2.05 }
]

const created = (scene, { camera }) => {
  camera.position.set(0, 6, 17)
  camera.lookAt(0, 6, 0)

  effects = shells.map((shell) => {
    const fireworks = new Fireworks({
      color: shell.color,
      burstHeight: shell.height,
      burstScale: shell.scale,
      burstPositionOffset: new THREE.Vector3(shell.offset[0], shell.offset[1], shell.offset[2]),
      launchDuration: shell.launch,
      burstDuration: shell.burst,
      loop: true
    })
    scene.add(fireworks)
    return fireworks
  })
}

onBeforeUnmount(() => {
  for (const effect of effects) effect.dispose()
  effects = []
})
</script>

<style>
.scene {
  margin-top: 10px;
  margin-bottom: 16px;
  width: 100%;
  height: 300px;
}
</style>

Options

NameTypeDefaultDescription
radiusnumber1optional Burst trail target length radius, baked into the geometry.
detailnumber0optional Icosahedron subdivision level, baked into the geometry. More detail means more bursts.
segmentsnumber5optional Number of segments sampled along each trail, baked into the geometry.
gravitynumber1optional Gravity parabola coefficient, baked into the geometry.
widthnumber0.1optional Ribbon half-width.
startTimenumber0optional Animation start time in seconds.
launchDurationnumber1.5optional Launch phase duration in seconds.
delayDurationnumber-0.4optional Delay between launch and burst in seconds; may be negative to overlap the phases.
burstDurationnumber2optional Burst phase duration in seconds.
burstHeightnumber6.5optional Burst height along the local Y axis.
burstScalenumber3.5optional Overall burst scale.
burstPositionOffsetVector3(0, 0, 0)optional Burst origin offset.
loopbooleantrueoptional Replay the effect when one cycle finishes.
colorColorRepresentation'#ffd4a0'optional Base ribbon color.
bloomIntensitynumber9optional Head glow intensity.
bloomFalloffnumber18optional Head glow length exponent; larger values tighten the glowing tip.
noiseFalloffnumber3optional Noise dissolve time exponent.
noiseScaleVector2(10, 200)optional Noise UV scale as (across, along).

Class usage

import * as THREE from 'three'
import { Fireworks } from 'three-vue3'

const shell = new Fireworks({
  color: '#ffd166',
  burstHeight: 6.5,
  burstScale: 3.5,
  burstPositionOffset: new THREE.Vector3(0, 0, 0)
})
scene.add(shell)

// The shell animates itself. `update(delta)` is optional and only needed when
// you want to drive the timeline manually:

// Live tweaks, the uniforms are updated in place:
shell.width = 0.14
shell.burstScale = 4
shell.color = '#4aa8ff'

// Restart the current cycle:
shell.restart()

// On teardown:
shell.dispose()
Edit this page on GitHub
Last Updated:
Contributors: Shing Rui
Next
Text Fireworks