ams-threejs-pro
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-11-07
- Stars
- ★ 0
- Forks
- 1
03 SKILL.md 正文
Three.js Pro
A practical guide to Three.js: the standard library for programmatic 3D in the browser — scene setup, cameras, lights, materials, the animation loop, asset loading, post-processing, and performance.
Overview
Three.js wraps WebGL in a scene-graph API: you compose scenes of meshes, lights, and cameras, and the renderer draws them each frame. It handles the GPU plumbing; you handle the 3D thinking (transforms, materials, lighting) and the performance budget. Pairs with the 3d-web-experiences skill (which covers art direction and asset pipeline); this one is the code-level reference.
When to use
- Programmatic 3D: scenes built in code rather than loaded models.
- Product viewers, configurators, data viz in 3D.
- Custom shaders (
ShaderMaterial,onBeforeCompile). - Post-processing pipelines (bloom, DOF, outlines).
- React integration via React Three Fiber (same concepts, declarative).
Core concepts
- Renderer / Scene / Camera.
WebGLRenderer({ antialias: true });Sceneholds everything;PerspectiveCamera(fov, aspect, near, far)(or Orthographic for isometric/data viz). - Mesh = Geometry + Material.
BoxGeometry,SphereGeometry,PlaneGeometry,BufferGeometry(custom); materials:MeshStandardMaterial(PBR),MeshBasicMaterial(unlit),ShaderMaterial(custom GLSL). - Transforms. Position/rotation/scale on
Object3D; groups for hierarchies. Remember: rotation order matters; use quaternions for interpolation. - Lights. Ambient/hemisphere (fill), Directional (sun + shadows), Point/Spot (local). Physical falloff in newer versions —
useLegacyLightsis gone; intensities are in physical units. - Shadows.
renderer.shadowMap.enabled = true; per-lightcastShadow+ per-meshcastShadow/receiveShadow. One shadow light for perf; tuneshadow.camerabounds tightly. - Loaders.
GLTFLoader(models),TextureLoader,RGBELoader(HDRI environments),DRACOLoader(compressed meshes). All async — design loading UX. - Animation loop.
renderer.setAnimationLoop(tick)(XR-compatible) withTHREE.Clockdelta; clamp delta to avoid tab-switch jumps. - Raycasting.
Raycasterfor picking (click/drag objects), with pointer NDC conversion. Essential for configurators. - Post-processing.
EffectComposer+ passes (RenderPass, UnrealBloomPass, OutputPass). Powerful but expensive — budget it.
Practical workflow
1. Boilerplate.
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
renderer.setSize(innerWidth, innerHeight);
renderer.shadowMap.enabled = true;
renderer.toneMapping = THREE.ACESFilmicToneMapping;
document.body.appendChild(renderer.domElement);
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(45, innerWidth / innerHeight, 0.1, 100);
camera.position.set(3, 2, 5);
const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true; // smooth; requires controls.update() in loop
2. Lights + environment.
scene.add(new THREE.HemisphereLight(0xffffff, 0x334455, 0.6));
const sun = new THREE.DirectionalLight(0xffffff, 2.5);
sun.position.set(5, 8, 3); sun.castShadow = true;
sun.shadow.mapSize.set(2048, 2048);
scene.add(sun);
// PBR reflections:
const pmrem = new THREE.PMREMGenerator(renderer);
scene.environment = pmrem.fromScene(new RoomEnvironment()).texture;
3. Animate.
const clock = new THREE.Clock();
renderer.setAnimationLoop(() => {
const dt = Math.min(clock.getDelta(), 0.05);
controls.update();
// update animations with dt
renderer.render(scene, camera);
});
4. Resize. Update camera aspect + renderer size on window resize (ResizeObserver on container).
5. Dispose. On teardown: traverse scene, geometry.dispose(), material.dispose(), textures too; renderer.dispose().
Common pitfalls
- Forgetting
controls.update(). Damping/auto-rotate silently do nothing without it in the loop. - Shadow camera too big. Default shadow camera covers a huge area → blurry shadows. Tighten
left/right/top/bottomto the scene's bounds. - No tone mapping / wrong color space. Washed-out or oversaturated renders.
ACESFilmicToneMapping+outputColorSpace = SRGBColorSpace(default in recent versions — verify). - Leaking GPU resources. SPA navigation between 3D views without dispose = VRAM leak → crash. Dispose geometries/materials/textures/render targets.
- Pixel ratio uncapped.
setPixelRatio(devicePixelRatio)on 3x displays = 9x fill cost. Cap at 2, lower for heavy scenes. - Z-fighting. Coplanar geometry flickers; use
polygonOffsetor small separations. - Blocking on load. Awaiting all assets before first frame = long blank. Progressive: show scene shell, stream assets with progress.
- Raycast on every mousemove against everything. Expensive with many meshes. Throttle, raycast against a curated pick-list, or use bounding-sphere prechecks.
- Version API drift. Three.js moves fast (lights physical units, color space defaults). Pin the version; read migration notes on upgrade.
04 同仓库更多 Skills
web-scrape
Turn web pages into LLM-ready markdown via the Firecrawl API (renders JS, anti-bot handling). Use when browser_open/fetch fails on JS-heavy pages, or when you need clean markdown/structured extraction from a site. Requires FIRECRAWL_API_KEY.
design-taste-frontend
tasteskill v2, the anti-slop frontend skill. Art direction for websites, distilled from a study of 247 curated gallery sites (One Page Love, Awwwards Sites of the Day). Deals researched directions (idea, composition, type, palette, photographs, section blueprints) from a library, enforces a strict no-slop house style with a real-browser inspector, and runs a look-and-fix loop on screenshots. Use this whenever you build, design, redesign, restyle, polish or review a landing page, marketing site, portfolio, product page, one-pager, hero or any public-facing web page, in any stack (HTML/CSS, React, Next.js, Vue, Svelte, Astro, Tailwind) — also when the user says a page looks generic, templated, "AI-made", sloppy, or asks to make it look designed, premium, award-level or less like every other site. Not for dashboards or app screens.
test-driven-development
Use when implementing any feature or bugfix, before writing implementation code
systematic-debugging
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
requesting-code-review
Use when completing tasks, implementing major features, or before merging to verify work meets requirements
brainstorming
You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).