Blockshot 사용 설명서

123크게 보기 ↗

1크게 보기 ↗

작업은 이 브라우저에 자동 저장됩니다. 다른 컴퓨터로 옮기거나 백업하려면 마지막 단계의 프로젝트 저장으로 파일을 받아 두세요. Chrome 또는 Edge 최신 버전을 권장합니다.

12345678크게 보기 ↗

팁아이콘의 뜻이 궁금하면 마우스를 올려 보세요. 이름과 단축키, 짧은 설명이 나옵니다. 하고 싶은 일이 있는데 어디 있는지 모르겠으면 ⌘K(Windows Ctrl+K)를 누르고 적어 보세요.

123크게 보기 ↗

• 방 안에서는 가구가 가까운 벽에 붙고, 문·창문·거울은 벽에 걸립니다.
• 내 3D 모델(GLB)도 불러와 소품처럼 쓸 수 있습니다(에셋 패널 아래).
• 공간(방 크기·문·창 위치, 거리, 바닥)은 아웃라이너 맨 위의 장면 · 공간을 눌러 바꿉니다.

1234크게 보기 ↗

팁툴 레일의 스냅(S)이 켜져 있으면 0.1 m · 15° 단위로 딱딱 맞습니다. 잘못 옮겼으면 ⌘Z로 되돌리세요.

12크게 보기 ↗

버튼 하나로 추가하는 동작

• 앉기 · 일어서기 — 의자나 소파를 고르면 걸어가 방향을 맞추고 앉습니다.
• 연기 — 손 흔들기·끄덕이기·박수 같은 몸짓, 손가락 모양, 들기(전화·마시기·읽기), 뻗기(대상 쪽으로 손 내밀기).
• 자동차 — 소품(차)을 선택하고 달릴 길을 찍습니다. 다른 차가 따라오게 하거나 카메라를 차에 붙일 수 있습니다.
• 라이브 녹화(Shift+R) — 게임하듯 WASD(Shift 달리기)로 시간 제한 없이 움직입니다. Space로 끝내면 엔진 동작으로 반복 재생되고, I·O로 쓸 구간만 골라 Enter로 넣습니다(아래 녹화 설명).

팁추가한 동작은 속성 패널의 동작 목록과 타임라인의 막대로 보입니다. 시작 시간·길이를 고치거나 지울 수 있습니다.

123456크게 보기 ↗

가장 쉬운 방법

1. 타임라인을 0초에 두고 인물을 시작 자리에 놓은 뒤 K.
2. 3초로 옮겨 인물을 끝 자리로 옮깁니다 — 키가 있는 값은 움직이는 순간 그 시간에 키가 찍힙니다.
3. Space로 재생해 보세요. 0→3초 사이를 이동합니다.

라이브 녹화로 동선 만들기

1. 움직일 인물(또는 카메라)을 선택하고, 녹화를 시작할 시간에 재생 헤드를 둔 뒤 Shift+R.
2. 게임하듯 움직입니다 — 인물은 WASD(보는 방향 기준), Shift로 달리기. 장면 길이에 상관없이 원하는 만큼, 화면 위 REC 시계가 녹화 시간입니다.
3. Space로 끝내면 녹화한 움직임이 그 자리에 들어가 엔진 동작으로 반복 재생됩니다 — 녹화 중엔 대충 움직여도 발 디딤·출발·정지는 엔진이 다시 만듭니다.
4. 아래 테이크 막대에서 쓸 구간을 고릅니다: 재생 헤드에서 I(여기서 시작)·O(여기서 끝), 또는 막대 양 끝 끌기. 넣을 위치와 동선(걷기 액션 — 나중에 경유점 수정)/키프레임(움직인 그대로)을 고르고 Enter.
5. 보관만을 누르면 장면에서 빼고 테이크만 남깁니다. 남겨 둔 테이크는 타임라인의 🎞 메뉴에서 골라 다른 구간을 다시 넣을 수 있습니다. 녹화 전체는 ⌘Z 한 번으로 취소됩니다.

팁팔·다리 같은 관절도 키를 찍을 수 있습니다. 인물의 팔을 클릭하면 관절에 회전 기즈모가 붙고, 돌리는 순간 그 뼈의 키가 찍힙니다(속성 패널 포즈 · 뼈 키프레임).

1234크게 보기 ↗

1234크게 보기 ↗

팁카메라가 움직이게 하려면 7단계처럼 카메라 위치·렌즈에 키를 찍으면 됩니다(돌리·트럭·줌).

123456크게 보기 ↗

크게 보기 ↗

자주 하는 편집

• 원하는 곳에서 자르기 — 면도날(B)로 클립을 클릭. 재생 헤드 위치는 ⌘B.
• 중간 덜어내기 — 조각을 선택하고 Delete(뒤가 당겨짐). 또는 I·O로 구간을 찍고 Delete.
• 붙여넣기 — ⌘C/⌘X 후 재생 헤드를 옮기고 ⌘V. 클립 중간이면 갈라서 끼워 넣습니다.
• 되돌리기 — 모든 편집은 ⌘Z.

1234크게 보기 ↗

팁컷 앞뒤 카메라가 두 인물을 잇는 선(180° 축선)을 넘으면 그 컷 위에 ⚠ 180°가 뜹니다. 샷 패널에서 같은 쪽 카메라로 바꾸거나, 의도한 연출이라고 표시할 수 있습니다.

1234크게 보기 ↗

저장

• 작업은 자동 저장됩니다. 파일로 남기려면 파일 → 프로젝트 저장(⌘S) — .blockshot.json 하나에 장면 전체가 들어 있습니다.
• 렌더와 함께 프레임별 카메라 위치·렌즈 값(camera.json)도 받을 수 있습니다.

영상 렌더는 브라우저의 WebCodecs를 씁니다. Chrome·Edge 최신 버전에서 가장 안정적입니다.

크게 보기 ↗

내가 배치한 장면에 AI로 애니메이션만 추가하려면: 메뉴바의 링크 버튼(또는 파일 → 링크 복사)으로 장면이 통째로 들어 있는 링크를 복사해 AI에게 주세요(MCP의 load_link가 읽습니다). 배치는 그대로 두고 동작·카메라·샷만 추가되고, 결과 링크를 열면 새 프로젝트로 들어옵니다. 링크가 너무 길어 잘리면 프로젝트 저장 파일을 붙여넣으세요.

AI(ChatGPT, Claude, Gemini 등)에게 장면을 만들게 하고, 결과를 붙여넣어 손으로 다듬는 흐름입니다. 오른쪽 AI / 스크립트 탭에서 합니다.

A. 복사·붙여넣기 (가장 간단)

1. 새 장면 만들기 — 요청을 적고 프롬프트 복사를 눌러 AI에 붙여넣습니다. AI가 돌려준 JSON 또는 스크립트를 다시 앱에 붙여넣으면 검증 후 장면이 열립니다. 오류가 있으면 고쳐 달라고 할 수 있는 수정 프롬프트가 만들어집니다.
2. 배치한 장면에 애니메이션 추가 — 직접 배치한 장면은 그대로 두고 동작·카메라·샷만 AI가 추가합니다. 요청 입력란에서 @를 치면 장면의 인물·소품·동작 목록이 떠서 정확한 대상을 지정할 수 있습니다.
3. 동작은 이름(act3)으로 지정되므로 “@act3 를 2초 늦춰줘”처럼 일부만 수정할 수 있습니다.
4. 스크립트로 받으면 브라우저 안의 격리된 Worker에서 실행됩니다(메인 화면에서 실행되지 않습니다).

B. 코드로 연기 쓰기 (고급)

스크립트에서는 반복·리듬이 있는 연기를 시간의 함수로 쓸 수 있습니다.

const a = scene.actor("minsu", { at: [0, 0, 0] });
scene.sequence(1, () => {                       // 안의 모든 시작 시간이 +1초
  a.boneFn("head", { to: 4 }, (t) => [0, 25 * Math.sin(t * Math.PI), 0]);   // 고개 젓기
  a.boneFn("chest", { to: 4 }, (t) => [2 * noise(t * 1.5, 3), 0, 0]);       // 숨쉬기
});
scene.animate("camA", "position", { to: 3 }, (t) => [interpolate(t, [0, 3], [0, 2]), 1.6, 5 - 2 * spring(t)]);

자세한 API는 스크립트 API, 장면 형식은 장면 스펙, 기계가 읽는 스키마는 JSON Schema를 보세요.

MCP를 연결하면 AI가 복사·붙여넣기 없이 직접 장면을 만들고, 프리뷰 이미지로 결과를 확인하며 고친 뒤, 열어볼 링크를 줍니다. 링크를 열면 스튜디오에 새 프로젝트로 들어옵니다.

원격 MCP (설치 없음 · iPad/모바일 가능)

주소: https://blockshot-eta.vercel.app/api/mcp
인증: Authorization: Bearer <토큰>   (토큰이 설정된 경우)

Claude Code:
claude mcp add --transport http blockshot https://blockshot-eta.vercel.app/api/mcp --header "Authorization: Bearer <토큰>"

헤더 입력이 없는 클라이언트(예: claude.ai 커넥터)는 주소 끝에 ?token=<토큰>

• 도구: get_guide 사용법, run_script 스크립트 실행·검증, validate_spec, apply_addon, evaluate 정확한 수치 확인, preview PNG 미리보기(카메라/탑뷰), open_link 스튜디오 링크.
• 프리뷰는 막대 인형과 박스로 그린 도식이라 구도·자세·동선 확인용입니다. 최종 화질은 스튜디오에서 봅니다.
• 토큰은 서비스 운영자가 정한 값입니다. 서버에는 아무것도 저장되지 않습니다.

로컬 MCP (내 컴퓨터에서 실행 · MP4 렌더 가능)

같은 도구를 내 컴퓨터에서 돌리고, 추가로 render_still(진짜 3D 이미지)과 render_video(MP4 파일 저장)를 씁니다. 내 컴퓨터의 Chrome이 렌더하므로 서버 비용이 없습니다. Node 22+와 Chrome이 필요합니다.

1. AI가 알아서 설치(권장) — 원격 MCP만 연결해 두고 “MP4로 내보내 줘”라고 하면, 셸을 쓸 수 있는 AI(Claude Code 등)가 설치 방법을 안내받아 동의를 구한 뒤 파일 하나를 내려받아 등록합니다.
2. 직접 설치

mkdir -p ~/.blockshot && curl -fsSL https://blockshot-eta.vercel.app/mcp/blockshot-mcp.mjs -o ~/.blockshot/blockshot-mcp.mjs
claude mcp add blockshot-local -e BLOCKSHOT_URL=https://blockshot-eta.vercel.app -- node ~/.blockshot/blockshot-mcp.mjs

• 등록 후 MCP를 다시 읽어야(Claude Code는 새 세션이나 /mcp) 도구가 나타납니다.
• Chrome이 표준 위치에 없으면 환경변수 BLOCKSHOT_CHROME에 실행 파일 경로를 지정하세요. 소프트웨어 렌더링이라 짧은 영상도 수십 초~수 분 걸릴 수 있습니다.
• 결과는 ~/Blockshot/renders/에 저장되고(경로 지정 가능), H.264를 지원하지 않는 Chrome에서는 WebM이 됩니다.

Codex에서 등록하기

# ~/.codex/config.toml   (경로는 절대경로로)
[mcp_servers.blockshot-local]
command = "node"
args = ["/Users/<이름>/.blockshot/blockshot-mcp.mjs"]
env = { BLOCKSHOT_URL = "https://blockshot-eta.vercel.app" }

원격에서 로컬로 바꾸기 (토큰 필요 없음)

로컬 서버는 내 컴퓨터에서 직접 실행되는 명령이라 토큰이 필요 없습니다(토큰은 원격 주소만 보호합니다). AI에게 이렇게 요청하세요.

토큰 없이 로컬 MCP로 다시 등록해 줘. 기존 원격 blockshot 등록은 지우고,
설치한 뒤 새 세션에서 도구 14개(render_video, render_still 포함)가 보이는지까지 확인해 줘.

AI가 원격 MCP의 local_setup에서 정확한 명령·요구사항(Node 22+, Chrome)·전환 절차·확인 방법을 읽어 진행합니다. 직접 확인하려면 printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' | node ~/.blockshot/blockshot-mcp.mjs 가 도구 목록 한 줄을 출력하는지 보세요.

설치할 수 없는 환경(모바일, iPad, 웹 채팅)에서는 원격 MCP만 쓰고, 링크를 연 뒤 스튜디오의 영상 렌더로 MP4를 내보내면 됩니다.

이렇게 요청해 보세요

• “Blockshot으로 거실에서 두 사람이 대화하다 한 명이 일어나 창가로 걷는 6초 장면을 만들어 줘. 프리뷰로 확인하고 링크를 줘.”
• “방금 장면에서 지영이 3초에 고개를 천천히 끄덕이게 해 줘. 다른 건 건드리지 마.”
• “민수가 오른팔을 위로 들었다 내리는 동작을 뼈 키프레임으로 만들어 줘. 내가 직접 고칠 수 있게.”
• “2초와 4초 시점의 두 사람 거리와 바라보는 방향을 evaluate로 확인해 줘.”

명령어를 직접 입력하지 않아도, 셸을 쓸 수 있는 AI(Claude Code, Codex 등)에게 아래 프롬프트를 붙여넣으면 설치·등록·확인까지 대신 진행합니다. 각 프롬프트는 그 자체로 완결돼 있어서, 아직 MCP가 연결되지 않은 AI에게도 쓸 수 있습니다. AI는 실행 전에 먼저 물어보도록 되어 있습니다.

토큰을 채팅에 직접 붙여넣지 마세요. 원격 연결에는 토큰을 환경변수(예: BLOCKSHOT_TOKEN)에 넣어 두고 AI가 그 변수를 쓰게 하세요. 로컬 MCP는 토큰이 필요 없습니다. 같은 안내 전체는 /docs/mcp-setup.md에도 공개돼 있어, 웹을 읽을 수 있는 AI는 이 주소만 알려 줘도 됩니다.

Blockshot 로컬 MCP를 이 컴퓨터에 설치하고 등록해 줘. 실행 전에 무엇을 할지 먼저 알려 주고 내 확인을 받아.

1. 먼저 확인: node -v 가 v22 이상인지, Chrome(또는 Edge/Chromium)이 설치돼 있는지.
2. 파일 하나를 내려받아:
   mkdir -p ~/.blockshot && curl -fsSL https://blockshot-eta.vercel.app/mcp/blockshot-mcp.mjs -o ~/.blockshot/blockshot-mcp.mjs
3. 절대경로로 등록해 (토큰은 필요 없어):
   claude mcp add blockshot-local -e BLOCKSHOT_URL=https://blockshot-eta.vercel.app -- node $HOME/.blockshot/blockshot-mcp.mjs
   (Codex를 쓰는 중이면 ~/.codex/config.toml 에 [mcp_servers.blockshot-local] command="node", args=["<절대경로>/.blockshot/blockshot-mcp.mjs"], env={BLOCKSHOT_URL="https://blockshot-eta.vercel.app"} 를 추가)
4. 확인: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' | node $HOME/.blockshot/blockshot-mcp.mjs 가 도구 목록 한 줄을 출력하는지 보고, 안 되면 원인(Node 버전·다운로드 실패·경로)을 알려 줘.
5. 끝나면 새 세션을 열어야 도구가 보인다고 안내하고, 새 세션에서 도구 14개(get_guide, run_script, validate_spec, apply_addon, animate_prompt, evaluate, analyze_motion, solve_motion, inspect_rig, preview, load_link, open_link, render_video, render_still)가 보이면 성공이야.

자세한 내용은 https://blockshot-eta.vercel.app/docs/mcp-setup.md 에 있어.

Blockshot 원격 MCP를 등록해 줘. 주소는 https://blockshot-eta.vercel.app/api/mcp 이고 HTTP(Streamable HTTP) 방식이야.
토큰은 내 환경변수 BLOCKSHOT_TOKEN 에 들어 있어. 토큰 값을 출력하거나 대화에 적지 말고, 환경변수를 참조해서 등록해 줘:

claude mcp add --transport http blockshot https://blockshot-eta.vercel.app/api/mcp --header "Authorization: Bearer $BLOCKSHOT_TOKEN"

환경변수가 비어 있으면 등록하지 말고 알려 줘. 등록 후 claude mcp list 에서 blockshot 이 Connected 인지 확인하고, 새 세션에서 get_guide 도구가 보이면 성공이야. (이 클라이언트가 헤더 입력을 지원하지 않으면 주소 끝에 ?token= 을 붙이는 방법을 알려 줘.)

지금 Blockshot MCP가 원격(토큰 방식)으로 등록돼 있는데, 토큰 없이 로컬 MCP로 다시 등록해 줘.
Blockshot MCP의 local_setup 도구를 조회해서 그 안내를 그대로 따라 진행하고, 실행 전에 무엇을 지우고 무엇을 설치할지 먼저 알려 줘서 내 확인을 받아.
순서: 기존 원격 blockshot 등록 찾기(주소가 /api/mcp 로 끝나는 항목) → 삭제(저장된 토큰도 함께 사라져도 돼) → 로컬 설치·등록 → 확인(tools/list 한 줄 출력) → 새 세션에서 도구 14개(render_video, render_still 포함, local_setup 없음)가 보이는지 안내. 내 토큰은 출력하지 마.

Codex에 Blockshot MCP를 등록해 줘. 먼저 내 확인을 받고 진행해.

[로컬 방식 — 토큰 필요 없음]
1) mkdir -p ~/.blockshot && curl -fsSL https://blockshot-eta.vercel.app/mcp/blockshot-mcp.mjs -o ~/.blockshot/blockshot-mcp.mjs
2) ~/.codex/config.toml 에 추가 (경로는 절대경로로):
   [mcp_servers.blockshot-local]
   command = "node"
   args = ["/Users/<내 이름>/.blockshot/blockshot-mcp.mjs"]
   env = { BLOCKSHOT_URL = "https://blockshot-eta.vercel.app" }
3) codex를 다시 시작한 뒤 codex mcp list 로 blockshot-local 이 보이는지 확인하고, 도구 14개가 보이면 성공이야. Node 22 이상과 Chrome이 필요해.

(원격 방식을 원하면 url = "https://blockshot-eta.vercel.app/api/mcp" 와 환경변수 BLOCKSHOT_TOKEN 을 쓰는 설정을 Codex 문서에 맞춰 만들어 줘. 토큰 값은 파일이나 대화에 적지 마.)

Blockshot MCP 연결 상태를 점검해 줘.
1) claude mcp list(Codex면 codex mcp list)에서 blockshot 항목이 Connected 인지.
2) 연결된 서버가 로컬인지 원격인지: 로컬은 도구가 14개이고 local_setup 이 없고 render_video 설명이 "LOCAL ONLY"로 시작해. 원격은 15개이고 local_setup 이 있어.
3) 작은 장면 하나를 run_script 로 만들고 preview 로 PNG가 오는지, 로컬이면 render_still 로 3D PNG가 오는지 확인해.
문제가 있으면 원인과 고치는 방법을 알려 줘. 토큰은 출력하지 마.

Blockshot MCP로 내가 스튜디오에서 배치한 장면에 애니메이션을 추가해 줘.
장면 링크: <여기에 스튜디오 메뉴바의 「링크」 버튼으로 복사한 링크를 붙여넣기>

규칙: load_link 로 링크를 읽고, 배치된 인물·소품·카메라는 절대 옮기거나 새로 만들지 마. 이미 있는 id 에 scene.use("<id>") 로 동작·카메라 무브·샷만 추가해(run_script 의 base 에 읽은 spec 을 넘기거나 apply_addon).
추가할 내용: <예: 민수가 문에서 소파까지 걸어와 앉고, 지영은 고개를 끄덕인다. 카메라는 천천히 다가간다. 6초>
끝나면 preview 로 몇 시점을 확인하고 어색한 건 고친 뒤 open_link 로 새 링크를 줘.

Blockshot MCP의 get_guide 로 사용법을 읽고, 거실에서 두 사람이 마주 보고 이야기하다가 한 명이 일어나 창가로 걸어가는 6초 장면을 만들어 줘.
preview 로 카메라 시점과 탑뷰를 각각 확인하고 어색한 건 고친 다음, open_link 로 열어볼 링크를 줘. (로컬 MCP가 연결돼 있으면 끝에 render_video 로 MP4도 만들어 줘.)

에디터의 모든 기능은 하나의 명령 목록에서 나옵니다. 메뉴·단축키·팔레트가 쓰는 그 명령을 코드로도 똑같이 실행할 수 있습니다. 스튜디오를 연 채 브라우저 개발자 도구 콘솔에서 써 보세요. 코드로 바꾼 것도 Ctrl+Z로 되돌릴 수 있고 자동 저장됩니다.

blockshot.commands()                 // 모든 명령 (id·이름·단축키)
blockshot.run("add.actor")           // 명령 실행 — 메뉴/단축키와 같은 id
blockshot.run("view.camera1")

await blockshot.script(`
  scene.use("minsu").walkTo([1, 0, 1.5], { start: 0.5 }).sitDown("sofa", { start: 3 });
`, { animate: true })                 // 스크립트 API로 지금 장면에 연출 추가

blockshot.addon({ actions: [ ... ] })  // AI가 준 추가분 JSON 병합
blockshot.spec() / blockshot.load(spec)
blockshot.seek(2.5); blockshot.play(); blockshot.state(2.5)
await blockshot.link()               // 장면이 담긴 공유 링크
blockshot.on("change", (spec) => console.log(spec.meta.title))

스크립트 문법은 MCP의 run_script와 같습니다. 자세한 명세는 저장소의 docs/EDITOR_API.md와 docs/SCRIPT_API.md를 보세요.

작업이 사라졌어요.

프로젝트는 이 브라우저(IndexedDB)에 저장됩니다. 사이트 데이터를 지우거나 다른 브라우저·기기에서 열면 보이지 않습니다. 중요한 장면은 프로젝트 저장으로 JSON 파일을 받아 두세요.

영상 렌더가 안 돼요.

Chrome·Edge 최신 버전인지 확인하세요(WebCodecs 필요). 해상도 배율을 낮추면 인코딩이 더 안정적입니다. 오류 메시지가 나오면 그 내용을 확인하세요.

AI가 만든 장면이 열리지 않아요.

검증 오류 목록이 표시되고, 그 목록을 AI에게 돌려줄 수 있는 수정 프롬프트가 만들어집니다. 오류가 나는 줄을 고쳐 달라고 요청하세요.

인물이 의자를 통과하거나 벽을 뚫어요.

걷기와 앉기는 길찾기로 피해 가도록 만들어졌습니다. 그래도 어색하면 해당 동작을 지우고 다시 만들거나 경로 찍기로 중간 지점을 직접 지정하세요. AI가 만든 동작에 직선 이동 옵션(direct)이 붙어 있으면 길찾기를 건너뛰니, 그런 경우엔 동작 목록에서 지우고 다시 요청하세요.

MCP 호출이 거절돼요(401).

토큰이 필요한 서버입니다. 클라이언트에 Authorization: Bearer <토큰> 헤더를 넣거나 주소 끝에 ?token=<토큰>을 붙였는지 확인하세요.

다른 사람과 장면을 공유하려면?

JSON 파일을 보내거나, MCP의 open_link가 주는 링크를 공유하세요. 링크 안에 장면이 들어 있어 서버에 저장되지 않고, 열면 상대 브라우저에 새 프로젝트로 생깁니다.