Fundamentals

npm i three
npm i -D @types/three   # keep its minor = three's minor

import * as THREE from "three";
import { Mesh, Scene, WebGLRenderer } from "three";
import { OrbitControls } from
  "three/addons/controls/OrbitControls.js";
import { GLTFLoader } from
  "three/addons/loaders/GLTFLoader.js";

<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@0.186.1/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.186.1/examples/jsm/"
  }
}
</script>
<script type="module" src="./main.js"></script>

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "strict": true,
    "skipLibCheck": true
  }
}

import { BoxGeometry, Mesh, MeshStandardMaterial }
  from "three";
import type { Object3D } from "three";
 
type Box = Mesh<BoxGeometry, MeshStandardMaterial>;
const box: Box = new Mesh(
  new BoxGeometry(1, 1, 1),
  new MeshStandardMaterial({ color: "tomato" }),
);
box.material.roughness = 0.4; // typed, no cast
 
function isMesh(o: Object3D): o is Mesh {
  return (o as Mesh).isMesh === true;
}

 Scene (root Object3D)
 ├── Mesh  = BufferGeometry + Material
 ├── Group ── Mesh, Mesh …
 ├── Light(s)
 └── (camera may be a child too)
          │
 renderer.render(scene, camera)
          │  per frame: update world matrices → frustum cull
          │  → sort opaque front-to-back, transparent back-to-front
          │  → compile/cache programs → draw calls
          ▼
 <canvas> drawing buffer  (tone mapping + sRGB on output)

const canvas = document.querySelector<HTMLCanvasElement>(
  "#app",
)!;
const renderer = new WebGLRenderer({
  canvas,
  antialias: true,                // MSAA on the canvas
  powerPreference: "high-performance",
});
const scene = new Scene();
scene.background = new Color(0x202025);
 
const camera = new PerspectiveCamera(
  50,                              // vertical fov, degrees
  canvas.clientWidth / canvas.clientHeight,
  0.1,                             // near
  100,                             // far
);
camera.position.set(0, 1.5, 4);
camera.lookAt(0, 0, 0);

import { Timer } from "three"; // core since r179
 
const timer = new Timer();
timer.connect(document); // no giant delta after tab switch
 
renderer.setAnimationLoop((time: DOMHighResTimeStamp) => {
  timer.update(time);
  const dt = timer.getDelta();  // s since last update
  const t = timer.getElapsed(); // s, total
  cube.rotation.y += dt * 0.8;  // frame-rate independent
  cube.position.y = Math.sin(t) * 0.25;
  renderer.render(scene, camera);
});

renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
 
function resize(): void {
  const w = canvas.clientWidth;
  const h = canvas.clientHeight;
  renderer.setSize(w, h, false); // false: leave CSS alone
  camera.aspect = w / h;
  camera.updateProjectionMatrix(); // required after edits
}

// position, rotation, scale are readonly references:
// mutate them, never reassign
mesh.position.set(1, 0, -2);
mesh.rotation.set(0, Math.PI / 4, 0);
mesh.scale.setScalar(0.5);
 
// quaternion from axis-angle, then slerp toward it
const target = new Quaternion().setFromAxisAngle(
  new Vector3(0, 1, 0), Math.PI,
);
mesh.quaternion.slerp(target, 1 - Math.exp(-6 * dt));

const pivot = new Group(); // empty transform node
scene.add(pivot);
pivot.add(moon);           // moon now orbits with pivot
moon.position.x = 3;       // local: 3 from pivot
 
pivot.remove(moon);        // or moon.removeFromParent()
other.attach(moon);        // re-parent, keep world pose
scene.clear();             // remove all children
 
scene.traverse((o) => { o.castShadow = true; });
scene.traverseVisible(cb); // skips hidden branches
obj.traverseAncestors(cb);
scene.getObjectByName("Wheel_FL");
scene.getObjectsByProperty("isLight", true);

// static scenery: compute once, then stop per-frame work
building.updateMatrix();
building.matrixAutoUpdate = false;
// after moving it later: building.updateMatrix()
 
// drive a transform by matrix instead of PRS
obj.matrixAutoUpdate = false;
obj.matrix.compose(pos, quat, scl);
obj.matrixWorldNeedsUpdate = true;

// orthographic: `viewH` world units visible vertically
const viewH = 10;
const aspect = canvas.clientWidth / canvas.clientHeight;
const ortho = new OrthographicCamera(
  (-viewH * aspect) / 2, (viewH * aspect) / 2,
  viewH / 2, -viewH / 2,
  0.1, 100,
);

import { OrbitControls } from
  "three/addons/controls/OrbitControls.js";
 
const controls = new OrbitControls(camera, canvas);
controls.target.set(0, 1, 0);
controls.enableDamping = true;   // inertia
controls.dampingFactor = 0.08;
controls.minDistance = 1;
controls.maxDistance = 20;
controls.maxPolarAngle = Math.PI / 2; // not below ground
controls.update();               // apply target now
 
renderer.setAnimationLoop(() => {
  controls.update(); // required with damping/autoRotate
  renderer.render(scene, camera);
});

scene.add(new AxesHelper(1), new GridHelper(10, 10));
console.table(renderer.info.render);  // calls, triangles
console.log(renderer.info.memory);    // geometries, textures
console.log(renderer.info.programs?.length); // shaders

 hex / CSS colors ──(treated as sRGB)──┐
 color textures (map, emissiveMap)     ├─► linear working space
   texture.colorSpace = SRGBColorSpace ─┘       │ lighting, blending
 data textures (normal, roughness…)             ▼
   colorSpace = NoColorSpace (default)   tone mapping
                                                │
                           renderer.outputColorSpace = SRGBColorSpace
                                                ▼
                                             canvas

const tex = await new TextureLoader().loadAsync(
  "/albedo.jpg",
);
tex.colorSpace = SRGBColorSpace;  // color data
const nrm = await new TextureLoader().loadAsync(
  "/normal.png",
); // data: leave NoColorSpace

import {
  BoxGeometry, Color, DirectionalLight, HemisphereLight,
  Mesh, MeshStandardMaterial, PerspectiveCamera, Scene,
  Timer, WebGLRenderer,
} from "three";
 
const canvas = document.querySelector("canvas")!;
const renderer = new WebGLRenderer({
  canvas, antialias: true,
});
renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
renderer.setSize(innerWidth, innerHeight, false);
 
const scene = new Scene();
scene.background = new Color("#1d1f24");
const camera = new PerspectiveCamera(
  50, innerWidth / innerHeight, 0.1, 50,
);
camera.position.set(2, 1.5, 3);
camera.lookAt(0, 0, 0);
 
scene.add(new HemisphereLight("#dfe8ff", "#3a2e24", 1));
const sun = new DirectionalLight("#ffffff", 2.5);
sun.position.set(3, 5, 2);
scene.add(sun);
 
const cube = new Mesh(
  new BoxGeometry(1, 1, 1),
  new MeshStandardMaterial({ color: "#4f8cff" }),
);
scene.add(cube);
 
const timer = new Timer();
timer.connect(document);
renderer.setAnimationLoop((t) => {
  timer.update(t);
  cube.rotation.y += timer.getDelta();
  renderer.render(scene, camera);
});

import type { PerspectiveCamera, WebGLRenderer }
  from "three";
 
export function autoResize(
  renderer: WebGLRenderer,
  camera: PerspectiveCamera,
  maxDpr = 2,
): () => void {
  const canvas = renderer.domElement;
  const ro = new ResizeObserver(([entry]) => {
    const { width, height } = entry.contentRect;
    if (width === 0 || height === 0) return;
    renderer.setPixelRatio(
      Math.min(devicePixelRatio, maxDpr),
    );
    renderer.setSize(width, height, false);
    camera.aspect = width / height;
    camera.updateProjectionMatrix();
  });
  ro.observe(canvas);
  return () => ro.disconnect();
}

import type {
  BufferGeometry, Material, Object3D, Texture,
} from "three";
 
type Drawable = Object3D & {
  geometry: BufferGeometry;
  material: Material | Material[];
};
const isDrawable = (o: Object3D): o is Drawable =>
  "geometry" in o && "material" in o;
 
function disposeMaterial(m: Material): void {
  for (const value of Object.values(m)) {
    const tex = value as Texture | null;
    if (tex?.isTexture) tex.dispose();
  }
  m.dispose();
}
 
export function disposeTree(root: Object3D): void {
  root.traverse((o) => {
    if (!isDrawable(o)) return;
    o.geometry.dispose();
    const mats = Array.isArray(o.material)
      ? o.material : [o.material];
    mats.forEach(disposeMaterial);
  });
  root.removeFromParent();
}

let queued = false;
 
function requestRender(): void {
  if (queued) return;
  queued = true;
  requestAnimationFrame(() => {
    queued = false;
    // damping emits "change" again until it settles
    controls.update();
    renderer.render(scene, camera);
  });
}
 
controls.addEventListener("change", requestRender);
new ResizeObserver(() => {
  resize();          // from "Resizing & pixel ratio"
  requestRender();
}).observe(canvas);
requestRender();     // first frame
// also call it after loading assets or changing materials

import { Box3, Sphere, Vector3 } from "three";
import type { Object3D, PerspectiveCamera } from "three";
 
export function frame(
  obj: Object3D, cam: PerspectiveCamera, pad = 1.2,
): Vector3 {
  const sphere = new Box3()
    .setFromObject(obj)
    .getBoundingSphere(new Sphere());
  const fov = (cam.fov * Math.PI) / 180;
  const dist = (sphere.radius * pad) / Math.sin(fov / 2);
  const dir = new Vector3(1, 0.6, 1).normalize();
  cam.position.copy(sphere.center)
    .addScaledVector(dir, dist);
  cam.near = dist / 100;
  cam.far = dist * 100;
  cam.updateProjectionMatrix();
  cam.lookAt(sphere.center);
  return sphere.center; // use as controls.target
}