XR Blocks 딥다이브
— 구글이 만든 "AI + XR 프로토타이핑" 웹 라이브러리

1프로젝트 한줄 요약

이 저장소가 대체 무엇인가.

README의 자기소개는 이렇다: "XR Blocks is a lightweight, cross-platform library for rapidly prototyping advanced XR and AI experiences." — "고급 XR·AI 경험을 빠르게 프로토타이핑하기 위한 가볍고 크로스플랫폼인 라이브러리." 여기서 세 단어가 핵심이다: lightweight(무겁지 않게), cross-platform(헤드셋·데스크톱 모두), rapidly prototyping(빠른 시제품).

기반은 three.js(웹에서 3D를 그리는 사실상 표준 라이브러리)다. XR Blocks는 three.js를 "의존 대상(peer dependency)"으로 두고, 그 위에 XR 전용 기능(손·깊이·평면·AI)을 얹는 레이어 역할을 한다. 타깃은 Chrome 136+이고, 삼성 Galaxy XR 같은 안드로이드 XR 기기의 WebXR을 지원한다.

2왜 주목받는가

구글 XR Labs 공개 · three.js 창시자 참여 · 헤드셋 없는 시뮬레이터 · Gemini Live · "바이브 코딩 XR".

XR Blocks가 트렌딩에 오른 이유는 여러 겹이다. 첫째, "구글 XR Labs가 직접 낸 오픈소스"라는 무게다. 저자 명단에는 three.js를 만든 Ricardo Cabello(mrdoob), 구글 리서치의 David Kim·Ruofei Du 등이 포함돼 있다. 웹 3D 생태계의 원류가 참여한 프로젝트라는 상징성이 크다. 둘째, 삼성 Galaxy XR 출시와 안드로이드 XR 플랫폼이 뜨면서, "웹으로 XR을 만드는 가장 쉬운 길"에 대한 수요가 폭발했다.

맨손 WebXR 개발로는 왜 벅찬가

주목도를 끌어올린 구체적 요인은 다음과 같다.

① 헤드셋 없이 개발 — 데스크톱 시뮬레이터. XR 개발의 가장 큰 고통은 "기기가 있어야 테스트된다"는 점이다. XR Blocks는 ?formFactor=desktop만 붙이면 일반 크롬에서 가상 사용자·가상 손·가상 깊이로 앱을 돌린다. 헤드셋을 쓰고 벗는 반복 없이 코드→새로고침으로 개발한다.
② Gemini가 1급 시민. options.enableAI() 한 줄로 Gemini에 연결된다. 단순 질의부터 Gemini Live(실시간 멀티모달 대화), 카메라로 본 물체를 Gemini가 인식하는 object detection까지 XR과 엮인다.
③ CDN 한 줄로 시작. 설치 없이 <script type="importmap">에 jsDelivr URL만 넣으면 브라우저에서 바로 돈다. "빈 HTML 파일 하나로 XR 씬 띄우기"가 가능하다.
④ 학술 백본. arXiv 논문 2편(2509.25504 XR Blocks, 2603.24591 Vibe Coding XR)과 research.google 블로그가 뒷받침한다. 단순 데모가 아니라 "Human-centered AI + XR"이라는 연구 비전의 구현체다.

3기술 스택 전체 지도

TypeScript + three.js를 축으로, 온디바이스 ML(MediaPipe/LiteRT)·클라우드 AI(Gemini)·물리(Rapier WASM)를 조립.

XR Blocks는 순수 프론트엔드 라이브러리다 — 서버가 없다. 대신 브라우저에서 돌아가는 여러 무거운 기술을 하나의 SDK로 오케스트레이션한다. 언어는 TypeScript(strict)이고, 빌드 결과물은 ESM 번들(build/xrblocks.js) 하나 + 애드온별 번들이다. 무거운 의존성(three, Gemini, MediaPipe, Rapier 등)은 번들에 넣지 않고 external로 빼서, 사용자가 importmap/CDN으로 따로 로드한다.

① 3D 렌더링 코어

② 입력 · 온디바이스 ML

③ AI · 물리 · 공간 UI

④ 빌드 · 개발 · 배포

4아키텍처 심화 분석

싱글턴 엔진(Core) + 스크립트 생명주기(Script) + 옵션 스위치(Options). 유니티 MonoBehaviour를 웹으로.

XR Blocks의 심장은 "하나의 싱글턴 엔진 + 스크립트 생명주기" 패턴이다. 게임 엔진을 써 봤다면 익숙하다 — 유니티의 MonoBehaviour처럼, 개발자는 xb.Script를 상속해 init()·update() 같은 생명주기 훅만 채우고, 엔진이 나머지(렌더 루프·XR 세션·입력)를 굴린다.

패턴 1 — 스크립트 하나가 곧 THREE.Object3D

똑똑한 설계 포인트: xb.Script는 three.js의 Object3D를 상속한다. 즉 스크립트 자체가 씬 그래프의 노드다. 그래서 this.add(mesh)를 하면 그 메시가 "내 스크립트 밑"에 붙는다. 별도의 "씬에 추가" 개념을 배울 필요가 없다.

// 가장 작은 XR Blocks 앱 (CONTEXT.md의 정석 패턴)
import * as THREE from 'three';
import * as xb from 'xrblocks';

class MainScript extends xb.Script {
  init() {                       // 한 번 실행
    this.add(new THREE.HemisphereLight(0xffffff, 0x666666, 3));
    const cube = new THREE.Mesh(
      new THREE.BoxGeometry(0.3, 0.3, 0.3),
      new THREE.MeshStandardMaterial({color: 0x4285f4}));
    // 사용자 앞, 편한 높이에 배치 (단위=미터)
    cube.position.set(0, xb.user.height - 0.3, -xb.user.objectDistance);
    this.add(cube);              // this 가 곧 Object3D
    this.cube = cube;
  }
  onSelectEnd() {                // 데스크톱 클릭 OR XR 핀치
    this.cube.material.color.set(Math.random() * 0xffffff);
  }
}
xb.add(new MainScript());
xb.init(new xb.Options());       // 엔진 + 렌더 루프 부팅

패턴 2 — 기능은 Options의 enable*()로 켠다

손 추적이 필요하면 options.enableHands(), 깊이 인식은 enableDepth(), AI는 enableAI(). 내부를 만지지 않고 스위치를 켜듯 기능을 조립한다. 이 체이닝 방식 덕에 "이 앱이 무슨 능력을 쓰는가"가 코드 상단에서 한눈에 보인다.

const options = new xb.Options();
options.enableUI();              // 공간 UI + 조준점
options.enableHands();           // 손 관절 추적
options.enableGestures();        // 핀치/주먹/포인트/스프레드/엄지척
options.enableDepth();           // WebXR 깊이 센싱 + 깊이 메시
options.enablePlaneDetection();  // 바닥·벽 등 평면 인식
options.enableObjectDetection(); // 물체 인식(카메라 권한도 함께)
options.enableAI();              // Gemini/OpenAI → xb.ai
xb.init(options);

// 예외: 물리는 enablePhysics()가 없다 — RAPIER를 직접 주입
import RAPIER from '@dimforge/rapier3d-simd-compat';
options.physics.RAPIER = RAPIER; // 이 대입이 물리를 켠다

패턴 3 — Reality Model: user · world · agents

논문이 제시하는 개념 모델은 "Reality Model"이다. 현실을 세 가지 1급 요소로 추상화한다 — xb.user(사용자: 키·손·시선·선택 상태), xb.world(세계: 인식된 평면·물체·메시), 그리고 AI agents. 여기에 "상호작용 문법(interaction grammar)"을 더해, 명시적 이벤트(클릭·핀치 = onSelectStart)와 암묵적 의도(제스처·시선·음성)를 구분해 다룬다.

// 사용자·AI를 코드로 다루기
xb.user.height;                  // 사용자 눈높이(미터)
xb.user.isSelectingAt(object);   // 이 물체를 선택 중인가?
xb.user.isPointingAt(object);    // 이 물체를 가리키나?(호버)

if (xb.ai.isAvailable()) {       // AI는 항상 가드!
  const res = await xb.ai.query({prompt: '먼지에 관한 하이쿠를 써줘.'});
  // res.text 에 답. 멀티모달·Gemini Live 세션도 지원
}

패턴 4 — 두 개의 UI 시스템(의도적 분리)

공간 UI가 두 갈래다. 코어 UI(xb.SpatialPanel + .addGrid()/.addRow()/.addButton())는 가볍고 의존성이 없어 HUD·메뉴에 좋다. uiblocks 애드온(@pmndrs/uikit 기반)은 flexbox·그라디언트·그림자까지 되는 풀 레이아웃이다. 문서는 "둘을 한 패널에 섞지 말라"고 못박는다. 필요에 따라 골라 쓰는 구조.

5디렉토리 구조 해부

"src의 서브시스템 한 폴더 = 한 능력" + 예제 3종(samples/demos/templates) + AI용 skills.

세 덩어리로 나눠 읽으면 명료하다.

① SDK 본체 src/. 규칙이 단순하다 — "한 폴더 = 한 능력(서브시스템)". core/가 엔진의 뼈대(Core·Script·Options)이고, 나머지 input/world/depth/ai/ui/physics…가 각각 하나의 기능을 담당한다. 새 기능을 추가할 때도 "폴더 만들고 → Options에 enable*() 붙이고 → 배럴에 export"라는 정형 절차(AGENTS.md에 명시)를 따른다.

② 예제 3종 세트. 학습 동선이 계단식이다. templates/는 최소 뼈대(복붙 시작점), samples/는 기능 하나씩 보여주는 예제, demos/는 완성형 쇼케이스(Ballpit 물리, XR-Emoji, Gemini Icebreakers). 막히면 이 실제 파일에서 패턴을 복사하라는 게 공식 가이드다.

③ AI를 위한 문서 계층. 이 저장소의 독특함 — 루트에 AGENTS.md·CONTEXT.md·GEMINI.md·CLAUDE.md가 있고, skills/에는 xb-core·xb-ui·xb-hands·xb-gestures·xb-depth·xb-world·xb-ai·xb-physics·xb-simulator·xb-sound·xb-netblocks·xb-uiblocks·xb-modelviewer·xb-lipsync·xb-testing 15개 스킬이 있다. 사람과 AI 에이전트 모두를 독자로 상정한 구조다.

6학습 포인트 (기술별)

이 저장소에서 "무엇을 배울 수 있는가" — 개념 → 코드 위치 → 실습 아이디어.

7하드웨어 / 시스템 요구사항

헤드셋은 선택 — 크롬만 있으면 시뮬레이터로 대부분 학습 가능. AI만 키 필요.

8직접 해볼 수 있는 실습 과제

난이도별로 손을 움직여 보는 5가지. (전부 데스크톱 시뮬레이터로 가능)

입문 ★☆☆

<!-- index.html 의 <head> 에 importmap -->
<script type="importmap">
{ "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@0.184.0/build/three.module.js",
    "xrblocks": "https://cdn.jsdelivr.net/gh/google/xrblocks@build/xrblocks.js"
}}
</script>

git clone --depth=1 https://github.com/google/xrblocks.git
cd xrblocks && npm ci
npm run dev        # 워치 빌드 + http://127.0.0.1:8080
# 브라우저에서 samples/demos 를 열고, ?formFactor=desktop 로 시뮬레이터 강제

중급 ★★☆

고급 ★★★

9관련 기술 심화 학습 로드맵

4주 코스 — three.js/WebXR 기초부터 AI·물리·애드온까지.

10핵심 키워드 사전

이 프로젝트를 읽을 때 반복 등장하는 용어 정리.

11참고 링크

원본을 직접 확인하고 싶을 때.