레슨 8 / 8·4개 토픽
A-Frame 레퍼런스
내장 프리미티브 레퍼런스
A-Frame은 자주 사용하는 3D 도형과 요소를 HTML 태그로 제공합니다. 각 프리미티브는 geometry + material 컴포넌트의 축약형이며, 해당 속성을 직접 지정할 수도 있습니다. 아래는 A-Frame에서 제공하는 주요 프리미티브와 핵심 속성 목록입니다.
| 프리미티브 | 설명 | 핵심 속성 |
|---|---|---|
| <a-box> | 직육면체 | width, height, depth, color, src |
| <a-sphere> | 구 | radius, segments-width, segments-height, color |
| <a-cylinder> | 원기둥 | radius, height, segments-radial, open-ended |
| <a-plane> | 평면 | width, height, color, src, repeat |
| <a-circle> | 원형 평면 | radius, segments, theta-start, theta-length |
| <a-ring> | 링(도넛 평면) | radius-inner, radius-outer, segments-theta |
| <a-torus> | 토러스(도넛) | radius, radius-tubular, segments-radial |
| <a-cone> | 원뿔 | radius-bottom, radius-top, height |
| <a-dodecahedron> | 정십이면체 | radius |
| <a-octahedron> | 정팔면체 | radius |
| <a-tetrahedron> | 정사면체 | radius |
| <a-icosahedron> | 정이십면체 | radius, detail |
| <a-sky> | 360도 배경 | color, src, radius |
| <a-text> | 3D 텍스트 | value, color, width, align, font |
| <a-image> | 이미지 평면 | src, width, height |
| <a-video> | 비디오 평면 | src, width, height, autoplay |
| <a-gltf-model> | GLTF 3D 모델 | src |
| <a-light> | 조명 | type, color, intensity, position |
| <a-camera> | 카메라 | fov, near, far, look-controls |
| <a-cursor> | 커서 | fuse, fuseTimeout, rayOrigin |
내장 컴포넌트 레퍼런스
| 컴포넌트 | 설명 | 주요 속성 |
|---|---|---|
| geometry | 형태 정의 | primitive, width, height, depth, radius 등 |
| material | 재질/외형 | color, src, metalness, roughness, opacity, shader |
| position | 3D 위치 | x y z (예: "0 1.6 -3") |
| rotation | 회전 | x y z (도 단위, 예: "0 45 0") |
| scale | 크기 배율 | x y z (예: "1 1 1") |
| visible | 가시성 | true / false |
| animation | 애니메이션 | property, to, dur, loop, easing, startEvents |
| light | 조명 | type, color, intensity, distance, decay |
| camera | 카메라 | active, fov, near, far |
| look-controls | 시점 제어 | enabled, reverseMouseDrag, touchEnabled |
| wasd-controls | 키보드 이동 | acceleration, enabled, fly |
| cursor | 선택 커서 | fuse, fuseTimeout, rayOrigin |
| raycaster | 레이캐스팅 | objects, far, near, interval |
| sound | 오디오 | src, autoplay, loop, volume, on |
| shadow | 그림자 | cast, receive |
| fog | 안개 (씬 속성) | type, color, density, near, far |
| gltf-model | GLTF 로딩 | src (에셋 ID 또는 URL) |
| obj-model | OBJ 로딩 | obj, mtl |
자주 쓰는 패턴과 레시피
html
<!-- 패턴 1: 이벤트 기반 상태 전환 -->
<a-box
class="clickable"
color="#e74c3c"
animation__grow="property: scale; to: 1.5 1.5 1.5; dur: 300; startEvents: mouseenter"
animation__shrink="property: scale; to: 1 1 1; dur: 300; startEvents: mouseleave"
animation__spin="property: rotation; to: 0 360 0; dur: 1000; startEvents: click"
></a-box>
<!-- 패턴 2: 카메라 + 마우스 커서 (데스크톱) -->
<a-entity camera look-controls wasd-controls position="0 1.6 0">
<a-entity cursor="rayOrigin: mouse" raycaster="objects: .clickable"></a-entity>
</a-entity>
<!-- 패턴 3: 카메라 + 시선 커서 (VR) -->
<a-entity camera look-controls position="0 1.6 0">
<a-entity
cursor="fuse: true; fuseTimeout: 1500"
raycaster="objects: .clickable"
position="0 0 -1"
geometry="primitive: ring; radiusInner: 0.02; radiusOuter: 0.03"
material="color: white; shader: flat"
></a-entity>
</a-entity>
<!-- 패턴 4: 반복 배치 (JavaScript) -->
<script>
const scene = document.querySelector('a-scene');
for (let i = 0; i < 10; i++) {
const el = document.createElement('a-sphere');
el.setAttribute('position', `${i * 2 - 9} 1 -5`);
el.setAttribute('color', `hsl(${i * 36}, 80%, 60%)`);
el.setAttribute('radius', '0.5');
scene.appendChild(el);
}
</script>
<!-- 패턴 5: 사운드 재생 -->
<a-entity
sound="src: url(click.mp3); on: click; volume: 0.5"
class="clickable"
geometry="primitive: box"
material="color: #3498db"
position="0 1 -3"
></a-entity>유용한 서드파티 컴포넌트
- •aframe-environment-component — 한 줄로 자연 환경 생성 (forest, desert 등 17개 프리셋)
- •aframe-extras — 애니메이션 믹서, 경로 이동, 물리 엔진 통합
- •aframe-physics-system — 중력, 충돌, 강체 물리 시뮬레이션
- •aframe-particle-system — 불, 연기, 눈 등 파티클 효과
- •aframe-event-set-component — 이벤트 발생 시 속성 일괄 변경
- •aframe-teleport-controls — VR 컨트롤러 기반 텔레포트 이동
- •aframe-super-hands-component — VR 손 인터랙션 (잡기, 늘리기)
- •networked-aframe — 멀티유저 VR 경험 (WebRTC 기반)
💡
A-Frame 공식 문서(aframe.io/docs)는 모든 프리미티브와 컴포넌트의 속성을 상세히 설명합니다. 서드파티 컴포넌트는 npm에서 검색하거나 aframe.io/aframe-registry에서 검증된 컴포넌트를 찾을 수 있습니다. 프로젝트에 필요한 기능이 이미 컴포넌트로 존재하는지 먼저 확인하면 개발 시간을 크게 줄일 수 있습니다.