phido0410/threejs-3d

Stack 3D Three.js

Verificado em 2026-10: three 0.186, @react-three/fiber 9.8, @react-three/drei 10.7, @react-three/rapier 2.2, @react-three/postprocessing 3.2 (+ postprocessing 6.39). Fiber 9 / Drei 10 / Rapier 2 / postprocessing 3 precisam de React 19 (fiber 9.8 peer: react >=19 <19.4).

npm i three @react-three/fiber @react-three/drei
npm i @react-three/rapier                         # física
npm i @react-three/postprocessing postprocessing  # efeitos
npm i -D @types/three

Cena base (web)

import { useRef, Suspense } from 'react'
import * as THREE from 'three'
import { Canvas, useFrame } from '@react-three/fiber'
import { OrbitControls, Environment, ContactShadows } from '@react-three/drei'

function Box() {
  const ref = useRef<THREE.Mesh>(null!)
  useFrame((_, delta) => { ref.current.rotation.y += delta }) // mutar refs, nunca usar setState por quadro
  return (
    <mesh ref={ref} castShadow>
      <boxGeometry />
      <meshStandardMaterial color="#4a9eff" />
    </mesh>
  )
}

<Canvas camera={{ position: [3, 2, 5], fov: 45 }} dpr={[1, 2]} shadows>
  <ambientLight intensity={0.3} />
  <directionalLight position={[5, 5, 5]} castShadow />
  <Suspense fallback={null}>
    <Box />
    <Environment preset="city" />
  </Suspense>
  <ContactShadows position={[0, -0.5, 0]} opacity={0.5} blur={2} />
  <OrbitControls />
</Canvas>

Regras:

• Qualquer coisa assíncrona (useGLTF, useTexture, Environment, fontes de Text, WASM de Physics) fica dentro de <Suspense>.
• useGLTF.preload(url) no nível do módulo para modelos usados na primeira renderização.
• Mantenha as cenas entre 1 e 10 unidades; escalas muito grandes ou pequenas quebram sombras e controles.
• MeshStandardMaterial precisa de luz ou de um <Environment>; sem eles, renderiza preto.

Drei (escolha o que for necessário)

• Câmera/controles: OrbitControls, CameraControls, PerspectiveCamera makeDefault
• Assets: useGLTF, useTexture, Environment (presets: apartment, city, dawn, forest, lobby, night, park, studio, sunset, warehouse), Center, Bounds
• Staging: ContactShadows, AccumulativeShadows, Stage, Float, Sparkles, Stars, Cloud
• Materiais: MeshTransmissionMaterial (vidro), MeshReflectorMaterial (piso reflexivo)
• Texto: Text (SDF, qualquer URL de fonte), Text3D (precisa de JSON de typeface), Html (overlay DOM)

Física Rapier

import { Physics, RigidBody, CuboidCollider, type RapierRigidBody } from '@react-three/rapier'

<Suspense>
  <Physics gravity={[0, -9.81, 0]} /* debug */>
    <RigidBody colliders="hull" restitution={0.6} ref={bodyRef}>
      <mesh><torusGeometry /><meshStandardMaterial /></mesh>
    </RigidBody>
    <RigidBody type="fixed">
      <CuboidCollider args={[10, 0.1, 10]} /> {/* metade das extensões */}
    </RigidBody>
  </Physics>
</Suspense>
// bodyRef.current?.applyImpulse({ x: 0, y: 5, z: 0 }, true)

• colliders: "cuboid" (padrão), "ball", "hull", "trimesh", false (adicione componentes de colisor você mesmo).
• type: "dynamic" (padrão), "fixed", "kinematicPosition", "kinematicVelocity".
• timeStep padrão é fixo em 1/60. timeStep="vary" não é determinístico. Passo manual: useRapier().step(1 / 60).
• debug no <Physics> desenha os colisores.

Pós-processamento

import { EffectComposer, Bloom, Vignette, DepthOfField, Noise } from '@react-three/postprocessing'

<EffectComposer>{/* último filho de <Canvas> */}
  <Bloom luminanceThreshold={0.9} intensity={1.2} mipmapBlur />
  <Vignette offset={0.1} darkness={0.9} />
</EffectComposer>

• Bloom captura apenas pixels acima de luminanceThreshold. Para fazer um objeto brilhar: cor emissive + emissiveIntensity > 1 + toneMapped={false} no material dele.
• Cada efeito custa uma passada de tela cheia; 2 a 4 efeitos é suficiente.

Para vídeo

Remotion (veja remotion-markup/3d.md): <ThreeCanvas width height> de @remotion/three; sem useFrame; todo movimento vem de useCurrentFrame(). Além disso:

• Sem OrbitControls — mova a câmera a partir de frame (interpolate / spring).
• Helpers Drei que animam com seu próprio relógio (Float, Sparkles, Stars, Cloud, MeshWobbleMaterial) piscam em renderizações. Deixe-os de fora ou reproduza o movimento a partir de frame.
• Física: Remotion renderiza quadros fora de ordem entre abas, então uma simulação ao vivo não pode coincidir. Faça um bake: inicialize @dimforge/rapier3d-compat (o motor por baixo do @react-three/rapier) uma vez, world.step() com timestep = 1 / fps para cada quadro, armazene a posição + rotação de cada corpo por quadro, então renderize as transformações no índice frame.

Fora do Remotion (gravação de tela, controlado por GSAP): useFrame é aceitável; acione o tempo a partir de uma timeline (tl.time()) em vez de delta quando a tomada precisar ser repetível.