AgentSkillsCN

threejs-fundamentals

Three.js 场景搭建、相机、渲染器、Object3D 层次结构、坐标系。当您需要搭建 3D 场景、创建相机、配置渲染器、管理对象层次,或处理变换时,可运用此技能。

SKILL.md
--- frontmatter
name: threejs-fundamentals
description: Three.js scene setup, cameras, renderer, Object3D hierarchy, coordinate systems. Use when setting up 3D scenes, creating cameras, configuring renderers, managing object hierarchies, or working with transforms.

Three.js Fundamentals

Quick Start

javascript
import * as THREE from "three";

// Create scene, camera, renderer
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(
  75,
  window.innerWidth / window.innerHeight,
  0.1,
  1000,
);
const renderer = new THREE.WebGLRenderer({ antialias: true });

renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
document.body.appendChild(renderer.domElement);

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

// Add light
scene.add(new THREE.AmbientLight(0xffffff, 0.5));
const dirLight = new THREE.DirectionalLight(0xffffff, 1);
dirLight.position.set(5, 5, 5);
scene.add(dirLight);

camera.position.z = 5;

// Animation loop
function animate() {
  requestAnimationFrame(animate);
  cube.rotation.x += 0.01;
  cube.rotation.y += 0.01;
  renderer.render(scene, camera);
}
animate();

// Handle resize
window.addEventListener("resize", () => {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(window.innerWidth, window.innerHeight);
});

Core Classes

Scene

javascript
const scene = new THREE.Scene();
scene.background = new THREE.Color(0x000000);
scene.fog = new THREE.Fog(0xffffff, 1, 100);

Cameras

javascript
// PerspectiveCamera(fov, aspect, near, far)
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
camera.position.set(0, 5, 10);
camera.lookAt(0, 0, 0);

WebGLRenderer

javascript
const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
renderer.setSize(width, height);
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = THREE.PCFSoftShadowMap;
renderer.toneMapping = THREE.ACESFilmicToneMapping;
renderer.outputColorSpace = THREE.SRGBColorSpace;

Object3D

javascript
obj.position.set(x, y, z);
obj.rotation.set(x, y, z);
obj.scale.set(x, y, z);
obj.add(child);
obj.remove(child);
obj.traverse((child) => { /* ... */ });

Math Utilities

Vector3

javascript
const v = new THREE.Vector3(x, y, z);
v.add(v2); v.sub(v2); v.normalize(); v.lerp(target, alpha);
v.length(); v.distanceTo(v2); v.dot(v2); v.cross(v2);

MathUtils

javascript
THREE.MathUtils.clamp(value, min, max);
THREE.MathUtils.lerp(start, end, alpha);
THREE.MathUtils.degToRad(degrees);
THREE.MathUtils.randFloat(min, max);

Common Patterns

Clock for Animation

javascript
const clock = new THREE.Clock();
function animate() {
  const delta = clock.getDelta();
  mesh.rotation.y += delta * 0.5;
  requestAnimationFrame(animate);
  renderer.render(scene, camera);
}

Proper Cleanup

javascript
function dispose() {
  mesh.geometry.dispose();
  mesh.material.dispose();
  scene.remove(mesh);
  renderer.dispose();
}

See Also

  • threejs-geometry - Geometry creation
  • threejs-materials - Material types
  • threejs-lighting - Light types and shadows