Build real-time collaboration features into a Three.js application

In this tutorial, we will guide you through integrating real-time collaboration features into a Three.js application using SuperViz. Real-time collaboration allows multiple users to interact within a 3D environment simultaneously, making it ideal for applications such as design, games or interactive education.

We'll demonstrate how to set up a Three.js scene and integrate SuperViz to enable features like real-time presence, contextual comments, and collaborative navigation within the 3D space. By the end of this tutorial, you'll have a fully functional Three.js application with real-time collaboration capabilities that you can extend and customize to meet your specific needs.
Let's get started!

Step 1: Set Up Your React Application

To begin, you'll need to set up a new React project where we will integrate SuperViz and Three.js for real-time collaboration.

1. Create a New React Project

First, create a new React application using Vite with TypeScript.

1
npm create vite@latest three-js -- --template react-ts
2
cd three-js

Vite is a modern build tool that provides a faster and more efficient development experience compared to Create React App. It also supports TypeScript out of the box.

2. Install Required Libraries

Next, install the necessary libraries for our project:

1
npm install @superviz/sdk three @superviz/threejs-plugin uuid

• @superviz/sdk: For integrating real-time collaboration features.
• three: The core library for creating 3D graphics in the browser.
• @superviz/threejs-plugin: A plugin for adding SuperViz features like presence and comments to a Three.js scene.
• uuid: A library for generating unique identifiers, useful for creating unique participant IDs.

3. Configure tailwind

In this tutorial, we'll use the Tailwind css framework. First, install the tailwind package.

1
npm install -D tailwindcss postcss autoprefixer
2
npx tailwindcss init -p

We then need to configure the template path. Open tailwind.config.js in the root of the project and insert the following code.

1
/** @type {import('tailwindcss').Config} */
2
export default {
3
content: [
4
"./index.html",
5
"./src/**/*.{js,ts,jsx,tsx}",
6
],
7
theme: {
8
extend: {},
9
},
10
plugins: [],
11
}

Then we need to add the tailwind directives to the global CSS file. (src/index.css)

1
@tailwind base;
2
@tailwind components;
3
@tailwind utilities;

4. Set Up Environment Variables

Create a .env file in your project root and add your SuperViz developer key. This key will be used to authenticate your application with SuperViz services.

1
VITE_SUPERVIZ_API_KEY=YOUR_SUPERVIZ_DEVELOPER_KEY

Step 2: Implement the Main Application

In this step, we'll implement the main application logic to initialize SuperViz and integrate it with a Three.js scene for real-time collaboration.

1. Implement the App Component

Open src/App.tsx and set up the main application component using SuperViz to manage the collaborative 3D environment.

1
import { v4 as generateId } from 'uuid';
2
import { useCallback, useEffect } from "react";
3
import SuperVizRoom, { Comments } from '@superviz/sdk';
4
import * as THREE from 'three';
5
import { RoomEnvironment } from "three/examples/jsm/environments/RoomEnvironment.js";
6
import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
7
import { GLTF, GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
8
import { Presence3D, ThreeJsPin } from '@superviz/threejs-plugin';

Explanation:

• Imports: Import necessary components from React, SuperViz, Three.js, and plugins for managing state, rendering the 3D scene, and integrating SuperViz features.

2. Define Constants

Define constants for the API key, room ID, and participant ID.

1
const apiKey = import.meta.env.VITE_SUPERVIZ_API_KEY as string;
2

3
const ROOM_ID = 'threejs-tutorial';
4
const PLAYER_ID = generateId();

Explanation:

• apiKey: Retrieves the SuperViz API key from environment variables.
• ROOM_ID & PLAYER_ID: Defines the room ID for the SuperViz session and generates a unique player ID for each participant.

3. Create the App Component

Set up the main App component and initialize the Three.js scene along with SuperViz.

1
export default function App() {
2
  useEffect(() => {
3
    initializeThreeJs();
4
  }, []);

Explanation:

• useEffect: Calls the initializeThreeJs function once when the component mounts to set up the Three.js scene and SuperViz.

4. Initialize SuperViz

Create a function to initialize SuperViz and integrate presence and comments features into the Three.js scene.

1
const initializeSuperViz = useCallback(async (scene: THREE.Scene, camera: THREE.Camera, renderer: THREE.Renderer) => {
2
  const superviz = await SuperVizRoom(apiKey, {
3
    roomId: ROOM_ID,
4
    participant: {
5
      id: PLAYER_ID,
6
      name: 'player-name',
7
    },
8
    group: {
9
      id: 'threejs-tutorial',
10
      name: 'threejs-tutorial',
11
    }
12
  });
13

14
  const presence = new Presence3D(scene, camera, camera);
15
  const pinAdapter = new ThreeJsPin(scene, renderer, camera);
16
  const comments = new Comments(pinAdapter, {
17
    buttonLocation: 'top-right',
18
  });
19

20
  superviz.addComponent(presence);
21
  superviz.addComponent(comments);
22
}, [])

Explanation:

• initializeSuperViz: Initializes SuperViz with the Three.js scene, adding real-time presence and contextual comments features.
• Presence3D: Displays real-time presence information, showing where each participant is interacting within the 3D space.
• ThreeJsPin & Comments: Enables users to pin comments to specific locations in the 3D model, enhancing collaborative review sessions.

5. Initialize Three.js

Create a function to set up the Three.js scene, including the camera, lighting, controls, and loading a 3D model.

1
const initializeThreeJs = useCallback(async () => {
2
  const canvas = document.getElementById('showcase') as HTMLCanvasElement;
3
  const width = canvas.clientWidth;
4
  const height = canvas.clientHeight;
5

6
  const renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
7
  renderer.setSize(width, height);
8

9
  const pmremGenerator = new THREE.PMREMGenerator(renderer);
10
  const scene = new THREE.Scene();
11
  scene.background = new THREE.Color(0xb6b7b8);
12
  scene.environment = pmremGenerator.fromScene(new RoomEnvironment(), 0.04).texture;
13

14
  const camera = new THREE.PerspectiveCamera(60, width / height, 0.1, 300);
15
  camera.position.set(2, 0, 2);
16

17
  const controls = new OrbitControls(camera, renderer.domElement);
18
  controls.target.set(0, 0.5, 0);
19
  controls.update();
20
  controls.enablePan = false;
21
  controls.enableDamping = true;
22

23
  const loader = new GLTFLoader();
24
  loader.load(
25
    "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/GlamVelvetSofa/glTF-Binary/GlamVelvetSofa.glb",
26
    (model: GLTF) => {
27
      scene.add(model.scene);
28
      initializeSuperViz(scene, camera, renderer);
29
    },
30
    undefined,
31
    (e: unknown) => {
32
      console.error(e);
33
    }
34
  );
35

36
  const animate = () => {
37
    requestAnimationFrame(animate);
38
    controls.update();
39
    renderer.render(scene, camera);
40
  };
41

42
  animate();
43
}, [initializeSuperViz]);

Explanation:

• initializeThreeJs: Sets up the Three.js scene, loads a 3D model, and then initializes SuperViz for real-time collaboration.
• GLTFLoader: Loads a 3D model (in this case, a sofa) into the scene.
• animate: Continuously updates the scene, ensuring smooth interaction and rendering.

Step 3: Render the 3D Scene

Finally, return the JSX structure for rendering the Three.js scene and interacting with it in real-time.

1
return (
2
  <div className='w-full h-full bg-gray-200 flex items-center justify-center flex-col'>
3
    <header className='w-full p-5 bg-purple-400 flex items-center justify-between'>
4
      <h1 className='text-white text-2xl font-bold'>SuperViz Three.JS</h1>
5
    </header>
6
    <main className='w-full h-full flex items-center justify-center relative'>
7
      <canvas id='showcase' className='w-full h-full' />
8
    </main>
9
  </div>
10
);

Explanation:

• Viewer Container: The showcase canvas is where the Three.js scene will be rendered, filling the entire screen. This is where users will interact with the 3D space and collaborate in real-time.

Step 4: Understanding the Project Structure

Here's a quick overview of how the project structure supports real-time collaboration in a Three.js application:

1. App.tsx:
   • Initializes SuperViz and sets up real-time collaboration features, including presence and comments.
   • Handles the Three.js scene setup and loading of 3D models.
2. 3D Scene: Renders a basic Three.js scene with interactive objects. Supports real-time interaction and updates using SuperViz.
3. Real-Time Communication: Manages real-time communication between participants using SuperViz.

Step 5: Running the Application

1. Start the React Application

To run your application, use the following command in your project directory:

1
npm run dev

This command will start the development server and open your application in the default web browser. You can interact with the 3D scene and see real-time presence and comments from other participants.

2. Test the Application

• Real-Time Collaboration: Open the application in multiple browser windows or tabs to simulate multiple participants and verify that presence and comments are synchronized in real-time.
• Collaborative Interaction: Test the responsiveness of the application by interacting with the 3D scene and observing how it updates for all participants.

Summary

In this tutorial, we built a Three.js application with real-time collaboration features using SuperViz. We configured a React application to handle real-time interaction within a 3D scene, enabling multiple users to collaborate seamlessly. This setup can be extended and customized to fit various scenarios where real-time collaboration in a 3D environment is essential.

Feel free to explore the full code and further examples in the GitHub repository for more details.