# Facet

> Facet is a copy-paste registry of production-ready React Three Fiber components. Components are installed as source files into your project. No runtime dependency, no lock-in.

## Install

```bash
npx facet3d init
npx facet3d add <name>
```

## Usage

Components render inside a react-three-fiber Canvas:

```tsx
import { Canvas } from '@react-three/fiber'
import { HeroBlob } from '@/components/facet/hero-blob'

export default function Page() {
  return (
    <Canvas camera={{ position: [0, 0, 5] }}>
      <ambientLight intensity={0.5} />
      <HeroBlob color="#a3e635" speed={2} />
    </Canvas>
  )
}
```

## Components

### hero-blob

Hero Blob: Morphing distortion sphere: the classic 3D hero centerpiece.

Props:
- color: color = "#a3e635"
- speed: number (0–10) = 2
- distort: number (0–1) = 0.4
- radius: number (0.5–3) = 1.5
- wireframe: boolean = false

Install: `npx facet3d add hero-blob`

### particle-field

Particle Field: Interactive particle cloud that reacts to the cursor.

Props:
- count: number (100–10000) = 3000
- color: color = "#a3e635"
- radius: number (1–10) = 4
- size: number (0.005–0.1) = 0.02
- speed: number (0–1) = 0.1

Install: `npx facet3d add particle-field`

### image-particles

Image Particles: Particles that assemble into any text or image, and scatter under the cursor.

Props:
- text: text = "FACET"
- color: color = "#a3e635"
- particleSize: number (0.01–0.2) = 0.05
- density: number (1–8) = 3
- scatter: number (0–5) = 1.5

Install: `npx facet3d add image-particles`

### galaxy

Galaxy: Procedural spiral galaxy with tens of thousands of shader-driven stars.

Props:
- count: number (2000–50000) = 20000
- branches: number (2–10) = 3
- spin: number (-3–3) = 1
- radius: number (1–20) = 8
- randomness: number (0–2) = 0.4
- insideColor: color = "#ff6030"
- outsideColor: color = "#1b3984"

Install: `npx facet3d add galaxy`

### globe-arcs

Globe Arcs: Interactive dotted globe with animated connection arcs: the infra-startup staple.

Props:
- color: color = "#a3e635"
- arcColor: color = "#f97316"
- arcCount: number (0–24) = 10
- speed: number (0–2) = 0.3

Install: `npx facet3d add globe-arcs`

### aurora

Aurora: Animated aurora gradient shader: the landing-page background everyone wants.

Props:
- colorA: color = "#a3e635"
- colorB: color = "#22d3ee"
- colorC: color = "#f97316"
- speed: number (0–3) = 0.6
- complexity: number (1–8) = 4

Install: `npx facet3d add aurora`

### ripple-plane

Ripple Plane: Touch-responsive water surface. Move your cursor and watch it ripple.

Props:
- color: color = "#38bdf8"
- waveHeight: number (0–1) = 0.35
- speed: number (0–3) = 1

Install: `npx facet3d add ripple-plane`

### node-network

Node Network: 3D plexus network of drifting, connected nodes, built for AI landing pages.

Props:
- nodeCount: number (10–300) = 120
- color: color = "#a3e635"
- maxDistance: number (0.5–5) = 2
- speed: number (0–2) = 0.4

Install: `npx facet3d add node-network`

### cursor-trail

Cursor Trail: A fluid ribbon of light that follows the cursor.

Props:
- color: color = "#22d3ee"
- length: number (10–200) = 60
- width: number (1–12) = 4

Install: `npx facet3d add cursor-trail`

### audio-visualizer

Audio Visualizer: Audio-reactive frequency rings: microphone or built-in simulation.

Props:
- color: color = "#a3e635"
- bars: number (16–128) = 64
- sensitivity: number (0.5–5) = 2
- mode: one of simulated|microphone = "simulated"

Install: `npx facet3d add audio-visualizer`

### floating-shapes

Floating Shapes: Drifting geometric primitives for ambient backgrounds.

Props:
- count: number (1–30) = 12
- speed: number (0–5) = 1
- spread: number (2–20) = 8

Install: `npx facet3d add floating-shapes`

### wave-grid

Wave Grid: Shader-driven undulating wireframe terrain.

Props:
- color: color = "#22d3ee"
- speed: number (0–5) = 1
- amplitude: number (0–2) = 0.6
- frequency: number (0.5–6) = 2

Install: `npx facet3d add wave-grid`

### text-3d

3D Text: Extruded 3D typography with environment-lit materials.

Props:
- text: text = "FACET"
- size: number (0.2–3) = 0.8
- color: color = "#ffffff"
- bevelSize: number (0–0.1) = 0.02
- floatIntensity: number (0–3) = 0.6

Install: `npx facet3d add text-3d`

### model-viewer

Model Viewer: Drop-in GLTF model viewer with staging and orbit controls.

Props:
- url: text = "https://threejs.org/examples/models/gltf/DamagedHelmet/glTF/DamagedHelmet.gltf"
- autoRotate: boolean = true
- autoRotateSpeed: number (0–10) = 1.5
- environment: one of city|sunset|dawn|night|warehouse|forest|apartment|studio|park|lobby = "city"
- enableZoom: boolean = false

Install: `npx facet3d add model-viewer`

### holo-card

Holo Card: Holographic fresnel card with an iridescent sheen.

Props:
- colorA: color = "#a3e635"
- colorB: color = "#f97316"
- intensity: number (0–3) = 1.2
- speed: number (0–5) = 1

Install: `npx facet3d add holo-card`

### scroll-camera

Scroll Camera: Scroll-driven camera flythrough scene.

Props:
- pages: number (1–6) = 3
- color: color = "#a3e635"
- damping: number (0.05–1) = 0.2

Install: `npx facet3d add scroll-camera`

### glass-prism

Glass Prism: Cinematic glass dispersion crystal with real refraction and chromatic aberration.

Props:
- shape: one of prism|torusknot|icosahedron = "prism"
- speed: number (0–2) = 0.4
- ior: number (1–2.5) = 1.5
- chromaticAberration: number (0–1) = 0.3
- tint: color = "#a3e635"
- floatIntensity: number (0–3) = 1
- distortion: number (0–1) = 0.2
- parallax: boolean = true

Install: `npx facet3d add glass-prism`

### face-puppet

Face Puppet: Webcam face-tracked spirit head that mirrors your expressions, with mouse-follow fallback.

Props:
- color: color = "#a3e635"
- smoothing: number (0.05–3) = 1
- trackingSensitivity: number (0–3) = 1
- followMouse: boolean = true
- showPreview: boolean = false
- pupilScale: number (0.5–2) = 1
- floatIntensity: number (0–3) = 1

Install: `npx facet3d add face-puppet`

### god-rays

God Rays: Volumetric light shafts with drifting dust: cinematic background glow, zero post-processing.

Props:
- color: color = "#fde68a"
- intensity: number (0–3) = 1
- rayCount: number (1–32) = 12
- density: number (0–1) = 0.7
- speed: number (0–3) = 1
- flicker: number (0–1) = 0.35
- dust: boolean = true

Install: `npx facet3d add god-rays`

### portal

Portal: A standing portal that renders another world live, with true perspective parallax.

Props:
- theme: one of galaxy|ocean = "galaxy"
- frameColor: color = "#a3e635"
- glowIntensity: number (0–3) = 1
- swirlSpeed: number (0–3) = 1
- wisps: boolean = true
- float: boolean = true
- size: number (0.5–2) = 1

Install: `npx facet3d add portal`

### silk-cloth

Silk Cloth: Silk banner billowing in gusting wind, with smooth pointer push and drag.

Props:
- color: color = "#a3e635"
- windStrength: number (0–3) = 1
- gustiness: number (0–3) = 1
- segments: number (8–64) = 36
- pointerRadius: number (0.1–3) = 0.9
- pointerStrength: number (0–3) = 1
- pinMode: one of top|corners = "top"
- sheen: number (0–2) = 1

Install: `npx facet3d add silk-cloth`

### lightning-arcs

Lightning Arcs: Branching electric arcs with a white-hot core, strike flicker, and pointer chasing.

Props:
- color: color = "#a3e635"
- branches: number (1–4) = 3
- strikeRate: number (0.1–5) = 1.5
- thickness: number (0.01–0.2) = 0.04
- flicker: number (0–1) = 0.7
- followPointer: boolean = false
- glowIntensity: number (0–3) = 1.6

Install: `npx facet3d add lightning-arcs`

### character-controller

Character Controller: Third-person character controller: WASD movement, jumping, and a collision-aware camera.

Props:
- color: color = "#a3e635"
- speed: number (1–20) = 6
- jumpForce: number (1–20) = 8
- cameraDistance: number (2–12) = 6

Install: `npx facet3d add character-controller`

### procedural-terrain

Procedural Terrain: Seeded noise terrain with elevation biomes, from sand to snow.

Props:
- seed: number (1–100) = 42
- size: number (10–100) = 40
- maxHeight: number (1–20) = 6
- roughness: number (0.1–2) = 0.8
- wireframe: boolean = false

Install: `npx facet3d add procedural-terrain`

### ocean

Ocean: Gerstner-wave water with fresnel, crest foam, and sun glint.

Props:
- color: color = "#075985"
- waveHeight: number (0–3) = 0.8
- choppiness: number (0–3) = 1
- speed: number (0–3) = 1

Install: `npx facet3d add ocean`

### vfx-burst

VFX Burst: GPU particle bursts with game-ready presets: explosion, fire, smoke, magic.

Props:
- preset: one of explosion|fire|smoke|magic = "explosion"
- color: color = "#f97316"
- count: number (100–3000) = 800
- size: number (0.01–0.3) = 0.08
- auto: boolean = true

Install: `npx facet3d add vfx-burst`

### day-night-sky

Day/Night Sky: Procedural sky dome with a full sun cycle, stars, and drifting clouds.

Props:
- timeOfDay: number (0–24) = 10
- speed: number (0–5) = 0.5
- cloudCover: number (0–1) = 0.4

Install: `npx facet3d add day-night-sky`

### grass-field

Grass Field: Tens of thousands of instanced grass blades swaying in the wind.

Props:
- count: number (5000–100000) = 30000
- color: color = "#65a30d"
- windStrength: number (0–3) = 1
- windSpeed: number (0–5) = 1.5
- area: number (5–50) = 20

Install: `npx facet3d add grass-field`

### avatar-maker

Avatar Maker: Design a stylized 3D character with expressions and export it as a .glb for your game.

Props:
- skinColor: color = "#f2c89b"
- hairColor: color = "#3f3f46"
- hairStyle: one of bowl|buzz|spiky|ponytail|messy = "bowl"
- shirtColor: color = "#a3e635"
- pantsColor: color = "#262626"
- accessory: one of none|glasses|cap = "none"
- expression: one of happy|neutral|surprised|sleepy = "happy"
- headSize: number (0.8–1.4) = 1.1
- height: number (0.8–1.3) = 1
- animate: boolean = true

Install: `npx facet3d add avatar-maker`

### drift-car

Drift Car: Arcade drift car with raycast suspension, handbrake slides, smoke, and skid marks.

Props:
- carColor: color = "#a3e635"
- acceleration: number (5–40) = 18
- topSpeed: number (5–50) = 26
- driftFactor: number (0–1) = 0.6
- cameraLag: number (1–20) = 6
- fovKick: boolean = true
- smoke: boolean = true
- skidmarks: boolean = true

Install: `npx facet3d add drift-car`

## CLI

- `npx facet3d init`: set up the components directory in your project
- `npx facet3d add <name>`: copy a component into your project as source
- `npx facet3d list`: list all available components
- `npx facet3d docs <name>`: print usage docs for a component

## MCP server

AI agents can also use the `@facet3d/mcp` MCP server (tools: facet_list, facet_docs, facet_source, facet_add). Config: {"mcpServers": {"facet": {"command": "npx", "args": ["-y", "@facet3d/mcp"]}}}