Motion Canvas 에디터 워크플로우

Motion Canvas 에디터의 효율적인 사용법 — 변수 슬라이더, 프레임 단위 디버깅, Vite 설정, 트러블슈팅 — 을 다룬다.

🎛️ 에디터 UI 구조

┌─────────────────────────────────────────────────┐
│  Toolbar (RENDER, Settings)                     │
├──────────┬──────────────────────┬───────────────┤
│ Scenes   │                      │ Inspector     │
│ (트리)   │      Canvas          │ (속성/변수)   │
│          │                      │               │
├──────────┴──────────────────────┴───────────────┤
│  Timeline + Playhead + Variables Slider        │
└─────────────────────────────────────────────────┘

영역	기능
Scenes (좌)	Scene 트리, 추가/삭제, 순서
Canvas (중앙)	실시간 미리보기, 클릭으로 노드 선택
Inspector (우)	선택 노드 속성, 변수 슬라이더
Timeline (하단)	시간축, 재생/이동, frame 단위
Variables (하단 우)	`createSignal`/`createVariable` 값 실시간 변경

🔧 변수 — 디자인 반복의 핵심

`createVariable` (에디터 슬라이더)

import {createVariable} from '@motion-canvas/core';

export default makeScene2D(function* (view) {
  const color = createVariable('#3b82f6');
  view.add(<Circle size={200} fill={color} />);
});

에디터에 슬라이더 등장. 드래그하면서 색상·크기·위치 실시간 변경 → 코드 수정 없이 디자인 반복.

`createSignal` (시간 의존)

import {createSignal} from '@motion-canvas/core';

const scale = createSignal(1);
view.add(<Circle size={200} scale={scale} />);
yield* scale(2, 1);

Signal은 시간 흐름에 따라 값이 변하는 경우, Variable은 사용자가 슬라이더로 직접 조정.

비교

	Variable	Signal
변경 주체	사용자 (에디터 슬라이더)	시간 (코드)
용도	디자인 반복 / 파라미터화	애니메이션 흐름
저장	project.ts (기본값)	Scene 내부
API 연동	가능 (URL query)	❌

Variable은 [?color=%23ef4444] 같은 URL 파라미터로도 공유 가능 — 디자인 리뷰에 강력.

⏱️ 타임라인 단축키

키	동작
`Space`	재생/정지
`←` / `→`	1초 뒤/앞
`Shift+←/→`	10초 뒤/앞
`Home` / `End`	시작/끝
`Ctrl+Click`	캔버스: 해당 시점으로 점프
`Ctrl+R`	Scene 재로드

🐞 디버깅 패턴

1) `console.log` + DevTools

export default makeScene2D(function* (view) {
  console.log('Scene start');
  const circle = createRef<Circle>();
  view.add(<Circle ref={circle} size={100} fill={'#3b82f6'} />);
  console.log('Circle added', circle());
});

F12 → Console 탭에서 Scene 재실행마다 로그 확인.

2) 로거 API

import {logger} from '@motion-canvas/core';

logger.info('Processing frame');
logger.warn('Deprecated API used');
logger.error('Cannot find node');

에디터 우측 하단 로그 패널에도 동시 출력.

3) 프레임 단위 멈춤

타임라인의 빨간 마커(브레이크포인트)로 특정 시점 멈춤 → 변수 상태 검사.

yield* circle().size(400, 1);
// ↑ 여기서 멈추고 circle().size() 확인 가능

⚙️ Vite 설정 (프로젝트 단위)

// vite.config.ts
import {defineConfig} from 'vite';
import motionCanvas from '@motion-canvas/vite-plugin';

export default defineConfig({
  plugins: [
    motionCanvas({
      project: './src/project.ts',
      output: './output',
    }),
  ],

  // 일반 Vite 옵션
  server: {
    port: 9013,           // 에디터 포트
    open: true,           // 자동 브라우저 오픈
  },
});

일반 Vite 옵션 + Motion Canvas 플러그인 옵션을 함께 사용.

🎨 테마 / 외관

@motion-canvas/2d는 다크/라이트 자동 반응. CSS 커스텀:

// project.ts
import {makeProject} from '@motion-canvas/core';

export default makeProject({
  scenes: [example],
  background: '#0a0a0a',   // 캔버스 배경
});

Inspector의 컬러 피커에서 색 즉시 확인 가능.

🔄 핫 리로드

코드 수정 → Ctrl+S → 자동 Scene 재로드 (Vite HMR). 변수 슬라이더 값은 유지.

가끔 HMR이 꼬이면 Ctrl+R (브라우저 새로고침)으로 강제 리로드.

🐛 자주 보이는 에디터 에러

증상	원인	해결
Scene 안 보임	import 경로 오타	`?scene` 접미사 확인
에디터 9013 안 열림	포트 충돌	Vite 설정 `port` 변경
노드 회색	부모가 `opacity={0}`	Inspector에서 확인
렌더 안 됨	output 경로 권한	절대 경로로 변경
타입 에러	TS 버전	`@motion-canvas/*` 최신 확인

🚀 다음 단계

작업	가이드
렌더링	Motion Canvas 렌더링
외부 에셋	Motion Canvas 확장 & 통합
도움말	Motion Canvas 플랫폼 & 도움말

🔗 공식 리소스

Configuration: https://motioncanvas.io/docs/getting-started/configuration
Logging: https://motioncanvas.io/docs/logging
Variables: https://motioncanvas.io/docs/signals (Signal 인접)

상위 문서: ← Motion Canvas 사용 가이드 출처: Motion Canvas 공식 문서 — Configuration + Logging 한글화 (2026-07-30) 공급사: Motion Canvas (motion-canvas 조직)

변경 이력

날짜	변경
2026-07-30	초안 작성 — 에디터 UI + Variable/Signal + 디버깅 + 트러블슈팅