fayazara/robot-heads

robot-heads – React용 애니메이션 3D 로봇 헤드

이것은 무엇인가

• <RobotHead> React 컴포넌트를 제공하는 npm 패키지입니다. 이 컴포넌트는 2D 캔버스(WebGL 없음)에 양식화된 로봇 머리를 그리고, 에이전트의 상태(대기, 생각 중, 듣기 등)를 반영하여 애니메이션을 만듭니다.

주요 기능

• 네 가지 기하학적 모양 – 직사각형, 정사각형, 원, 육각형 – 모두 동일한 화면, 안테나, 귀, 동작을 공유합니다.
• 상태 기반 얼굴 – 각 상태(대기, 생각 중, 검색 중, 듣기 중, 말하기 중, 작업 중, 행복, 오류, 수면 중)에는 고유한 LED 매트릭스 얼굴, 동작 패턴 및 안테나 표시등 색상이 있습니다.
• 사용자 정의 가능한 모양 – 쉘, 트림, 화면의 색상 속성; 크기(픽셀 단위); 애니메이션 속도; 선택적 안테나, 바닥 그림자, 여러 헤드를 비동기화하는 seed가 있습니다.
• 상호 작용 – interactive(기본값)일 때 헤드는 마우스 포인터를 따라가고 클릭하면 점프/회전합니다. prefers-reduced-motion과 paused 속성을 존중합니다.
• 성능 친화적 – 모든 헤드가 단일 애니메이션 루프를 공유하며, 탭이 숨겨지면 일시 중지됩니다. 동일한 모양/크기의 헤드는 베이크된 텍스처를 재사용합니다.
• 접근성 – 캔버스는 role="img"와 현재 상태를 설명하는 aria-label을 받습니다.

작동 방식

• 헤드 지오메트리는 모서리가 둥근 볼록 다각형으로 생성된 후 3D 스타일 메시(귀, 안테나 칼라)로 선반 가공됩니다. 각 프레임에서 메시가 변환되고, 뒷면이 컬링되고, 간단한 스튜디오 조명 설정(키, 필, 림, 스카이 돔)과 필름 톤 곡선으로 조명됩니다.
• 전면 화면은 LED 매트릭스이며, 얼굴은 선명하게 렌더링된 후 글로우 효과를 위해 블룸 처리됩니다.
• 모든 그리기는 일반 HTML <canvas> 요소에서 수행되어 무거운 WebGL 종속성을 피합니다.

일반적인 사용법

import { RobotHead } from 'robot-heads';

function Agent({status}: {status: 'idle' | 'thinking' | 'speaking'}) {
  return <RobotHead state={status} size={160} />;
}

프로퍼티를 사용하여 모양, 색상, 속도를 변경하고 안테나, 그림자, 상호 작용을 활성화/비활성화할 수 있습니다.

개발 및 플레이그라운드

• 리포지토리는 pnpm 워크스페이스이며, 라이브러리는 src/에 있고, 대화형 플레이그라운드는 site/(Vite + Cloudflare Worker)에 있습니다. pnpm run dev를 실행하면 플레이그라운드가 시작되고 라이브러리 변경 사항이 핫 리로드됩니다.
• pnpm run build로 dist/에 배포 파일을 생성합니다.

라이선스

• MIT 라이선스, 저자: Fayaz Ahmed.

사용 대상

• AI 챗봇, 음성 비서 또는 대화형 에이전트 UI를 구축하는 프런트엔드 개발자로, 에이전트의 현재 활동에 대한 가볍고 애니메이션된 시각적 신호를 원하는 사람.

---

모든 세부 사항은 리포지토리의 README에서 직접 가져왔습니다.