TypeScript & Three.js: Building Interactive 3D Scenes

Written by

learnmodernjavascript

in

In the ever-evolving landscape of web development, creating immersive and interactive experiences is becoming increasingly important. Imagine a website where users can rotate a 3D model of a product, explore a virtual environment, or visualize complex data in three dimensions. This is where Three.js, a powerful JavaScript library, comes into play, and when combined with TypeScript, the development process becomes even more robust and maintainable. This tutorial will guide you through building interactive 3D scenes using Three.js and TypeScript, designed specifically for beginners and intermediate developers.

Why TypeScript and Three.js?

Before diving into the code, let’s explore why TypeScript and Three.js are a great combination:

  • TypeScript: TypeScript adds static typing to JavaScript, which helps catch errors early in the development process. It improves code readability, maintainability, and refactoring, making it easier to work on larger projects.
  • Three.js: This library simplifies the process of creating 3D graphics in the browser. It abstracts away the complexities of WebGL, allowing you to focus on the creative aspects of 3D development.
  • Combined Power: TypeScript provides type safety for your Three.js code, ensuring that you’re using the library’s features correctly and reducing the chances of runtime errors. This synergy results in more reliable and scalable 3D applications.

Setting Up Your Development Environment

Before we start coding, you’ll need to set up your development environment. Follow these steps:

  1. Install Node.js and npm: If you haven’t already, download and install Node.js and npm (Node Package Manager) from nodejs.org. npm is used to manage project dependencies.
  2. Create a Project Directory: Create a new directory for your project and navigate into it using your terminal.
  3. Initialize a Node.js Project: Run npm init -y in your terminal to create a package.json file.
  4. Install TypeScript and Three.js: Run the following command to install TypeScript and Three.js as project dependencies: 
    npm install typescript three @types/three --save-dev
    • typescript: The TypeScript compiler.
    • three: The Three.js library.
    • @types/three: Type definitions for Three.js, which are crucial for TypeScript integration.
  5. Create a TypeScript Configuration File: Run npx tsc --init in your terminal to generate a tsconfig.json file. This file allows you to configure TypeScript compiler options.
  6. Create Project Files: Create the following files in your project directory:
    • index.html: The HTML file for your web page.
    • src/index.ts: The main TypeScript file where you’ll write your Three.js code.

Writing Your First 3D Scene

Now, let’s write the code for a basic 3D scene. Open src/index.ts and add the following code:

import * as THREE from 'three';

// 1. Create a scene
const scene = new THREE.Scene();

// 2. Create a camera
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
camera.position.z = 5;

// 3. Create a renderer
const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

// 4. Create a geometry (e.g., a cube)
const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);

// 5. Animation loop
function animate() {
 requestAnimationFrame(animate);

 cube.rotation.x += 0.01;
 cube.rotation.y += 0.01;

 renderer.render(scene, camera);
}

animate();

Let’s break down this code step by step:

  • Import Three.js: import * as THREE from 'three'; imports the Three.js library.
  • Create a Scene: const scene = new THREE.Scene(); creates a scene, which is where you’ll place your 3D objects.
  • Create a Camera: const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000); creates a perspective camera. The parameters are:
    • Field of View (FOV): 75 degrees.
    • Aspect Ratio: The width of the viewport divided by the height.
    • Near: Objects closer than 0.1 units from the camera won’t be rendered.
    • Far: Objects further than 1000 units from the camera won’t be rendered.

    camera.position.z = 5; positions the camera 5 units away from the origin along the Z-axis, allowing you to see the cube.

  • Create a Renderer: const renderer = new THREE.WebGLRenderer(); creates a WebGL renderer, which handles the rendering of your 3D scene. renderer.setSize(window.innerWidth, window.innerHeight); sets the size of the renderer to match the browser window. document.body.appendChild(renderer.domElement); adds the renderer’s DOM element to the page.
  • Create a Geometry and Material: const geometry = new THREE.BoxGeometry(1, 1, 1); creates a cube geometry. const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 }); creates a basic material with a green color. const cube = new THREE.Mesh(geometry, material); creates a mesh by combining the geometry and material. scene.add(cube); adds the cube to the scene.
  • Animation Loop: The animate() function is the animation loop. requestAnimationFrame(animate); calls the animate() function again in the next frame, creating a continuous loop. Inside the loop, cube.rotation.x += 0.01; and cube.rotation.y += 0.01; rotate the cube. renderer.render(scene, camera); renders the scene using the camera.

Now, let’s create the index.html file:

<!DOCTYPE html>
<html lang="en">
<head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>My Three.js Scene</title>
 <style>
  body {
   margin: 0;
   overflow: hidden;
  }
 </style>
</head>
<body>
 <script src="./dist/index.js"></script>
</body>
</html>

This HTML file sets up the basic structure of the page, includes a style to remove margins and hide scrollbars, and links to the compiled JavaScript file.

Compiling and Running Your Code

To compile your TypeScript code, run the following command in your terminal:

tsc

This command will compile src/index.ts into dist/index.js based on the configurations in your tsconfig.json file. To run your 3D scene, open index.html in your web browser. You should see a rotating green cube.

Adding More Complex Objects

Let’s add a sphere to our scene. Modify your src/index.ts file as follows:

import * as THREE from 'three';

// Scene, Camera, Renderer (as before)
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
camera.position.z = 5;
const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

// Cube
const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);

// Sphere
const sphereGeometry = new THREE.SphereGeometry(0.5, 32, 32);
const sphereMaterial = new THREE.MeshBasicMaterial({ color: 0xff0000 });
const sphere = new THREE.Mesh(sphereGeometry, sphereMaterial);
sphere.position.x = -2; // Position the sphere to the left of the cube
scene.add(sphere);

// Animation loop
function animate() {
 requestAnimationFrame(animate);

 cube.rotation.x += 0.01;
 cube.rotation.y += 0.01;

 renderer.render(scene, camera);
}

animate();

In this code, we added the following:

  • Sphere Geometry: const sphereGeometry = new THREE.SphereGeometry(0.5, 32, 32); creates a sphere geometry with a radius of 0.5, 32 segments along the width, and 32 segments along the height.
  • Sphere Material: const sphereMaterial = new THREE.MeshBasicMaterial({ color: 0xff0000 }); creates a red material.
  • Sphere Mesh: const sphere = new THREE.Mesh(sphereGeometry, sphereMaterial); creates a mesh using the sphere geometry and material.
  • Sphere Position: sphere.position.x = -2; positions the sphere to the left of the cube.
  • Adding to Scene: scene.add(sphere); adds the sphere to the scene.

Compile your code again using tsc and refresh your browser. You should now see both a rotating green cube and a red sphere.

Adding Lighting

To make your scene more visually appealing, let’s add some lighting. Modify your src/index.ts file:

import * as THREE from 'three';

// Scene, Camera, Renderer (as before)
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
camera.position.z = 5;
const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

// Ambient Light
const ambientLight = new THREE.AmbientLight(0x404040); // Soft white light
scene.add(ambientLight);

// Directional Light
const directionalLight = new THREE.DirectionalLight(0xffffff, 1); // White light
directionalLight.position.set(1, 1, 1); // Position the light
scene.add(directionalLight);

// Cube, Sphere (as before)
const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshPhongMaterial({ color: 0x00ff00 }); // Use MeshPhongMaterial for lighting
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);

const sphereGeometry = new THREE.SphereGeometry(0.5, 32, 32);
const sphereMaterial = new THREE.MeshPhongMaterial({ color: 0xff0000 }); // Use MeshPhongMaterial for lighting
const sphere = new THREE.Mesh(sphereGeometry, sphereMaterial);
sphere.position.x = -2;
scene.add(sphere);

// Animation loop
function animate() {
 requestAnimationFrame(animate);

 cube.rotation.x += 0.01;
 cube.rotation.y += 0.01;

 renderer.render(scene, camera);
}

animate();

Here’s what changed:

  • Ambient Light: const ambientLight = new THREE.AmbientLight(0x404040); creates a soft, white light that illuminates all objects in the scene.
  • Directional Light: const directionalLight = new THREE.DirectionalLight(0xffffff, 1); creates a directional light, like the sun, that casts shadows and highlights. directionalLight.position.set(1, 1, 1); sets the position of the light.
  • MeshPhongMaterial: We changed the material of the cube and sphere to MeshPhongMaterial, which responds to lighting.

Compile and refresh your browser. You should now see the cube and sphere with lighting effects, making the scene more realistic.

Adding Textures

Textures can add a lot of detail to your 3D objects. Let’s add a texture to the cube. First, you’ll need an image file (e.g., a texture image). Save the image in a directory (e.g., assets/) within your project directory. Then, modify your src/index.ts file:

import * as THREE from 'three';

// Scene, Camera, Renderer (as before)
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
camera.position.z = 5;
const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

// Ambient Light, Directional Light (as before)
const ambientLight = new THREE.AmbientLight(0x404040);
scene.add(ambientLight);
const directionalLight = new THREE.DirectionalLight(0xffffff, 1);
directionalLight.position.set(1, 1, 1);
scene.add(directionalLight);

// Load Texture
const textureLoader = new THREE.TextureLoader();
const texture = textureLoader.load('assets/texture.jpg'); // Replace 'texture.jpg' with your image file

// Cube
const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshPhongMaterial({ map: texture }); // Use MeshPhongMaterial with texture
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);

// Sphere (as before)
const sphereGeometry = new THREE.SphereGeometry(0.5, 32, 32);
const sphereMaterial = new THREE.MeshPhongMaterial({ color: 0xff0000 });
const sphere = new THREE.Mesh(sphereGeometry, sphereMaterial);
sphere.position.x = -2;
scene.add(sphere);

// Animation loop
function animate() {
 requestAnimationFrame(animate);

 cube.rotation.x += 0.01;
 cube.rotation.y += 0.01;

 renderer.render(scene, camera);
}

animate();

In this code, we added the following:

  • Texture Loader: const textureLoader = new THREE.TextureLoader(); creates a texture loader.
  • Load Texture: const texture = textureLoader.load('assets/texture.jpg'); loads the texture from the specified file path. Replace 'assets/texture.jpg' with the path to your image file.
  • Apply Texture to Material: We modified the material of the cube to use the loaded texture: const material = new THREE.MeshPhongMaterial({ map: texture });.

Remember to create an assets folder and place your texture image in it. Compile and refresh your browser. The cube should now have the texture applied.

Adding User Interaction

User interaction makes your 3D scenes more engaging. Let’s add the ability to rotate the cube when the user clicks and drags the mouse. Modify your src/index.ts file:

import * as THREE from 'three';

// Scene, Camera, Renderer (as before)
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
camera.position.z = 5;
const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

// Ambient Light, Directional Light, Texture (as before)
const ambientLight = new THREE.AmbientLight(0x404040);
scene.add(ambientLight);
const directionalLight = new THREE.DirectionalLight(0xffffff, 1);
directionalLight.position.set(1, 1, 1);
scene.add(directionalLight);
const textureLoader = new THREE.TextureLoader();
const texture = textureLoader.load('assets/texture.jpg');

// Cube
const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshPhongMaterial({ map: texture });
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);

// Sphere (as before)
const sphereGeometry = new THREE.SphereGeometry(0.5, 32, 32);
const sphereMaterial = new THREE.MeshPhongMaterial({ color: 0xff0000 });
const sphere = new THREE.Mesh(sphereGeometry, sphereMaterial);
sphere.position.x = -2;
scene.add(sphere);

// Mouse interaction variables
let isDragging = false;
let previousMousePosition = { x: 0, y: 0 };

// Event listeners for mouse interaction
document.addEventListener('mousedown', (event: MouseEvent) => {
 isDragging = true;
});

document.addEventListener('mouseup', () => {
 isDragging = false;
});

document.addEventListener('mousemove', (event: MouseEvent) => {
 if (!isDragging) return;

 const deltaX = event.clientX - previousMousePosition.x;
 const deltaY = event.clientY - previousMousePosition.y;

 cube.rotation.y += deltaX * 0.01;
 cube.rotation.x += deltaY * 0.01;

 previousMousePosition = { x: event.clientX, y: event.clientY };
});

document.addEventListener('mouseleave', () => {
 isDragging = false;
});

document.addEventListener('mouseenter', (event: MouseEvent) => {
  previousMousePosition = { x: event.clientX, y: event.clientY };
});

// Animation loop
function animate() {
 requestAnimationFrame(animate);

 renderer.render(scene, camera);
}

animate();

Here’s what we added for user interaction:

  • Mouse Interaction Variables: let isDragging = false; and let previousMousePosition = { x: 0, y: 0 }; are variables to track the dragging state and the previous mouse position.
  • Event Listeners: We added event listeners for mousedown, mouseup, mousemove, mouseleave, and mouseenter events to detect mouse interactions.
    • mousedown: Sets isDragging to true when the mouse button is pressed.
    • mouseup and mouseleave: Sets isDragging to false when the mouse button is released or the mouse leaves the window.
    • mousemove: If isDragging is true, it calculates the difference in mouse position and updates the cube’s rotation.
    • mouseenter: Records the initial mouse position when the mouse enters the window.
  • Rotation Update: Inside the mousemove event listener, we update the cube’s rotation based on the mouse movement: cube.rotation.y += deltaX * 0.01; and cube.rotation.x += deltaY * 0.01;.

Compile and refresh your browser. Now you can rotate the cube by clicking and dragging your mouse.

Common Mistakes and How to Fix Them

Here are some common mistakes and how to fix them:

  • Missing Type Definitions: If you get TypeScript errors related to missing type definitions for Three.js, make sure you have installed @types/three and that your tsconfig.json is configured correctly. Check your tsconfig.json file; it should have the following settings or similar ones: 
    {
  "compilerOptions": {
   "target": "ES2015",
   "module": "ESNext",
   "moduleResolution": "node",
   "strict": true,
   "esModuleInterop": true,
   "skipLibCheck": true,
   "forceConsistentCasingInFileNames": true
  }
}
  • Incorrect File Paths: When loading textures or other assets, ensure that the file paths in your code are correct relative to your HTML file. Double-check your file structure and the paths you’re using.
  • Uncompiled Code: Always remember to compile your TypeScript code using tsc before refreshing your browser. If you make changes to your .ts files but don’t compile, the changes won’t be reflected in your browser.
  • Camera Clipping: If you don’t see your objects, the camera’s near and far clipping planes might be set incorrectly. Adjust the near and far parameters in the PerspectiveCamera constructor.
  • Lighting Issues: If your objects appear dark or flat, ensure you’ve added lighting to your scene and that your materials respond to lighting (e.g., using MeshPhongMaterial or MeshStandardMaterial).
  • Performance Issues: For complex scenes, performance can be an issue. Consider optimizing your code by:
    • Reducing the number of objects.
    • Using instancing to render multiple instances of the same object.
    • Using level of detail (LOD) to render simplified models when objects are far away.
    • Caching calculations.

Key Takeaways

  • TypeScript enhances Three.js development: TypeScript adds type safety and improves code maintainability.
  • Basic Scene Structure: A Three.js scene typically consists of a scene, camera, renderer, and objects.
  • Objects, Materials, and Textures: You can create various 3D objects with different materials and apply textures.
  • Lighting is Crucial: Lighting adds depth and realism to your scenes.
  • User Interaction: You can make your scenes interactive by adding event listeners for mouse and keyboard input.

FAQ

  1. Can I use other 3D models instead of built-in geometries?

    Yes, you can load 3D models in various formats (e.g., GLTF, OBJ) using Three.js loaders. You’ll need to install the appropriate loaders (e.g., npm install three-gltf-loader) and use them to load the models into your scene.

  2. How do I add animations to my scene?

    You can use the Three.js animation system or third-party animation libraries (e.g., GSAP) to animate objects in your scene. This involves creating animations that modify object properties over time.

  3. How can I optimize performance for large scenes?

    Optimize performance by using techniques like level of detail (LOD), instancing, and reducing the number of draw calls. Consider using a scene graph to organize your objects and optimize rendering.

  4. Where can I find more Three.js examples and documentation?

    The official Three.js documentation (threejs.org/docs/) and the Three.js examples (threejs.org/examples/) are excellent resources. There are also many online tutorials and communities where you can learn and get help.

Building interactive 3D scenes with Three.js and TypeScript opens up a world of possibilities for web development. From simple visualizations to complex interactive applications, the combination of these technologies empowers you to create engaging and visually stunning experiences. By following this tutorial and practicing with different geometries, materials, and interactions, you can master the fundamentals and bring your creative visions to life. The journey from a simple rotating cube to a complex, interactive 3D environment is a rewarding one, and with each line of code, you’ll gain a deeper understanding of the power and potential of 3D graphics on the web.

More posts