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
        • Text Fireworks
          • Default Usage
          • Options
          • Members
          • Methods
          • Class usage
        • Glow Sprite
    • GIS

      • Geographic Reference
      • GeoObject
      • GeoJsonLayer
      • Tile Layer

type

Class

TextFireworks samples a line of text into glyph particles and turns it into a firework. On launch() the glyph flies apart into groups of colored bursts, then every particle is pulled back to the pixel it came from, leaving the readable text on screen again. Each particle is a camera-facing quad sized in CSS pixels, so the effect keeps its look at any distance.

The text is rasterized on an offscreen canvas and sampled on a fixed grid; worldScale converts the sampled pixels into world units. The class advances its own timeline, so update(delta) is optional.

Default Usage

Click me to view the codes
<template>
  <div>
    <div class="toolbar">
      <input v-model="text" class="input" placeholder="Type a sentence" @keyup.enter="launch" />
      <button type="button" class="button" @click="launch">Launch</button>
    </div>
    <tv-scene class="scene" bg-color="rgb(40, 42, 54)" @created="created"></tv-scene>
  </div>
</template>

<script lang="ts" setup>
import { onBeforeUnmount, ref } from 'vue'
import { TextFireworks } from 'three-vue3'

const DEFAULT_TEXT = 'Good things are coming'

const text = ref(DEFAULT_TEXT)
let effect: TextFireworks | undefined

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

  effect = new TextFireworks({ text: DEFAULT_TEXT })
  scene.add(effect)
}

const launch = () => {
  if (!effect) return
  // Sampling a new sentence rebuilds the particles, then replay the cycle.
  effect.setText(text.value)
  effect.launch()
}

onBeforeUnmount(() => {
  effect?.dispose()
  effect = undefined
})
</script>

<style>
.scene {
  margin-top: 10px;
  margin-bottom: 16px;
  width: 100%;
  height: 300px;
}
.toolbar {
  display: flex;
  gap: 8px;
  margin-top: 10px;
}
.input {
  flex: 1;
  padding: 6px 10px;
  border-radius: 6px;
  border: 1px solid var(--vp-c-divider);
  background: var(--vp-c-bg);
  color: var(--vp-c-text-1);
}
.button {
  padding: 6px 14px;
  border-radius: 6px;
  cursor: pointer;
  color: var(--vp-c-white);
  background: var(--vp-c-brand-1);
  border: none;
}
</style>

Options

NameTypeDefaultDescription
textstring'Good things are coming'optional Text sampled into particles.
colorsColorRepresentation[]['#ff8a3d', '#ffd166', '#4aa8ff', '#b06cff']optional Burst colors from left to right.
burstCenters[number, number][]four staggered positionsoptional Burst center of each group in world units.
burstScalenumber1optional Uniform scale applied to burst centers and radial spread.
groupDelaynumber0.22optional Seconds between the launches of successive groups.
groupJitternumber0.2optional Extra per-particle delay jitter in seconds.
pointSizenumber3.4optional Particle size in CSS pixels.
trailOffsetnumber0.105optional Seconds the trail layer lags behind the main layer.
trailOpacitynumber0.34optional Opacity multiplier of the trail layer.
restColorColorRepresentation0xffd4adoptional Color the letters rest at and fade back to.
worldScalenumber0.0068optional World units per sampled canvas pixel.
offsetYnumber0.55optional Vertical offset of the text center in world units.
autoPlaybooleantrueoptional Play once automatically after the object is created.
autoPlayDelaynumber1.2optional Seconds before the automatic launch, counted down by update(delta).
seednumber1optional Seed for the deterministic per-particle randomness.

Members

NameTypeDescription
pointsMeshMain particle layer.
trailMeshDelayed, dimmer copy of the same particles used as a trail.
textstringText currently sampled into the particle cloud.
particleCountnumberNumber of glyph particles, each rendered as a billboarded quad.
durationnumberLength of one lift-off / burst / return cycle in seconds.
phasenumberCurrent position on the timeline in seconds.
playingbooleanWhether the timeline is currently advancing.

Methods

NameDescription
update(delta)Optional: advance the timeline manually; the class also runs its own clock.
launch()Restart the lift-off / burst / return cycle from 0.
setText(text)Re-sample new text and settle back at rest.
dispose()Dispose the geometry and both materials, then remove the group from its parent.

Class usage

import { TextFireworks } from 'three-vue3'

const effect = new TextFireworks({ text: 'Good things are coming', autoPlay: false })
scene.add(effect)

// The effect animates itself. `update(delta)` is optional.

// Replay with the same text, or sample a new line:
effect.launch()
effect.setText('Hello')

// On teardown:
effect.dispose()
Edit this page on GitHub
Last Updated:
Contributors: Shing Rui
Prev
Fireworks
Next
Glow Sprite