react-threejs-game

# react-threejs-game Skill ## Context Applies when building 3D scenes, implementing game loops, handling 3D interactions, optimizing Three.js rendering, loading assets, or managing game state with React. ## Rules 1. **Declarative first** — `@react-three/fiber` JSX, not imperative Three.js 2. **Type everything** — `useRef<THREE.Mesh>(null)`, typed props, typed event handlers 3. **`useFrame` for the game loop** — `((state, delta) => …)` — delta time, not wall-clock 4. **Refs for Three.js objects** — never mutate props 5. **Minimize re-renders** — 60 Hz updates go through refs, not `useState` 6. **Use Drei helpers** — `OrbitControls`, `useTexture`, `Html`, `Sparkles`, `Trail` 7. **Mesh events** — `onClick`, `onPointerOver` on meshes — no manual raycasting 8. **Dispose resources** — geometries, materials, textures, audio buffers on unmount 9. **InstancedMesh** for > 10 similar objects (particles, bullets, enemies) 10. **Target 60 fps** — frame time ≤ 16.67 ms; profile with React DevTools + Spector.js 11. **Separate concerns** — logic in hooks, rendering in JSX, state in React 12. **No `useState` inside `useFrame`** — use refs for transient animation state 13. **Accessibility** — keyboard equivalents, `prefers-reduced-motion`, readable HUD contrast 14. **Asset safety** — load textures/models only from trusted origins; no user-supplied URLs without validation ## Examples ### ✅ Typed interactive object with `useFrame` ```tsx import { useRef } from 'react'; import { useFrame } from '@react-three/fiber'; import * as THREE from 'three'; interface TargetProps { position: readonly [number, number, number]; size: number; onClick: () => void; } export function Target({ position, size, onClick }: TargetProps): JSX.Element { const meshRef = useRef<THREE.Mesh>(null); useFrame((state, delta) => { const mesh = meshRef.current; if (!mesh) return; mesh.rotation.y += delta * 0.5; mesh.position.y = position[1] + Math.sin(state.clock.elapsedTime) * 0.3; }); return ( <mesh ref={meshRef} position={position} onClick={onClick}> <sphereGeometry args={[size, 16, 16]} /> <meshStandardMaterial color="hotpink" /> </mesh> ); } ``` ### ✅ Resource disposal on unmount ```tsx import { useEffect, useMemo } from 'react'; import * as THREE from 'three'; function Ring(): JSX.Element { const geometry = useMemo(() => new THREE.TorusGeometry(1, 0.2, 16, 64), []); const material = useMemo(() => new THREE.MeshStandardMaterial({ color: 'cyan' }), []); useEffect(() => { return () => { geometry.dispose(); material.dispose(); }; }, [geometry, material]); return <mesh geometry={geometry} material={material} />; } ``` ### ✅ Respecting reduced-motion ```tsx const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches; useFrame((_, delta) => { const speed = prefersReduced ? 0 : 0.5; if (meshRef.current) meshRef.current.rotation.y += delta * speed; }); ``` ### ❌ Anti-Patterns ```typescript // BAD: setInterval for animation setInterval(() => { mesh.rotation.y += 0.01 }, 16); // BAD: useState in useFrame (60 renders/sec) useFrame(() => setPosition(p => p + 1)); // BAD: untyped ref const meshRef = useRef(null); // BAD: forgetting disposal // Leaks geometry and material on unmount // BAD: loading textures from user-supplied URLs without validation useTexture(userInputUrl); ``` ## Validation Checklist - [ ] Refs are typed (`useRef<THREE.X>(null)`) - [ ] Animations use `useFrame` + delta; no timers - [ ] No `useState` inside `useFrame` - [ ] Geometries / materials / textures disposed - [ ] > 10 similar meshes → `InstancedMesh` - [ ] `prefers-reduced-motion` honored - [ ] Asset URLs validated / from bundled sources - [ ] Frame time under 16.67 ms on target hardware