Communitygithub.com

스크롤 기반 3D 스토리텔링

페이지 스크롤에 따라 3D 장면을 연출합니다: 스크롤에 연결된 카메라 움직임, 구간별 장면 스토리텔링, 고정 히어로, 부드러운 스크롤링, 스크롤 진행률 기반 셰이더/애니메이션. 사용자가 스크롤 애니메이션, 스크롤 기반 장면, 스크롤 시 카메라 움직임, 스토리텔링 섹션, 고정된 3D 캔버스, 스크롤 진행률, GSAP ScrollTrigger, Lenis를 언급하거나 웹사이트 내러티브가 스크롤에 따라 펼쳐지길 원할 때 사용하세요. threejs-fundamentals, threejs-animation, ai-website-aesthetics와 함께 사용하세요.

스크롤 기반 3D 스토리텔링란 무엇인가요?

이 스킬은 프리미엄 AI 웹사이트에서 흔히 볼 수 있는 '스크롤 기반 3D 스토리텔링' 아키텍처를 제공합니다. 핵심 아이디어는 캔버스를 `position: fixed`로 유지하고 DOM은 정상적으로 스크롤되도록 두면서, 스크롤 위치를 읽어 단일 진행률 값(`scrollProgress`)으로 변환하고, 이 값을 기반으로 3D 장면의 모든 요소(카메라 위치, 모델 변환, 조명, 셰이더 유니폼)를 보간하는 것입니다. 스토리보드를 먼저 설계하여 각 스크롤 구간(예: 0.00-0.15 히어로 비트)에 특정 장면 상태를 매핑하고, 각 비트에 대해 `(시작, 끝, 적용(t))` 함수 쌍을 구현하여 클램핑, 이징 및 보간을 처리합니다. 부드러운 스크롤을 위해 Lenis를 사용하며(접근성 및 SEO를 위해 기본 스크롤을 차단하지 않음), 카메라 경로는 `THREE.CatmullRomCurve3`를 사용하여 여러 비트에 걸쳐 매끄러운 움직임을 만듭니다. DOM 콘텐츠와 3D 장면은 동일한 `scrollProgress` 소스에서 동기화되어 한 가지 진실 공급원을 유지합니다. 성능 최적화(DPR 제한, 화면 밖에서 RAF 일시 중지)와 접근성(`prefers-reduced-motion` 준수, WebGL 대체)도 중요하게 다룹니다. 이 스킬은 threejs-animation, ai-website-aesthetics, threejs-postprocessing, 3d-hero-interactions와 함께 사용하여 완전한 경험을 구축합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/BLACKNIGHT-cloud12/scroll-driven-3d-story/tree/HEAD

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

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

문서

스크롤 기반 3D 스토리텔링은(는) 무엇을 하나요?

최고 수준 AI 웹사이트의 특징: 페이지가 스크롤되고, 3D 장면이 이야기를 전합니다 — 카메라가 미끄러지고, 모델이 조립되고, 입자가 재형성됩니다. 이 스킬은 그 아키텍처를 제공합니다.

아키텍처: 하나의 고정 캔버스, 스크롤이 숫자를 구동합니다

캔버스는 DOM 뒤에 position: fixed로 위치합니다. 스크롤은 캔버스를 절대 움직이지 않습니다 — 장면이 보간하는 진행률 값을 움직입니다. 나머지는 구현 세부 사항입니다.

// DOM은 정상적으로 스크롤됩니다. 우리는 읽기만 하고 가로채지 않습니다.
let scrollProgress = 0;
addEventListener('scroll', () => {
  scrollProgress = scrollY / (document.body.scrollHeight - innerHeight);
}, { passive: true });

RAF 루프에서 scrollProgress로 장면 상태를 보간합니다. 이것이 전부입니다: 스토리보드(아래 참조)를 만든 다음 비트별로 보간기를 작성하세요.

스토리보드 (항상 먼저 만드세요)

코드 작성 전에 주석이나 표로 스크롤 범위를 장면 상태에 매핑하세요:

0.00-0.15  히어로:    모델이 중앙에 떠 있고, 천천히 회전, 카메라 z=8
0.15-0.35  기능:      카메라가 x=-4로 돌리, 모델이 3부분으로 분할
0.35-0.60  기술:      카메라가 90°로 궤도 이동, 입자 떼가 들어옴, 와이어프레임 오버레이 페이드 인
0.60-0.80  증명:      카메라가 뒤로 물러나고, 장면이 어두워지며, DOM 카드가 캔버스 위로 페이드 오버
0.80-1.00  CTA:       모델이 중앙에 재조립, 광채가 퍼짐, 카메라 z=5

각 비트를 (시작, 끝, 적용(t)) 쌍으로 구현하고, 진행률을 각 범위로 클램핑하고 적용 전에 t를 이징하세요. 카메라 위치, 회전, 유니폼 값을 키프레임 상태 사이에서 보간하세요 — 의도적으로 스냅하는 경우가 아니라면 비트 중간에 순간이동하지 마세요.

부드러운 스크롤: Lenis, 스크롤 하이재킹이 아님

관성 느낌을 위해 Lenis를 사용하세요. 여전히 기본 스크롤을 구동합니다(접근성 안전):

const lenis = new Lenis({ lerp: 0.1 });
function raf(time) { lenis.raf(time); update3D(); requestAnimationFrame(raf); }
requestAnimationFrame(raf);
  • 기본 스크롤을 차단하지 마세요(overflow: hidden on body) — 키보드/모바일 사용자와 SEO를 해칩니다.
  • 수동 진행률 대신 GSAP ScrollTrigger를 사용하는 경우에도 캔버스를 고정된 상태로 유지하고 장면 상태를 구동하세요. ScrollTrigger가 캔버스를 변형시키지 않도록 하세요.

카메라 경로

여러 비트에 걸친 움직임의 경우 키프레임 위치를 통해 THREE.CatmullRomCurve3를 정의하고 이징된 진행률로 샘플링하세요 — 점 쌍을 lerping하는 것보다 더 부드럽습니다. 시선 대상에는 자체 곡선을 사용하세요. 이징/곡선 세부 사항은 threejs-animation과 연결됩니다.

DOM + 3D 동기화

  • 섹션 텍스트는 일반 DOM입니다. 캔버스 위에 mix-blend-mode 또는 반투명 패널을 추가하세요.
  • 장면 비트와 함께 섹션 공개를 동기화하세요: 동일한 scrollProgress 범위에서 DOM 애니메이션(GSAP 또는 CSS)을 트리거하세요 — 하나의 진실 공급원입니다.
  • 3D 레이블을 월드 위치를 매 프레임마다 화면 공간으로 투영하여 앵커링하세요. 카메라 뒤에 있으면 숨기세요.

성능 및 모바일

  • 캔버스를 하나의 DPR(1.5–2로 제한)로 유지하세요. 스크롤 연결 장면은 스크롤 여부와 관계없이 매 프레임마다 다시 렌더링됩니다 — 다른 프레임당 작업을 줄이세요.
  • 탭이나 장면이 화면 밖으로 많이 벗어나면 RAF 렌더링을 일시 중지하세요(document.visibilityState, 섹션의 IntersectionObserver).
  • 모바일: 비트 수를 줄이고(스크롤 길이 아님), 입자 수를 낮추고, 후처리를 비활성화하세요(threejs-performance 및 threejs-postprocessing 스킬 참조).
  • iOS Safari: 주소 표시줄 크기 조정이 스크롤 도중 innerHeight를 변경합니다 — 크기 조정을 디바운싱하고, 비트가 불안정해 보이면 진행률 계산에 visualViewport 인식 높이를 선호하세요.

접근성 및 대체

  • prefers-reduced-motion을 존중하세요: 최종 조립된 상태를 정적 장면으로 렌더링하고, 카메라 연출을 건너뛰세요. 스크롤은 정상으로 유지됩니다.
  • 3D 꺼짐 대체(약한 GPU / failsIf): 그라데이션 배경 + 동일한 DOM 이야기. 이야기는 WebGL 없이도 살아남아야 합니다.

일반적인 실수

  • 스크롤 이벤트나 휠 하이재킹 — "프리미엄" 사이트가 망가진 느낌을 주는 #1 이유.
  • 매 프레임마다 scrollHeight 읽기(레이아웃 스래싱) — 크기 조정 시 캐싱하세요.
  • 카메라 움직임에 원시 선형 진행률 적용 — 항상 이징(slow-in-out)하거나 기계적으로 느껴집니다.
  • 여러 ScrollTrigger가 동일한 장면 속성을 각각 변경 — 충돌합니다. 모든 것을 하나의 진행률 값으로 라우팅하세요.
  • 루프에서 lenis.raf(time)을 잊는 것 → 스크롤이 죽은 듯한 느낌.

관련 스킬

  • threejs-animation — 이징, 곡선, 모핑
  • ai-website-aesthetics — 비트의 외관
  • threejs-postprocessing — 비트 간 블룸 램프
  • 3d-hero-interactions — 히어로 비트의 클릭/호버 동작

관련 스킬