Community코딩 & 개발github.com

3D 물리 & 시뮬레이션

three.js 웹사이트 내에서 강체, 중력, 충돌, 래그돌, 천, 체인 및 GPU 입자 시뮬레이션을 실행합니다. 사용자가 물리, 시뮬레이션, 중력, 충돌, 튀는 물체, 파괴, 천, 유체 같은 입자 효과를 언급하거나 게임뿐만 아니라 마케팅/랜딩 페이지에서도 사실적인 움직임을 가진 3D 객체를 원할 때 사용하세요.

3D 물리 & 시뮬레이션란 무엇인가요?

이 기술은 three.js 기반 웹사이트에 실제 물리 시뮬레이션을 통합하는 방법을 안내합니다. Rigid Body (강체), 중력, 충돌, 래그돌, 천, 체인 등 다양한 물리 효과를 지원하며, 주로 Rapier 엔진(기본)과 cannon-es 엔진을 사용합니다. WASM 기반 Rapier는 뛰어난 성능과 결정론적 시뮬레이션을 제공하며, `await RAPIER.init()`으로 비동기 초기화가 필요합니다. 물리 엔진이 상태를 관리하고 three.js는 매 프레임마다 body의 위치와 회전을 동기화하여 렌더링하는 패턴을 사용합니다. 또한 고정 타임스텝(fixed timestep), 인스턴싱(InstancedMesh)을 통한 대량 객체 처리, 객체 수면(sleep) 기능, 클릭-임펄스 패턴 등을 다룹니다. 단순한 효과(떠다니는 구체, 클릭으로 흩어지는粒子 등)는 물리 엔진 없이 수학이나 셰이더로 구현하는 '가짜 물리(fake physics)' 기법도 소개하며, GPU 입자 시뮬레이션(GPGPU/FBO)은 수천 개의 입자를 처리해야 하는 신경망 클라우드, 연기, 별 필드 등에 사용됩니다. 이 기술은 threejs-fundamentals, threejs-interaction, threejs-performance 기술과 함께 사용하면 더욱 효과적입니다.

지원 대상~Claude Code~Codex CLI✓Cursor
Part ofReact
npx skills add https://github.com/BLACKNIGHT-cloud12/3d-physics-simulations/tree/HEAD

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

3D 물리 & 시뮬레이션은(는) 무엇을 하나요?

3D 씬이 실제처럼 행동하도록 만듭니다: 물체가 떨어지고, 쌓이고, 부서지며, 클릭에 질량감 있게 반응합니다. 이 기술은 엔진 선택, three.js 연결, 60fps 유지, 그리고 히어로 섹션에서 사용되는 클릭-임펄스 패턴을 다룹니다.

엔진 선택

  • Rapier (@dimforge/rapier3d-compat) — 기본값. WASM 기반, 결정론적, 적극적으로 유지보수됨, 최고 성능. 번들러에는 rapier3d-compat (비동기 WASM 초기화) 사용; rapier3d (동기)는 일반 스크립트 태그에서만 사용.
  • cannon-es — WASM 로딩을 피해야 할 때만 사용 (file:// 데모, 엄격한 CSP). 느리고 유지보수 덜 됨.
  • GPGPU/FBO 입자 — 연기, 떼, "AI 신경망" 입자 구름 (수천 개 이상)에 사용. 물리 엔진이 아닙니다; 아래 GPU 섹션 참고.

Rapier를 본체 생성 전에 로드하세요:

import RAPIER from '@dimforge/rapier3d-compat';
await RAPIER.init(); // world 생성 전에 한 번 필요
const world = new RAPIER.World({ x: 0, y: -9.81, z: 0 });

핵심 연결 패턴 (three.js + Rapier)

물리는 상태를 소유하고; three.js는 렌더링만 합니다. 본체가 있는 메시를 직접 움직이지 말고 — 매 프레임 본체를 읽어 메시에 반영하세요.

// 1. 본체 먼저 생성
const bodyDesc = RAPIER.RigidBodyDesc.dynamic().setTranslation(0, 5, 0);
const body = world.createRigidBody(bodyDesc);
const colliderDesc = RAPIER.ColliderDesc.cuboid(0.5, 0.5, 0.5).setRestitution(0.4);
world.createCollider(colliderDesc, body);

// 2. 렌더 루프 — 동기화, 직접 설정 금지
function tick(dt) {
  world.timestep = dt;
  world.step();
  mesh.position.copy(body.translation());
  mesh.quaternion.copy(body.rotation());
}
  • 안정성을 위해 고정 타임스텝 사용: dt를 누적하고, 1/60 단위로 스텝, 프레임당 최대 3 스텝으로 제한 (죽음의 나선 방지).
  • 플랫폼/이동체에는 키네마틱 본체 사용; 매 프레임 setNextKinematicTranslation() 호출.
  • 콜라이더는 메시 스케일을 상속하지 않음 — 월드 단위로 직접 크기 지정.

클릭-임펄스 패턴 (히어로 섹션)

포인터로 광선을 쏘고, 커서 아래 본체를 찾아, 차기. 최상위 AI 사이트에서 사용하는 "히어로 객체 찌르기" 상호작용입니다. 레이캐스터 세부 사항은 threejs-interaction 기술 참고.

raycaster.setFromCamera(pointerNDC, camera);
const hit = world.castRay(new RAPIER.Ray(origin, dir), 100, true, undefined, undefined, undefined, filterPredicate);
if (hit) {
  const body = world.getCollider(hit.colliderHandle).parent();
  const dir3 = rayDir.clone().multiplyScalar(6); // 임펄스 강도
  body.applyImpulse({ x: dir3.x, y: dir3.y, z: dir3.z }, true);
}

클릭 가능한 본체에는 약간의 각운동 감쇠(setAngularDamping(0.5))를 적용하여 영원히 회전하지 않고 그럴듯하게 회전하도록 하세요.

대량 본체: 인스턴싱, 예산, 수면

  • 지오메트리당 하나의 THREE.InstancedMesh 사용; world.step() 후 본체 변환을 인스턴스 행렬에 기록. 약 50개 이상의 객체에서는 본체당 하나의 Mesh를 사용하지 마세요.
  • 예산: 데스크탑에서 약 200개의 동적 상자/콜라이더 무난; 모바일에서 약 80개. 그 이하에서는 가짜 물리로 대체 (아래 "가짜 물리" 참고).
  • 본체는 수면 상태로 두고(기본) 상호작용 시에만 깨우세요. 절대 잠들지 않는 본체로 가득한 씬은 CPU를 낭비합니다.
  • 콜라이더에는 단순한 지오메트리(상자/구/캡슐) 사용; 윤곽이 중요한 경우에만 볼록/복합 메시 사용.

가짜 물리 (먼저 결정)

대부분의 마케팅 사이트는 엔진이 필요하지 않습니다. 물음: 효과에 충돌이 필요한가, 아니면 단지 그럴듯한 움직임만 필요한가?

  • 커서에 반응하는 떠다니는 구체 → 스프링/댐핑 수학, 엔진 없음.
  • 클릭으로 흩어지는 3D 모양 종이 조각 → 미리 계산된 속도 + 단일 셰이더 또는 루프에서의 중력 통합, 엔진 없음.
  • 드래그 가능한 히어로 모델이 원위치로 돌아오기 → 휴식 자세로의 스프링 (3d-히어로-상호작용 기술 참고). 물체가 충돌하고, 서로 위에 쌓이거나, 쌓여야 할 때만 Rapier를 사용하세요.

GPU 입자 시뮬레이션

신경망 구름, 별 필드, 연기 — 핑퐁 렌더 타겟(상태 텍스처)을 통해 GPU에서 업데이트되는 수천 개의 입자. 자세한 내용과 작동 템플릿: references/gpgpu-particles.md 참고.

일반적인 실수

  • await RAPIER.init() 를 잊음 → 모호한 WASM 오류.
  • mesh.position 을 설정하고 본체가 그것을 구동하게 둠 — 본체가 이기고 메시가 순간이동. 본체를 움직이고, 메시는 읽기만.
  • 프레임마다 가변 타임스텝 → 떨리는 더미와 터널링. 고정 타임스텝 + 누적기.
  • 충돌 이벤트 내에서 렌더 루프 작업 추가 — 효과를 큐에 넣고 step() 후에 적용.
  • 물리 피킹을 위해 three.js 씬을 레이캐스팅하는 대신 world.castRay 사용 (또는 그 반대) — 객체를 소유한 월드에서 피킹.
  • 페이지 전환 시 월드를 복원하지 않음 (R3F 언마운트 시 WASM 본체 누수; 월드 폐기).

관련 기술

  • threejs-fundamentals — 씬, 렌더러, 루프
  • threejs-interaction — 레이캐스팅 및 포인터 피킹
  • threejs-performance — 인스턴싱 및 예산
  • 3d-히어로-상호작용 — 상위 UX 계층 (호버 상태, 폭발, 자기 커서)

관련 스킬