threejs

Three.js — WebGL 3D シーンのスキル

使用する場面

• 実際の 3D：製品の回転表示、インタラクティブなヒーローシーン、シェーダー／マテリアル効果、3D データの可視化
• 「背景効果」を超える、完全な制御が必要な場合
• アセットのパイプライン構築とパフォーマンス調整に時間を割ける場合

基本的な考え方

• 作成するもの：
  • Scene（ルートグラフ）
  • Camera（透視投影／正射影）
  • Renderer（WebGLRenderer）
  • Mesh = Geometry + Material
  • ライト（非ライティングマテリアルを使用する場合を除く）
• レンダリングループ：
  • requestAnimationFrame(animate)
  • 時間ベースのアニメーション、コントロール、ミキサーを更新してから、renderer.render(scene, camera) を実行します

主な API／パターン

• セットアップ：
  • const renderer = new THREE.WebGLRenderer({ canvas, antialias, alpha })
  • renderer.setSize(width, height, false)
  • renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))
• カメラ：
  • camera.aspect = width / height; camera.updateProjectionMatrix()
• シーングラフ：
  • scene.add(object) / object.position/rotation/scale
• アセットの読み込み：
  • GLTFLoader（モデル）、TextureLoader（画像）、DRACOLoader（圧縮 glTF）
• コントロール（一般的なもの）：
  • OrbitControls（デバッグ／製品表示）、PointerLockControls（FPS）、カスタムポインターハンドラー
• クリーンアップ（SPA では重要）：
  • geometry.dispose()、material.dispose()、texture.dispose()、renderer.dispose()
  • イベントリスナーを削除し、RAF をキャンセルします。

よくある落とし穴

• リサイズに対応しない → レンダリングが引き伸ばされたり、切り取られたりします
• devicePixelRatio が高すぎる → モバイル GPU に過大な負荷がかかります
• WebGL リソースのリーク（破棄しない） → ルート変更後にクラッシュします
• 大きすぎるテクスチャ／モデルを読み込む → 起動が遅くなります。圧縮テクスチャ、Draco／KTX2、小さなマップを使用してください
• ライト／シャドウを使いすぎる → 処理コストが高くなります。可能であれば、ベイク済みテクスチャでライティングを再現してください

すぐに使えるレシピ

1) 最小構成の回転する立方体

import * as THREE from "three";

const canvas = document.querySelector("#c");
const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true });

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 100);
camera.position.set(0, 0, 4);

const geom = new THREE.BoxGeometry(1, 1, 1);
const mat = new THREE.MeshStandardMaterial({ color: 0x7c3aed });
const mesh = new THREE.Mesh(geom, mat);
scene.add(mesh);

scene.add(new THREE.AmbientLight(0xffffff, 0.8));
const dir = new THREE.DirectionalLight(0xffffff, 0.8);
dir.position.set(2, 2, 2);
scene.add(dir);

function resize() {
  const w = canvas.clientWidth;
  const h = canvas.clientHeight;
  renderer.setSize(w, h, false);
  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
  camera.aspect = w / h;
  camera.updateProjectionMatrix();
}
window.addEventListener("resize", resize);
resize();

function animate(t) {
  mesh.rotation.y = t * 0.0006;
  renderer.render(scene, camera);
  requestAnimationFrame(animate);
}
requestAnimationFrame(animate);

2) 視差効果を抑える設定に対応する

• prefers-reduced-motion: reduce の場合は、静止フレームを描画する（RAF を使用しない）か、更新頻度を下げます。

ユーザーに確認すること

• 装飾用（ヒーロー）ですか、それとも機能的な 3D（製品ビューア）ですか？
• 対象デバイス：モバイルですか？古い iPhone ですか？
• 使用可能なアセット形式（glTF、HDRI、テクスチャ）とファイルサイズの制約
• アクセシビリティ／視差効果を抑える設定の要件