Communitygithub.com

모바일 퍼스트 3D

무거운 3D/WebGL 사이트를 위한 전용 휴대폰/태블릿 환경 — 기기 프로필 감지, 더 가벼운 렌더 설정 및 텍스처 세트, 피사체(고리를 가진 행성, 은하)가 잘리지 않도록 하는 세로형 카메라 프레이밍, 바텀 시트 콘텐츠, 메뉴 시트, 세이프 에리어, 터치 동작 및 짧은 스크롤을 제공합니다. 3D 사이트를 구축할 때 항상 사용하고, 누군가 "모바일에서 잘렸어요 / 완벽하게 안 보여요 / 느려요 / 이상해요"라고 말할 때 사용하세요.

모바일 퍼스트 3D란 무엇인가요?

이 스킬은 모바일 3D WebGL 사이트에서 발생하는 주요 문제점(렌더링 성능, 피사체 잘림, 레이아웃 깨짐)을 해결하기 위해 설계되었습니다. `html.mobile` 클래스 하나로 전환되는 별도의 모바일 프로필을 구축하여, 데스크톱과 동일한 코드베이스로 최적화된 모바일 경험을 제공합니다. 주요 기능으로는 기기 감지(포인터 유형, 화면 크기), 저해상도 렌더링 설정(DPR, 지오데식 스텝, 텍스처 세트), 세로형 카메라 프레이밍(수평 FOV가 좁은 환경에서 피사체가 잘리지 않도록 보정), 바텀 시트 레이아웃, 터치 동작 최적화, 그리고 실제 기기 테스트를 대체할 수 있는 최소한의 에뮬레이션 가이드라인을 포함합니다. Cursor, Windsurf, Claude Code 등 다양한 AI 에이전트 환경에서 활용할 수 있으며, 특히 다양한 화면 크기와 입력 방식을 가진 모바일 기기에서 일관된 3D 경험을 보장해야 할 때 필수적입니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/forpc1428-eng/cosmic-forge/tree/HEAD/skills/mobile-first-3d

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

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

문서

모바일 퍼스트 3D은(는) 무엇을 하나요?

휴대폰은 작은 데스크톱이 아닙니다. html.mobile 클래스 하나로 전환되는 별도의 프로필을 구축하세요.

1. 감지

const MOBILE = qs.get('m') === '1' || (qs.get('m') !== '0' &&
  (matchMedia('(pointer: coarse)').matches || Math.min(innerWidth, innerHeight) < 600));
document.documentElement.classList.toggle('mobile', MOBILE);

?m=1 / ?m=0으로 강제 설정할 수 있습니다 — 데스크톱 에뮬레이션에서 테스트할 때 필수적입니다.

2. 렌더링 프로필

설정데스크톱휴대폰
DPR 상한 / 최대 픽셀1.5 / 3.2 MP1.25 / 1.0 MP
측지선(Geodesic) 단계220150
볼륨 샘플3624
스카이 베이크 크기768 / 512384 / 256
텍스처 세트textures/hd (~6 MB)textures/m (~1.2 MB)
마우스 시차/둘러보기켜짐꺼짐 (터치 전용; 에뮬레이터는 마우스 이벤트를 보냄)

3. 세로형 프레이밍 (대부분 "잘렸어요" 버그가 발생하는 곳)

  • 세로형에서 수평 FOV는 매우 좁습니다: tan(hFOV/2) = tan(vFOV/2)·aspect (52°, 0.46 화면비에서 ≈0.22).
  • 각 피사체로부터의 거리 = max(R·distMul·1.25, visibleRadius·7.6); visibleRadius는 고리 포함 (토성 ≈ 2.35 R, 천왕성 ≈ 1.8 R).
  • 피사체를 조준한 후, 보기를 전체적으로 약 0.21 rad 아래로 기울여 텍스트 시트 위쪽 1/3 지점에 위치시킵니다. (대상을 오프셋하면 카메라가 움직일 때 옆으로 표류합니다.)
  • 더 전면적으로 조명 설정 (~45° 위상): 작은 화면에서 측면이 반쯤 어두운 행성은 "잘렸다"고 읽힙니다.
  • 콘텐츠 유지 중에는 조준을 고정합니다(대상 접선 0) — 중앙에서 표류하지 않도록 합니다.
  • 수치적으로 확인: 프레임을 렌더링하고, 피사체 가로질러 readPixels 행으로 조명 범위가 너비의 5~95% 내에 있는지 확인합니다.

4. 레이아웃

  • 패널 → 바텀 시트: left:0; right:0; bottom:0; max-height:60vh; overflow:auto, 그라데이션 배경, padding-bottom: calc(54px + env(safe-area-inset-bottom)).
  • 제목 clamp(34px, 10vw, 52px); 히어로 이름은 2줄로 분할.
  • 네비게이션 → 버거 + 전체 화면 블러 시트, 44px 세리프 링크.
  • 장식용 레일 숨기기; 라벨 단축(이름만); 접촉 시 랜딩 스크롤 힌트 숨기기.
  • 더 짧은 스크롤: 인트로 ~320vh, 여정 ~2600vh (휴대폰은 관성으로 더 빠르게 스크롤).
  • viewport-fit=cover, 100svh 고정 스테이지, 320px에서 가로 오버플로우 없음.

5. 테스트 매트릭스 (에뮬레이션만으로 충분하지 않지만 최소한의 기준)

375×812 및 390×844 세로형, 412×915 Android, 768×1024 태블릿. 모든 콘텐츠 비트: 피사체가 시트 위에 완전히 보이고 중앙에 위치하며, 텍스트를 읽을 수 있고, 노치/홈 바 아래에 가려지지 않아야 함. 실제 기기 테스트를 수행하지 않았으면 사용자에게 정직하게 알리세요.

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

관련 스킬