Learning
레슨 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
position3D 위치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-modelGLTF 로딩src (에셋 ID 또는 URL)
obj-modelOBJ 로딩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에서 검증된 컴포넌트를 찾을 수 있습니다. 프로젝트에 필요한 기능이 이미 컴포넌트로 존재하는지 먼저 확인하면 개발 시간을 크게 줄일 수 있습니다.