Three.js

Build performant 3D browser apps and games with Three.js using modern ES module patterns (r150+). This file covers scene setup inline; physics, controllers, gameplay architecture, and deep topics live in references/.

Core principles:

1. Scene Graph First: everything added to scene renders. Use Group for hierarchical transforms (parent transforms affect children).
2. Primitives as building blocks: built-in geometries (Box, Sphere, Torus) cover most simple cases.
3. Animation as transformation: change position/rotation/scale over time in renderer.setAnimationLoop.
4. Performance through simplicity: fewer objects, fewer draw calls, reusable geometries/materials.
5. A scene is not a game: gameplay needs a fixed-timestep loop, a controller driven by input, collision, and a follow camera — see the Reference Files below before building one.

Prebuilt Modules — copy the hard parts, generate the rest

modules/ holds a small set of TypeScript files for the parts of a 3D game that are hard to get right and the same across games: framerate-independent smoothing + a deterministic PRNG (math.ts), Y-up orientation-frame helpers + a grounded character controller (character-movement.ts), and a Rapier kinematic character-collision resolver (kinematic-resolver.ts). Copy these into the project rather than re-deriving them — inverted axes, framerate-dependent smoothing, and mis-wired Rapier controllers are the classic ways this goes wrong.

Everything else — camera rigs, enemy waves, pathfinding, steering, minimaps, input schemes — is not prebuilt on purpose: it differs per game and is cheap to write, so generate it live against the references below. Read modules/summary.md before pulling anything in.