AGENT SKILL

ams-threejs-pro

暂无简介

License 许可
MIT
所属仓库
TanNhatCMS/jarvis
最近更新
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 }); Scene holds 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 — useLegacyLights is gone; intensities are in physical units.
  • Shadows. renderer.shadowMap.enabled = true; per-light castShadow + per-mesh castShadow/receiveShadow. One shadow light for perf; tune shadow.camera bounds tightly.
  • Loaders. GLTFLoader (models), TextureLoader, RGBELoader (HDRI environments), DRACOLoader (compressed meshes). All async — design loading UX.
  • Animation loop. renderer.setAnimationLoop(tick) (XR-compatible) with THREE.Clock delta; clamp delta to avoid tab-switch jumps.
  • Raycasting. Raycaster for 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/bottom to 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 polygonOffset or 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

TanNhatCMS
TanNhatCMS/jarvis

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.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

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.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

test-driven-development

Use when implementing any feature or bugfix, before writing implementation code

★ 0
TanNhatCMS
TanNhatCMS/jarvis

systematic-debugging

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

★ 0
TanNhatCMS
TanNhatCMS/jarvis

requesting-code-review

Use when completing tasks, implementing major features, or before merging to verify work meets requirements

★ 0
TanNhatCMS
TanNhatCMS/jarvis

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).

★ 0