visual-fx-3d

Files (3)

• CATALOG.md
• RECIPES.md
• SKILL.md

SKILL.md (first lines)

# Visual FX & 3D Spatial Materials ([`pmndrs/react-three-fiber`](https://github.com/pmndrs/react-three-fiber) Suite)

The house engine for high-end modern 3D spatial craft: declarative 3D scene graphs, glTF/GLB product models, tactile spring-damped tilt physics, 3D mesh transmission materials, cinematic post-processing, and real-time rigid body physics.

> **Architecture Boundaries:** 
> - **2D UI Frosted Glass & Live-DOM Refraction:** Use [`.agents/skills/apple-glass`](../apple-glass/SKILL.md) (hardware-composited CSS and SDF displacement maps). Do NOT use `visual-fx-3d` or `MeshTransmissionMaterial` for 2D UI cards, tab bars, or buttons — 3D WebGL FBO multi-sampling exhausts mobile GPU memory and cannot refract HTML DOM elements underneath it.
> - **2D Surface Shaders & Plasma Backdrops:** Use [`.agents/skills/vgpu`](../vgpu/SKILL.md) (~25KB typed WGSL).
> - **3D Spatial Geometry & GLTF Product Scenes:** Use `visual-fx-3d` strictly for true 3D spatial geometry, glTF models, 3D physics, and 3D spatial materials.

### Deep Reference Documentation
* **Component & Tool Encyclopedia:** [`CATALOG.md`](./CATALOG.md) (All 8 domains, 100+ components, imports, and props)
* **Working Implementation Recipes:** [`RECIPES.md`](./RECIPES.md) (Copy-pasteable code examples for each tool category)

---

## 1. Architectural Role & Distinction

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                      FRONTEND VISUAL CRAFT ENGINES                          │
├─────────────────────────┬───────────────────────────┬───────────────────────┤
│ 1. 2D UI GLASS          │ 2. WEBGPU SHADERS         │ 3. 3D SPATIAL SCENES  │
│    (apple-glass)        │    (vgpu)                 │    (visual-fx-3d)     │
├─────────────────────────┼───────────────────────────┼───────────────────────┤
│ • Apple HIG frosted     │ • Fullscreen ambient mesh │ • Declarative R3F     │
│   glass (CSS/Tailwind)  │ • Interactive plasma      │ • glTF/GLB models     │
│ • Live DOM liquid lens  │ • Audio-reactive ripples  │ • Spatial lighting    │
│   refraction (SDF SVG)  │ • Particle compute        │ • 3D mesh transmission│
│ • Locked 120fps mobile  │ • ~25KB WGSL bundle       │ • Interactive tilt    │
│ • 0 canvas/screenshot   │ • Zero-GPU headless CI    │ • Postprocessing/Rapier│
└─────────────────────────┴───────────────────────────┴───────────────────────┘
```

> **House Rule:** Use `apple-glass` for all UI cards, headers, buttons, and navigation. Use `vgpu` for 2D surface shaders. Use `visual-fx-3d` strictly when rendering actual 3D spatial geometry, glTF models, or 3D physics.

---

## 2. Installation & Ecosystem Stack

Integrate the official **Poimandres (`pmndrs`)** toolkit:
* [`pmndrs/react-three-fiber`](https://github.com/pmndrs/react-three-fiber) — Core React Three.js renderer
* [`pmndrs/drei`](https://github.com/pmndrs/drei) — Abstractions, controls, staging, and shaders
* [`pmndrs/postprocessing`](https://github.com/pmndrs/postprocessing) — Cinematic bloom, DoF, and chromatic aberration
* [`pmndrs/react-three-rapier`](https://github.com/pmndrs/react-three-rapier) — Real-time WebAssembly physics
* [`pmndrs/gltfjsx`](https://github.com/pmndrs/gltfjsx) — JSX asset pipeline for 3D `.glb` models
* [`pmndrs/leva`](https://github.com/pmndrs/leva) — Live in-browser parameter tweak GUI

```bash
# Core 3D engine and production helpers
npm i three @react-three/fiber @react-three/drei

# Optional cinematic post-processing & physics
npm i @react-three/postprocessing postprocessing @react-three/rapier leva

# TypeScript definitions and glTF JSX compiler
npm i -D @types/three gltfjsx
```

---

## 3. The `gltfjsx` 3D Asset Pipeline

Never manually write imperative loaders for 3D meshes. Use `gltfjsx` to compile `.glb` / `.gltf` models into clean, declarative, typed React components with Draco compression:

```bash
# Compile and optimize 3D model into a typed React component
npx gltfjsx public/models/product.glb --transform --types -o src/components/3d/ProductModel.tsx
```

### Clean Consumption Pattern
```tsx
import React, { Suspense } from 'react';
import { Canvas } from '@react-three/fiber';
import { Center, Environment } from '@react-three/drei';
import { ProductModel } from './ProductModel';

export function ProductViewer() {
  return (
    <div className="w-full h-96 relative">
      <Canvas frameloop="demand" dpr={[1, 1.5]} camera={{ position: [0, 0, 4], fov: 45 }}>
        <ambientLight intensity={0.5} />
        <Suspense fallback={null}>
          <Center>
            <ProductModel scale={1.2} />
          </Center>
          <Environment preset="city" />
        </Suspense>
      </Canvas>
    </div>
  );
}
```

---

## 4. Component Recipe: Tactile 3D Spring Tilt Card

A tactile 3D card utilizing `@react-three/drei`'s `<PresentationControls>` with Apple 2-parameter spring physics, floating momentum, and dynamic ground contact shadows.

```tsx
'use client';

import React, { Suspense } from 'react';
import { Canvas } from '@react-three/fiber';
import { PresentationControls, Float, ContactShadows } from '@react-three/drei';

export function SpatialTiltCard({ children }: { children?: React.ReactNode }) {
  return (
    <div className="relative w-full h-80 rounded-3xl bg-neutral-950 border border-white/10 overflow-hidden shadow-2xl">
      <Canvas
        frameloop="demand"
        dpr={[1, 1.5]}
        camera={{ position: [0, 0, 5], fov: 45 }}
        className="touch-none"
      >
        <ambientLight intensity={0.6} />
        <directionalLight position={[8, 8, 4]} intensity={1.4} />

        <Suspense fallback={null}>

From sudomadhatter/design-engineer-skills, MIT.

More from sudomadhatter/design-engineer-skills