⚠️ This lesson is not yet translated in your language, it will be available soon!

Welcome to Sky Adventure, a futuristic company providing the best fireworks in the galaxy! 🎇

We are going to create a 3D website to showcase our fireworks using Three.js, React Three Fiber, and our VFX engine.

This is what we are going to build together!

Starter project

Our starter project already includes the following:

• A basic React Three Fiber setup with a lovely floating island from where we will launch our fireworks.
• Post-processing effects to make bloom the lights from the model (and later the fireworks).
• A simple UI made with Tailwind CSS with three buttons to later launch the fireworks.

Here is what we get when we run the starter project.

Fireworks

To create the fireworks, we will use the VFX engine we built in the previous lesson. This engine allows us to create and manage multiple particle systems with different behaviors.

useFireworks

To efficiently manage the fireworks, we will create a custom hook called useFireworks. This hook will handle the creation and management of the fireworks.

Let's add zustand library to our project:

Copy
yarn add zustand

Now in a folder called hooks, create a new file called useFireworks.js:

Copy
import { create } from "zustand";

const useFireworks = create((set, get) => {
  return {
    fireworks: [],
  };
});

export { useFireworks };

A simple store with an empty array of fireworks.

Let's add a method to create a firework:

Copy
// ...
import { randFloat, randInt } from "three/src/math/MathUtils.js";

const useFireworks = create((set) => {
  return {
    fireworks: [],
    addFirework: () => {
      set((state) => {
        return {
          fireworks: [
            ...state.fireworks,
            {
              id: `${Date.now()}-${randInt(0, 100)}-${state.fireworks.length}`,
              position: [0, 0, 0],
              velocity: [randFloat(-8, 8), randFloat(5, 10), randFloat(-8, 8)],
              delay: randFloat(0.8, 2),
              color: ["skyblue", "pink"],
            },
          ],
        };
      });
    },
  };
});

// ...

addFirework will add a new firework to the store with:

• id: a unique identifier to use as a key in the React component.
• position: where the firework will start.
• velocity: the direction and speed of the firework before exploding.
• delay: the time before the firework explodes.
• color: an array of colors to use for the firework explosion particles.

We can now connect this hook to our UI to launch fireworks.

Open UI.jsx and let's connect the addFirework method to the buttons:

Copy
import { useFireworks } from "../hooks/useFireworks";

export const UI = () => {
  const addFirework = useFireworks((state) => state.addFirework);

  return (
    <section className="fixed inset-0 z-10 flex items-center justify-center">
      {/* ... */}
      <div
      // ...
      >
        {/* ... */}
        <div className="flex gap-4">
          <button
            // ..
            onClick={addFirework}
          >
            🎆 Classic
          </button>
          <button
            // ..
            onClick={addFirework}
          >
            💖 Love
          </button>
          <button
            // ..
            onClick={addFirework}
          >
            🌊 Sea
          </button>
        </div>
        {/* ... */}
      </div>
    </section>
  );
};

To check if it works, let's create a Fireworks.jsx component. We will simply log the fireworks in the console for now:

Copy
import { useFireworks } from "../hooks/useFireworks";

export const Fireworks = () => {
  const fireworks = useFireworks((state) => state.fireworks);

  console.log(fireworks);
};

And let's add it to the Experience com

Copy
// ...
import { Fireworks } from "./Fireworks";

export const Experience = () => {
  // ...

  return (
    <>
      {/* ... */}

      <Float
        speed={0.6}
        rotationIntensity={2}
        position-x={4}
        floatIntensity={2}
      >
        <Fireworks />
        <Gltf src="/models/SkyIsland.glb" />
      </Float>

      {/* ... */}
    </>
  );
};

We import the Fireworks component and add it next to the SkyIsland in our <Float /> component.

When pressing the buttons, we can see in the console that the fireworks are properly added to the store.

Before representing them in the scene we need to handle the fireworks' lifecycle. Currently, they are added but never removed.

In the addFirework in our useFireworks hook, we can add a setTimeout to remove the firework after a certain time.

First we need to know when the firework spawns. We can add a time property to the firework object:

Copy
{
  id: `${Date.now()}-${randInt(0, 100)}-${state.fireworks.length}`,
  // ...
  time: Date.now(),
},

Then call setTimeout to remove the fireworks that have exploded and faded away:

Copy
addFirework: () => {
  set((state) => {
    // ...
  });
  setTimeout(() => {
    set((state) => ({
      fireworks: state.fireworks.filter(
        (firework) => Date.now() - firework.time < 4000 // Max delay of 2 seconds +  Max lifetime of particles of 2 seconds
      ),
    }));
  }, 4000);
},

We filter the fireworks that have been added more than 4 seconds ago. This way, we keep the fireworks that are still active.

Adjust the time according to the final settings you will use for the fireworks.

When pressing the buttons, we can see in the console that the fireworks are properly removed after a certain time.

We can now dive into the part you've been waiting for: creating the fireworks in the scene!

VFX engine (Wawa VFX)

To not copy/paste the component from the previous lesson, I published the VFX engine as a package on npm: Wawa VFX. You can install it by running:

Copy
yarn add wawa-vfx@^1.0.0

By using @^1.0.0, we ensure that we always use the major version 1 of the package but including the latest minor and patch versions. This way, we can benefit from the latest features and bug fixes without breaking changes.

We can now use the <VFXParticles /> and <VFXEmitter /> in our project!

In experience, let's add the VFXParticles component to the scene:

Copy
// ...
import { VFXParticles } from "wawa-vfx";

export const Experience = () => {
  const controls = useRef();

  return (
    <>
      {/* ... */}

      <VFXParticles
        name="firework-particles"
        settings={{
          nbParticles: 100000,
          gravity: [0, -9.8, 0],
          renderMode: "billboard",
          intensity: 3,
        }}
      />

      <EffectComposer>
        <Bloom intensity={1.2} luminanceThreshold={1} mipmapBlur />
      </EffectComposer>
    </>
  );
};

We add the VFXParticles component with the following settings:

• 100000 particles. As when we reach the limit, the oldest particles will be removed, it should be more than enough for many fireworks at the same time.
• gravity to simulate the gravity on the particles. -9.8 is the gravity on Earth. (But wait we are in space! 👀)
• renderMode to billboard to always face the camera.
• intensity to 3 to make the particles glow in the night sky.

Where you place the <VFXParticles /> component is not very important. Just be sure it is at the top level of the scene.

And let's add a VFXEmitter component next to the VFXParticles to shape the explosion in debug mode and have access to the visual controls:

Copy
// ...
import { VFXEmitter, VFXParticles } from "wawa-vfx";

export const Experience = () => {
  const controls = useRef();

  return (
    <>
      {/* ... */}

      <VFXParticles
        name="firework-particles"
        settings={{
          nbParticles: 100000,
          gravity: [0, -9.8, 0],
          renderMode: "billboard",
          intensity: 3,
        }}
      />
      <VFXEmitter emitter="firework-particles" debug />

      {/* ... */}
    </>
  );
};

Be sure to set the emitter prop to the same name as the VFXParticles component and to set debug to true to see the controls.

*Draft a first version of the fireworks explosion. *💥

Once you are happy with the settings, you can remove the debug prop from the VFXEmitter component, press the export button and paste the settings in the VFXEmitter component.

Copy
<VFXEmitter
  emitter="firework-particles"
  settings={{
    nbParticles: 5000,
    delay: 0,
    spawnMode: "burst",
    colorStart: ["skyblue", "pink"],
    particlesLifetime: [0.1, 2],
    size: [0.01, 0.4],
    startPositionMin: [-0.1, -0.1, -0.1],
    startPositionMax: [0.1, 0.1, 0.1],
    directionMin: [-1, -1, -1],
    directionMax: [1, 1, 1],
    startRotationMin: [degToRad(-90), 0, 0],
    startRotationMax: [degToRad(90), 0, 0],
    rotationSpeedMin: [0, 0, 0],
    rotationSpeedMax: [3, 3, 3],
    speed: [1, 12],
  }}
/>

We have everything ready to connect the fireworks to the VFX engine!

Fireworks explosion

Inside the Fireworks.jsx file, let's create a Firework component that will represent one firework:

Copy
// ...
import { useRef } from "react";
import { VFXEmitter } from "wawa-vfx";

export const Fireworks = () => {
  // ...
};

const Firework = ({ velocity, delay, position, color }) => {
  const ref = useRef();
  return (
    <>
      <group ref={ref} position={position}>
        <VFXEmitter
          emitter="firework-particles"
          settings={{
            nbParticles: 5000,
            delay: 0,
            spawnMode: "burst",
            colorStart: ["skyblue", "pink"],
            particlesLifetime: [0.1, 2],
            size: [0.01, 0.4],
            startPositionMin: [-0.1, -0.1, -0.1],
            startPositionMax: [0.1, 0.1, 0.1],
            directionMin: [-1, -1, -1],
            directionMax: [1, 1, 1],
            startRotationMin: [degToRad(-90), 0, 0],
            startRotationMax: [degToRad(90), 0, 0],
            rotationSpeedMin: [0, 0, 0],
            rotationSpeedMax: [3, 3, 3],
            speed: [1, 12],
          }}
        />
      </group>
    </>
  );
};

Simply cut/paste the VFXEmitter from the Experience component to the Firework component.

We wrap it in a <group /> to be able to move the firework in the scene based on the position and velocity.