Communitygithub.com

VectoJS Three

VectoJS 2D 인터페이스를 Three.js 텍스처에 배치하고 3D 포인터 입력을 VectoJS 씬으로 라우팅하는 스킬입니다.

VectoJS Three란 무엇인가요?

이 스킬은 VectoJS 2D 인터페이스를 Three.js 3D 텍스처 위에 렌더링하고, 3D 공간에서의 포인터 입력(예: 클릭, 호버, 휠)을 VectoJS 논리적 2D 씬으로 전달하는 방법을 제공합니다. 개발자는 `ThreeAdapter`를 사용하여 VectoJS 패널을 Three.js 메시로 변환하고, 호스트 Three.js 씬에 추가한 후, 레이캐스팅을 통해 사용자 인터랙션을 동기화할 수 있습니다. 이 스킬은 Codex, Claude Code, Cursor, GitHub Copilot과 같은 AI 에이전트 플랫폼에서 VectoJS 기반 3D UI 컴포넌트를 빌드, 최적화 및 디버깅할 때 유용하며, 2D 논리적 히트 테스트와 3D 공간 변환을 자연스럽게 결합합니다. 특히, 버전 호환성 문제(예: `three ≤ 0.1.3`의 GL flush 성능 이슈)와 일반적인 실수(예: `updateIntersection` 호출 누락)를 사전에 방지할 수 있도록 상세한 제약 조건과 오류 수정 표를 제공합니다.

지원 대상✓Claude Code✓Codex CLI✓Cursor
npx skills add vectojs/vectojs-skills

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

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

문서

VectoJS Three은(는) 무엇을 하나요?

이 스킬을 사용하면 라이브 VectoJS 2D 인터페이스를 Three.js 텍스처 위에 올리고 3D 포인터 입력을 VectoJS 씬으로 다시 라우팅할 수 있습니다.

통합 워크플로우

  1. @vectojs/core, @vectojs/three, three, 그리고 UI 컴포넌트를 사용하는 경우 @vectojs/ui를 설치합니다.
  2. VectoJS 패널 텍스처당 하나의 ThreeAdapter를 생성합니다.
  3. adapter.vectoScene에 VectoJS 엔티티를 추가한 다음 내부 씬을 시작합니다.
  4. adapter.mesh 또는 어댑터 텍스처/머티리얼을 호스트 Three.js 씬에 추가합니다.
  5. 호스트 포인터/휠 루프에서 어댑터 메시에 대해 레이캐스트를 수행하고 adapter.updateIntersection(...)을 호출합니다.
  6. 패널을 제거할 때 adapter.dispose()를 호출합니다.

참조: references/three-recipes.md에서 스니펫을 확인하세요.

제약 사항

  • 기본 출력은 평평한 텍스처 평면이며, 3D에서 DOM으로 렌더링되지 않습니다.
  • VectoJS 논리적 히트 테스팅은 메시가 월드 공간에서 변환되더라도 2D로 유지됩니다.
  • 호스트 애플리케이션이 카메라, 렌더러, 컨트롤, XR 세션, 레이캐스터 및 폐색 규칙을 소유합니다.
  • 레이캐스트 UV는 어댑터의 논리적 width/height에 매핑되어야 하며, 레이아웃 계산에 백킹 저장소 크기를 사용하지 마십시오.
  • 텍스처 해상도는 선명도와 업로드 비용에 영향을 미칩니다. 시청 거리에 맞는 치수를 선택하십시오.

일반적인 실수

실수수정 사항
오프스크린 어댑터 캔버스를 DOM에 추가함adapter.mesh를 Three.js에 추가하십시오. 캔버스가 텍스처를 뒷받침합니다.
updateIntersection 호출을 잊음각 포인터/휠 이벤트마다 호스트 레이캐스터 이벤트를 어댑터로 라우팅하십시오.
화면 좌표로 디스패치함ThreeAdapter를 통해 레이캐스트 UV를 사용하십시오.
폐기된 텍스처를 활성 상태로 유지함adapter.dispose()를 호출하고 호스트 참조를 제거하십시오.
XR 내에서 완전한 DOM 접근성 기대3D 패널을 캔버스 텍스처로 취급하고, 필요한 경우 호스트 수준의 의미를 제공하십시오.

버전 및 백엔드 주의사항 (소스 확인 완료)

  • three ≤ 0.1.3: ThreeRenderer.flush()가 전체 GL 렌더를 수행하고, 씬이 배치되지 않은 모든 노드 주변에서 플러시를 실행하여 프레임 비용이 엔티티 수에 따라 O(N²)으로 증가했습니다. three 0.1.4에서는 present() 훅을 통해 프레임당 한 번씩 렌더링합니다. 다른 프로파일링 전에 업그레이드하십시오.
  • 텍스처 내 기본 입력은 제한적입니다. 어댑터의 캔버스는 오프스크린이므로, 씬의 프로젝션 접근성 요소가 문서에 연결되지 않습니다. updateIntersection은 VectoJS 자체 이벤트 디스패치로 폴백됩니다. 버튼/호버/휠은 작동하지만, 완전한 기본 IME/텍스트 편집은 작동하지 않습니다. 텍스트 입력은 3D 패널 외부에 두거나 단순화된 입력을 수용하십시오.
  • stroke() 선 두께는 대부분의 플랫폼에서 사실상 1px입니다 (LineBasicMaterial.linewidth는 알려진 WebGL 제한 사항). 두꺼운 선은 채워진 도형으로 그리십시오.
  • ThreeRenderer.drawImage는 호출당 프레임당 텍스처를 할당합니다 (clear()에서 폐기됨). 가능하면 소스 캔버스를 재사용하십시오. fillText는 three 0.1.4부터 캐시됩니다 (LRU 키: font|color|text, 256개 항목). ≤ 0.1.3에서는 동일한 호출당 비용이 있었으므로, 해당 버전에서는 MSDFTextEntity를 선호하십시오.

관련 스킬