Geometry & materials

 Mesh (Object3D: transform, layers, castShadow…)
 ├── geometry: BufferGeometry
 │     attributes: position (vec3), normal (vec3), uv (vec2),
 │                 color, tangent, uv1…uv3, skinIndex/Weight
 │     index?:     Uint16/Uint32 BufferAttribute
 │     groups:     [{ start, count, materialIndex }]
 │     boundingBox / boundingSphere (culling, raycasting)
 └── material: Material | Material[]  (one per group)
       → compiled to a shader program, cached by its settings

import {
  BufferAttribute, BufferGeometry, DynamicDrawUsage,
} from "three";
 
const geo = new BufferGeometry();
const pos = new BufferAttribute(
  new Float32Array(1000 * 3), 3,
);
pos.setUsage(DynamicDrawUsage); // updated often
geo.setAttribute("position", pos);
 
// later: change a vertex, then flag the upload
pos.setXYZ(42, 1, 2, 3);
pos.addUpdateRange(42 * 3, 3); // upload only this slice
pos.needsUpdate = true;
geo.computeBoundingSphere();   // keep culling correct

import { Shape, ExtrudeGeometry } from "three";
 
const s = new Shape();
s.moveTo(0, 0).lineTo(2, 0).lineTo(2, 1)
  .quadraticCurveTo(1, 2, 0, 1).closePath();
const hole = new Shape()
  .absarc(1, 0.8, 0.25, 0, Math.PI * 2);
s.holes.push(hole);
const geo = new ExtrudeGeometry(s, {
  depth: 0.3, bevelEnabled: true, bevelSize: 0.03,
});
geo.center();

// A quad from 4 shared vertices and 2 indexed triangles
const geo = new BufferGeometry();
geo.setAttribute("position", new Float32BufferAttribute([
  -1, -1, 0,   1, -1, 0,   1, 1, 0,   -1, 1, 0,
], 3));
geo.setAttribute("uv", new Float32BufferAttribute([
  0, 0,   1, 0,   1, 1,   0, 1,
], 2));
geo.setIndex([0, 1, 2,   0, 2, 3]); // CCW = front
geo.computeVertexNormals();          // +Z here

import { mergeGeometries } from
  "three/addons/utils/BufferGeometryUtils.js";
 
const parts: BufferGeometry[] = [];
for (const m of rocks) {
  m.updateWorldMatrix(true, false);
  parts.push(m.geometry.clone().applyMatrix4(m.matrixWorld));
}
const merged = mergeGeometries(parts, false);
// null if attribute sets or index usage differ

import {
  Color, DynamicDrawUsage, InstancedMesh, Matrix4,
  Object3D,
} from "three";
 
const COUNT = 5_000;
const trees = new InstancedMesh(geo, mat, COUNT);
trees.instanceMatrix.setUsage(DynamicDrawUsage);
 
const dummy = new Object3D(); // reusable PRS helper
const c = new Color();
for (let i = 0; i < COUNT; i++) {
  dummy.position.set(rand(-50, 50), 0, rand(-50, 50));
  dummy.rotation.y = Math.random() * Math.PI * 2;
  dummy.scale.setScalar(rand(0.7, 1.3));
  dummy.updateMatrix();
  trees.setMatrixAt(i, dummy.matrix);
  trees.setColorAt(i, c.setHSL(0.3, 0.5, rand(.3, .6)));
}
trees.instanceMatrix.needsUpdate = true;
trees.instanceColor!.needsUpdate = true;
trees.computeBoundingSphere(); // culling + raycasting
scene.add(trees);

import { BatchedMesh, Matrix4 } from "three";
 
// (maxInstances, maxVertices, maxIndices, material)
const batch = new BatchedMesh(1000, 50_000, 100_000, mat);
const boxId = batch.addGeometry(boxGeo);
const ballId = batch.addGeometry(sphereGeo);
 
const m = new Matrix4();
for (let i = 0; i < 500; i++) {
  const inst = batch.addInstance(i % 2 ? boxId : ballId);
  m.makeTranslation(i % 25, 0, Math.floor(i / 25));
  batch.setMatrixAt(inst, m);
}
scene.add(batch);

const tl = new TextureLoader();
const [albedo, orm, normal] = await Promise.all([
  tl.loadAsync("/crate/albedo.jpg"),
  tl.loadAsync("/crate/orm.jpg"),
  tl.loadAsync("/crate/normal.png"),
]);
albedo.colorSpace = SRGBColorSpace; // only color maps
const mat = new MeshStandardMaterial({
  map: albedo,
  normalMap: normal,
  aoMap: orm, roughnessMap: orm, metalnessMap: orm,
  roughness: 1, metalness: 1, // multipliers: keep 1
});

const tex = await new TextureLoader().loadAsync(url);
tex.colorSpace = SRGBColorSpace;
tex.wrapS = tex.wrapT = RepeatWrapping;
tex.repeat.set(4, 4);          // tile 4×4
tex.anisotropy =               // sharp at grazing angles
  renderer.capabilities.getMaxAnisotropy();

import { KTX2Loader } from
  "three/addons/loaders/KTX2Loader.js";
 
const ktx2 = new KTX2Loader()
  // serve a copy of three/examples/jsm/libs/basis/
  .setTranscoderPath("/basis/")
  .detectSupport(renderer);
const tex = await ktx2.loadAsync("/textures/wood.ktx2");
tex.colorSpace = SRGBColorSpace;

const N = 20_000;
const pos = new Float32Array(N * 3);
for (let i = 0; i < pos.length; i++) {
  pos[i] = (Math.random() - 0.5) * 20;
}
const geo = new BufferGeometry();
geo.setAttribute("position", new BufferAttribute(pos, 3));
 
const stars = new Points(geo, new PointsMaterial({
  size: 0.05,              // world units when attenuated
  sizeAttenuation: true,   // smaller with distance
  color: "#cfe3ff",
  map: dotTexture,         // round sprite, not squares
  alphaTest: 0.5, // or transparent + depthWrite: false
}));
scene.add(stars);

const pts = curve.getPoints(100); // e.g. CatmullRomCurve3
const line = new Line(
  new BufferGeometry().setFromPoints(pts),
  new LineDashedMaterial({ dashSize: 0.2, gapSize: 0.1 }),
);
line.computeLineDistances(); // required for dashes

import { Line2 } from "three/addons/lines/Line2.js";
import { LineGeometry } from
  "three/addons/lines/LineGeometry.js";
import { LineMaterial } from
  "three/addons/lines/LineMaterial.js";
 
const g = new LineGeometry().setFromPoints(pts);
const fat = new Line2(g, new LineMaterial({
  color: 0xffaa00,
  linewidth: 4,        // pixels (worldUnits: false)
}));
fat.computeLineDistances();

const label = new Sprite(new SpriteMaterial({
  map: labelTexture,        // e.g. a CanvasTexture
  sizeAttenuation: true,    // false: constant screen size
  depthTest: false,         // stay on top
}));
label.scale.set(2, 0.5, 1); // world size; match aspect
label.center.set(0.5, 0);   // anchor: bottom middle
label.position.set(0, 2, 0);
label.renderOrder = 10;

import {
  Color, ConeGeometry, InstancedMesh,
  MeshStandardMaterial, Object3D,
} from "three";
 
export function forest(count: number, size = 80) {
  const geo = new ConeGeometry(0.6, 2, 8).translate(0, 1, 0);
  const mat = new MeshStandardMaterial({ roughness: 0.9 });
  const mesh = new InstancedMesh(geo, mat, count);
  const d = new Object3D();
  const c = new Color();
  for (let i = 0; i < count; i++) {
    d.position.set(
      (Math.random() - 0.5) * size, 0,
      (Math.random() - 0.5) * size,
    );
    d.scale.setScalar(0.6 + Math.random() * 0.8);
    d.updateMatrix();
    mesh.setMatrixAt(i, d.matrix);
    mesh.setColorAt(i, c.setHSL(0.3, 0.45,
      0.25 + Math.random() * 0.2));
  }
  mesh.computeBoundingSphere();
  mesh.castShadow = true;
  return mesh;
}

import { Mesh } from "three";
import type { BufferGeometry, Material, Object3D }
  from "three";
import { mergeGeometries } from
  "three/addons/utils/BufferGeometryUtils.js";
 
export function mergeByMaterial(root: Object3D): Mesh[] {
  const buckets = new Map<Material, BufferGeometry[]>();
  root.updateMatrixWorld(true);
  root.traverse((o) => {
    const m = o as Mesh;
    if (!m.isMesh || Array.isArray(m.material)) return;
    const g = m.geometry.clone().applyMatrix4(m.matrixWorld);
    const list = buckets.get(m.material) ?? [];
    list.push(g);
    buckets.set(m.material, list);
  });
  return [...buckets].flatMap(([mat, geos]) => {
    const merged = mergeGeometries(geos);
    geos.forEach((g) => g.dispose());
    return merged ? [new Mesh(merged, mat)] : [];
  });
}

import {
  MeshStandardMaterial, RepeatWrapping, SRGBColorSpace,
  TextureLoader,
} from "three";
import type { Texture, WebGLRenderer } from "three";
 
export async function pbr(
  dir: string, renderer: WebGLRenderer, repeat = 1,
): Promise<MeshStandardMaterial> {
  const tl = new TextureLoader();
  const load = (f: string) => tl.loadAsync(`${dir}/${f}`);
  const [map, normalMap, orm] = await Promise.all([
    load("albedo.jpg"), load("normal.png"), load("orm.jpg"),
  ]);
  map.colorSpace = SRGBColorSpace;
  const aniso = renderer.capabilities.getMaxAnisotropy();
  for (const t of [map, normalMap, orm] as Texture[]) {
    t.wrapS = t.wrapT = RepeatWrapping;
    t.repeat.set(repeat, repeat);
    t.anisotropy = aniso;
  }
  return new MeshStandardMaterial({
    map, normalMap,
    aoMap: orm, roughnessMap: orm, metalnessMap: orm,
  });
}

import {
  CanvasTexture, SRGBColorSpace, Sprite, SpriteMaterial,
} from "three";
 
export function textSprite(text: string, px = 64): Sprite {
  const c = document.createElement("canvas");
  const ctx = c.getContext("2d")!;
  ctx.font = `600 ${px}px system-ui`;
  c.width = Math.ceil(ctx.measureText(text).width) + 16;
  c.height = px * 1.4;
  ctx.font = `600 ${px}px system-ui`; // reset by resize
  ctx.fillStyle = "white";
  ctx.textBaseline = "middle";
  ctx.fillText(text, 8, c.height / 2);
  const tex = new CanvasTexture(c);
  tex.colorSpace = SRGBColorSpace;
  const s = new Sprite(new SpriteMaterial({
    map: tex, transparent: true, toneMapped: false,
  }));
  s.scale.set(c.width / c.height, 1, 1).multiplyScalar(0.3);
  return s;
}

const geo = new PlaneGeometry(4, 4, 64, 64);
const pos = geo.attributes.position as BufferAttribute;
const base = Float32Array.from(pos.array);
 
function wave(t: number): void {
  for (let i = 0; i < pos.count; i++) {
    const x = base[i * 3];
    const y = base[i * 3 + 1];
    pos.setZ(i, Math.sin(x * 2 + t) * Math.cos(y * 2 + t)
      * 0.15);
  }
  pos.needsUpdate = true;
  geo.computeVertexNormals(); // lighting follows shape
}