Getting Started with Three.js: Creating Your First 3D Scene
Three.js is a powerful JavaScript library that enables developers to create stunning 3D graphics in the browser. This guide will walk you through the fundamental steps of setting up a basic Three.js scene.
- Including Three.js in You're Project
First, you need to include the Three.js library in your project. You can either download the library locally or use a CDN version.
// Using local file
import * as THREE from "./three.module.js";
// Or using CDN
// import * as THREE from 'https://unpkg.com/three/build/three.module.js';
- Setting Up the Scene
A scene serves as a container for all your 3D objects, lights, cameras, and other elements you want to display.
const sceneContainer = new THREE.Scene();
- Configuring the Camera
The camera determines what portion of the scene is visible and how it's projected. We'll use a perspective camera for this example.
const viewerCamera = new THREE.PerspectiveCamera();
- Creating 3D Objects
Three.js requires both geometry (shape) and material (appearance) to create visible 3D objects.
4.1 Defining Geometry
Let's create a cube as our first example object:
const cubeShape = new THREE.BoxGeometry();
4.2 Applying Materials
Materials define how surfaces appear in the scene, including their color and other properties.
const surfaceMaterial = new THREE.MeshBasicMaterial({
color: 0x00ff00 // Green color
});
- Creating and Positioning Meshes
A mesh combines geometry and material to create a renderable object. We'll add our cube to the scene and position it.
const cubeObject = new THREE.Mesh(cubeShape, surfaceMaterial);
cubeObject.position.set(0, 3, 0);
sceneContainer.add(cubeObject);
- Setting Up the Renderer
The renderer is responsible for rendering your 3D scene to the browser's canvas element.
const graphicsRenderer = new THREE.WebGLRenderer();
// Set the renderer to match the window size
graphicsRenderer.setSize(window.innerWidth, window.innerHeight);
- Adding the Canvas to the Page
Finally, we need to add the renderer's canvas element to our HTML document.
document.body.appendChild(graphicsRenderer.domElement);
- Implementing Animation
To bring our scene to life, we'll create an animation loop that updates and renders the scene continuously.
function animationLoop() {
// Request the next animation frame
requestAnimationFrame(animationLoop);
// Rotate the cube
cubeObject.rotation.x += 0.01;
// Render the scene
graphicsRenderer.render(sceneContainer, viewerCamera);
}
// Start the animation
animationLoop();
Complete Example
Here's a complete HTML file that demonstrates all these concepts together:
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Three.js Basic Scene</title>
</head>
<body>
<script type="module">
import * as THREE from "./three.module.js";
// Alternative: import * as THREE from 'https://unpkg.com/three/build/three.module.js';
// Create the scene
const sceneContainer = new THREE.Scene();
// Set up the camera
const viewerCamera = new THREE.PerspectiveCamera();
viewerCamera.position.z = 10;
viewerCamera.position.y = 2;
viewerCamera.position.x = 2;
// Create a cube
const cubeShape = new THREE.BoxGeometry();
const surfaceMaterial = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
const cubeObject = new THREE.Mesh(cubeShape, surfaceMaterial);
cubeObject.position.set(0, 3, 0);
sceneContainer.add(cubeObject);
// Add a grid helper for reference
const gridHelper = new THREE.GridHelper(10, 10);
sceneContainer.add(gridHelper);
// Create the renderer
const graphicsRenderer = new THREE.WebGLRenderer();
graphicsRenderer.setSize(window.innerWidth, window.innerHeight);
// Add the canvas to the page
document.body.appendChild(graphicsRenderer.domElement);
// Initial render
graphicsRenderer.render(sceneContainer, viewerCamera);
// Animation loop
function animationLoop() {
requestAnimationFrame(animationLoop);
cubeObject.rotation.x += 0.01;
graphicsRenderer.render(sceneContainer, viewerCamera);
}
// Start the animation
animationLoop();
</script>
</body>
</html>
This example creates a simple 3D scene with a rotating green cube above a grid reference plane. You can expand upon this foundation to create more complex 3D experiences.