Threejs Syntax Geometries

threejs-syntax-geometries

Quick Reference

BufferGeometry: Core Properties

BufferGeometry: Key Methods

BufferAttribute: Constructor and Properties

import * as THREE from 'three';

new THREE.BufferAttribute(array: TypedArray, itemSize: number, normalized?: boolean)

Typed Convenience Classes

Usage Hints

Critical Warnings

NEVER forget attribute.needsUpdate = true after modifying BufferAttribute data via setX/setXY/setXYZ or direct array writes. Without this flag, changes will NOT reach the GPU.

NEVER assume boundingBox or boundingSphere are populated automatically. They are null until you explicitly call computeBoundingBox() / computeBoundingSphere().

ALWAYS call computeVertexNormals() after building custom geometry if you need lighting. Without normals, MeshStandardMaterial and other lit materials render black.

ALWAYS call geometry.dispose() when removing geometry from the scene permanently. Failing to dispose leaks GPU memory. The garbage collector does NOT free GPU-side buffers.

NEVER call translate(), rotateX(), scale(), or other in-place transform methods in an animation loop. These modify the actual vertex data permanently. Use mesh.position, mesh.rotation, and mesh.scale for runtime transforms.

ALWAYS set usage to DynamicDrawUsage BEFORE the first render if you plan to update attribute data every frame. Changing usage after initial upload has no effect on some GPU drivers.

NEVER forget instanceMatrix.needsUpdate = true after calling setMatrixAt() on InstancedMesh. Without this flag, all instances render at the origin.

Indexed vs Non-Indexed Geometry

ALWAYS use indexed geometry for smooth-shaded meshes with shared vertices. Use geometry.toNonIndexed() ONLY when you need per-face attributes (flat shading with unique normals).

All 21 Built-in Geometries

Primitives

Polyhedra

All accept (radius=1, detail=0). Detail controls subdivision level.

Path-Based

Utility

ExtrudeGeometry Options

Shape Class: 2D Path Drawing

import * as THREE from 'three';

const shape = new THREE.Shape();
shape.moveTo(x, y);                                    // Start new subpath
shape.lineTo(x, y);                                    // Straight line
shape.bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y);   // Cubic Bezier
shape.quadraticCurveTo(cpx, cpy, x, y);                // Quadratic Bezier
shape.splineThru(points);                               // Smooth spline through Vector2[]
shape.arc(aX, aY, radius, startAngle, endAngle, cw);   // Relative arc
shape.absarc(aX, aY, radius, startAngle, endAngle, cw); // Absolute arc

// Holes
const holePath = new THREE.Path();
holePath.absarc(0, 0, 0.5, 0, Math.PI * 2);
shape.holes.push(holePath);

Morph Targets

import * as THREE from 'three';

// Define morph target positions
const morphPositions = new Float32Array([/* ... */]);
geometry.morphAttributes.position = [
  new THREE.BufferAttribute(morphPositions, 3)
];

// Control on the mesh
mesh.morphTargetInfluences[0] = 0.5; // 50% blend toward morph target 0

// Named morph targets (from glTF)
mesh.morphTargetDictionary; // { "smile": 0, "frown": 1 }

Set geometry.morphTargetsRelative = true when morph data represents offsets rather than absolute positions.

InstancedMesh

import * as THREE from 'three';

const mesh = new THREE.InstancedMesh(geometry, material, count);

Performance Guidelines

Custom Per-Instance Attributes

import * as THREE from 'three';

const phases = new Float32Array(count);
for (let i = 0; i < count; i++) phases[i] = Math.random();
mesh.geometry.setAttribute('aPhase', new THREE.InstancedBufferAttribute(phases, 1));
// Access in vertex shader: attribute float aPhase;

Multi-Material with Groups

import * as THREE from 'three';

geometry.addGroup(0, 6, 0);    // First 6 indices -> material[0]
geometry.addGroup(6, 6, 1);    // Next 6 indices  -> material[1]
const mesh = new THREE.Mesh(geometry, [materialA, materialB]);

InterleavedBuffer

For optimal GPU cache performance on large meshes (10,000+ vertices):

import * as THREE from 'three';

const stride = 8; // 3 (position) + 3 (normal) + 2 (uv)
const buffer = new THREE.InterleavedBuffer(new Float32Array(vertexCount * stride), stride);

geometry.setAttribute('position', new THREE.InterleavedBufferAttribute(buffer, 3, 0));
geometry.setAttribute('normal',   new THREE.InterleavedBufferAttribute(buffer, 3, 3));
geometry.setAttribute('uv',       new THREE.InterleavedBufferAttribute(buffer, 2, 6));

ALWAYS use separate buffers when individual attributes are updated independently. Use interleaved buffers ONLY when all attributes are static or updated together.

Disposal Rules

• ALWAYS call geometry.dispose() when removing geometry from the scene permanently
• Shared geometries (used by multiple meshes): dispose ONLY after ALL meshes are removed
• Built-in geometries: dispose when the mesh using them is removed
• The JavaScript garbage collector does NOT free GPU-side vertex buffers

Reference Links

• references/methods.md — Complete API signatures for BufferGeometry, BufferAttribute, InstancedMesh
• references/examples.md — Working code examples for custom geometry, instancing, extrusion
• references/anti-patterns.md — What NOT to do with geometry in Three.js

Official Sources

• https://threejs.org/docs/#api/en/core/BufferGeometry
• https://threejs.org/docs/#api/en/core/BufferAttribute
• https://threejs.org/docs/#api/en/objects/InstancedMesh
• https://threejs.org/docs/#api/en/geometries/ExtrudeGeometry
• https://threejs.org/docs/#api/en/extras/core/Shape