Communitygithub.com

애니메이션(anim) 제작

짧은 브리핑을 바탕으로 노래 가사와 비트를 브라우저에서 애니메이션화하는 단일 YAML 모듈(anim)을 생성합니다. Canvas2D, SVG, DOM 또는 Three.js를 지원하며, 가사 시각화 도구나 리릭 애니메이션 모듈을 만들거나, 포팅/스타일 변경/수정할 때 사용합니다.

애니메이션(anim) 제작란 무엇인가요?

이 스킬은 '애니메이션(anim)'이라는 단일 YAML 파일을 작성하여 노래의 가사와 비트를 브라우저에서 시각적으로 표현하는 작업을 자동화합니다. anim 파일은 네 가지 주요 섹션(t, j, s, h)으로 구성되며, 호스트 플레이어는 전역 G API를 통해 음절, 단어, 줄, 섹션, 비트 데이터를 제공합니다. 개발자는 디자인 브리핑을 바탕으로 이 파일을 작성해야 하며, 특히 '프레임은 재생 시간의 순수 함수여야 한다'는 핵심 규칙을 준수해야 합니다. 이는 seek/일시 정지/크기 조정/테마 변경 상황에서도 정확하고 가독성 있으며 아름다운 출력을 보장합니다. 지연된 렌더링, WebGL, 접근성, 다양한 언어(한글, CJK, RTL 등) 지원을 위한 가이드라인이 포함되어 있으며, g-lib 라이브러리의 유틸리티 함수를 최대한 재사용하도록 권장합니다. 주로 Claude Code, Cursor, Codex와 같은 AI 에이전트 도구에서 사용되며, 셸 환경에서 검증 및 테스트 도구를 활용하거나 셸 없이도 텍스트 템플릿과 체크리스트를 통해 작업할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/prjctg/animr-skill/tree/HEAD/skill

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

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

문서

애니메이션(anim) 제작은(는) 무엇을 하나요?

애니메이션(anim) 은 하나의 파일, <kebab-name>@<major>.<minor>.yaml이며, 정확히 네 개의 키(t(리터럴 c), j(ES 모듈), s(CSS), h(HTML/SVG))로 구성됩니다. 호스트 플레이어는 전역 G API를 통해 노래의 음절, 단어, 줄, 섹션, 비트를 전달합니다. 여러분의 임무는 브리핑을 바탕으로 seek/일시정지/크기조정/테마 변경 상황에서 올바르게 동작하고, 가독성이 있으며 아름다운 파일 하나를 만드는 것입니다. 아래 경로는 이 skill/ 디렉토리를 기준으로 합니다.

가장 중요한 규칙

  1. 프레임은 재생 시간의 순수 함수입니다. render(t)는 재생 시간이 t에 도달했든 사용자가 스크럽했든 동일한 그림을 그려야 합니다. Math.random, Date.now, 누적 통합, seek 시 건너뛰는 "지난 프레임 상태"는 사용할 수 없습니다. 모든 것은 노래 데이터, 시드(seed) 및 t에서 파생되어야 합니다.
  2. 두 부분으로 나뉩니다. 주석 배너 위에 DOM에 의존하지 않는 순수한 반쪽(buildPlan, frameAt, 헬퍼; 단위 테스트 가능)을 작성하고, 그 아래에 얇은 브라우저 반쪽(export default function (G, shadowRoot, config))을 작성하여 와이어링과 드로잉만 수행합니다. guides/architecture.md를 참조하세요.
  3. default에서 등록하고, INIT에서 노래 데이터를 읽습니다. G.on / G.off / G.onFrame은 default 내부에서만 사용합니다. G.map / forEach / lookup / iterator / relayout은 INIT이 발생한 후(INIT 핸들러 또는 이후의 render 같은 콜백)에만 사용하며, default 자체에서는 절대 사용하지 않습니다. 재생을 위해 G.on(G.TYPE.TICK, render)로 구독하고, G.onFrame({ render, reset })은 SEEK/PLAY/PAUSE/RESIZE 및 UNINIT를 처리합니다.
  4. G.dispose / G.listen으로 정리합니다. default에서 반환된 함수는 무시됩니다. WebGL(forceContextLoss), 리스너, 타이머, 카메라를 해제하세요.
  5. 색상은 c.v가 아닌 CSS에 있습니다. :host에 밝은 값, [data-bs-theme=dark] { }에 어두운 재정의를 배치합니다. 캔버스는 g-lib cssColors로 읽어옵니다. 두 테마 모두 의도적으로 보여야 합니다.
  6. g-lib가 이미 제공하는 기능은 직접 구현하지 마세요(clamp, lerp, easing, 시드 RNG, 캔버스 맞춤, 스프링, 텍스트 레이아웃, 풀 등). 정확한 태그 핀(exact-tag pin) 에서 임포트하고, 헬퍼를 작성하기 전에 pitfalls/dont-hand-roll.md와 spec/g-lib.md를 확인하세요.
  7. 가독성이 효과보다 우선합니다. 활성 음절은 밝은 테마와 어두운 테마, 휴대폰과 노트북, 긴 줄, CJK, RTL, 미얀마어에서도 읽을 수 있어야 합니다. 큰 섬광은 3Hz 미만으로 유지하세요(guides/accessibility.md).
  8. 적은 수의 타입화된 옵션. c와 cSchema는 일반 리터럴이며, 각 옵션은 시각적으로 눈에 띄는 효과가 있어야 합니다.

워크플로우 (저장소 도구 사용)

  1. 브리핑. guides/design-brief.md에서 디자인 브리핑을 작성합니다: 하나의 강력하고 물리적인 그림; 메커니즘; 어떤 이벤트가 무엇을 구동하는지(동기화 맵); 구조(절/후렴/비트); 가독성 계획; 옵션; 함정. 선택 테이블을 참고하여 백엔드를 선택합니다. 가독성을 유지할 수 없는 아이디어는 거절합니다.
  2. 스캐폴드. npm run new -- <name> --backend canvas2d|svg|dom|three (또는 templates/<backend>.yaml을 수동으로 복사하고 __NAME__을 대체).
  3. 한 번 읽어보세요: spec/module-format.md, pitfalls/general.md, 백엔드에 해당하는 pitfalls/backends.md 섹션, pitfalls/dont-hand-roll.md. 아래 라우팅 테이블을 통해서만 다른 문서를 엽니다.
  4. 구현 먼저 순수한 반쪽(시간→상태), 그다음 얇은 브라우저 반쪽을 구현합니다.
  5. 검증. npm run validate -- anims/<file>.yaml. 모든 오류를 수정하고, 모든 경고는 문서 블록(docblock)에서 정당화하거나 수정합니다.
  6. 확인. npm run check -- anims/<file>.yaml은 13개의 엣지 케이스 노래를 헤드리스로 마운트하고, 적합성 테이블을 점수화하고, PNG를 out/<name>/에 씁니다. PNG를 엽니다 (휴대폰/노트북, 밝은/어두운). 보기 흉하거나 읽을 수 없는 프레임 위에 녹색 테이블이 있으면 실패입니다. seek 순수성 행에서 WARN이 발생하면 그림이 히스토리에 의존한다는 뜻입니다: 수정하거나 문서 블록에서 정당화하세요 (의도적인 시뮬레이션).
  7. 미리보기 (선택 사항). npm run preview -- anims/<file>.yaml로 재생, 스크럽, 테마 전환, 옵션 조정을 할 수 있습니다.
  8. 리뷰 guides/quality-rubric.md (20개 질문)에 따라 검토한 후, 하나의 YAML 파일과 짧은 보고서(파일명, 최종 확인 테이블, 브리핑에서 열어둔 결정 사항, 의도적으로 수행하지 않은 작업)를 제공합니다. out/ 또는 테스트 하네스는 포함하지 마세요.

도구 없는 모드 (채팅 모델, 셸 없음)

2, 5-7단계를 건너뜁니다. 일치하는 템플릿 텍스트로 시작하고, 추론 과정에서 디자인 브리핑을 작성한 다음, pitfalls/general.md, 백엔드 섹션, 20개 질문 루브릭을 작성한 코드와 한 줄씩 비교 검토한 후 답변하세요. 하나의 YAML 파일만 펜스 블록으로 출력하고, 실행하지 않고 확인할 수 없는 루브릭 항목(seek 순수성, 테마 전환, 크기 조정)을 언급하세요.

라우팅 테이블: 트리거가 적용될 때만 문서 열기

작업 중...읽을 문서
무엇을 구축할지 결정; 백엔드 선택guides/design-brief.md
파일 레이아웃; 단계 이름 지정; 문서 블록 작성guides/architecture.md
G.* 호출, 이벤트 옵션 또는 ID 범위 사용spec/events.md, spec/event-shapes.md, spec/g.d.ts
옵션, 색상, 테마 추가spec/config.md
시간 유틸리티, 텍스트 측정, 캔버스 헬퍼, 라이프사이클 사용spec/utilities.md
줄을 표시 줄로 분할, 텍스트 줄 바꿈spec/relayout.md, guides/patterns-text.md
음절/줄/비트에 반응; 사전 생성; 일시 정지; 스프링guides/patterns-timing.md
텍스트 맞춤, 강조 또는 스타일 지정; 비라틴 스크립트guides/patterns-text.md
렌더링 코드 작성 (DOM, SVG, 캔버스, Three.js, 시뮬레이션, 레이어)guides/patterns-render.md, pitfalls/backends.md
카메라, 지형, 무리, 패킹, 절차적 3Dguides/techniques.md, pitfalls/techniques.md
사진 또는 카메라 사용spec/image-input.md
게임 구축 (autoPlay false, 점수, 상태)guides/games.md
g-lib 헬퍼 사용spec/g-lib.md
깜박임, 움직임, 대비에 대해 확신이 없음guides/accessibility.md
완료guides/quality-rubric.md

최소 형태 (이것을 배포하지 말고 템플릿에서 시작하세요)

"t": |-
  c
"j": |
  import { hash01 } from 'https://cdn.jsdelivr.net/gh/prjctg/[email protected]/index.js';
  /* [email protected]: <한 줄>
   * 1. <번호가 매겨진 디자인 주장: 메커니즘과 그것이 거부하는 유혹적인 오답> */
  export function frameAt(plan, t) { /* 순수 함수 */ }
  /* 브라우저 반쪽. 이 줄 위의 모든 것은 의도적으로 DOM에 의존하지 않습니다. */
  export default function (G, shadowRoot, config) {
    const cfg = G.cfg(config, { channel: G.cfg.int(0) });
    let ready = false;
    const render = (t) => { if (!ready) return; /* frameAt(plan, t) 그리기 */ };
    G.on(G.TYPE.INIT, () => { ready = true; /* 여기서 G.map(...) 사용 가능 */ });
    G.on(G.TYPE.TICK, render);
    G.onFrame({ render, reset() { ready = false; } });
  }
  export const c = { v: { fadeMs: 150 }, m: [{ s: 'fadeMs', t: 'fadeMs' }] };
  export const cSchema = [{ i: 'fadeMs', n: '페이드 (ms)', t: 'int', mn: 0, mx: 2000 }];
"s": |
  :host { display: block; --ink: var(--inkColor, #111); }
  [data-bs-theme=dark] { --ink: var(--inkColor, #eee); }
"h": |
  <canvas id="c"></canvas>

j, s, h는 원시 텍스트(백틱이나 따옴표로 감싸지 않음)를 담습니다. t는 |-를 사용합니다. 파일 이름에 버전이 포함됩니다. 게시된 버전을 제자리에서 편집하지 마세요.

관련 스킬