teardown은(는) 무엇을 하나요?
하나의 기계, 하나의 페이지. 방문자는 기계가 작동하는 모습을 보고, 버튼을 누르면 작동 중인 부품이 열리면서 주변 게이지에 실제 수치가 표시됩니다. 아무 조작 없이 놔두면 페이지가 커서와 함께 스스로 투어를 진행합니다. 동일한 코드가 투어의 영상을 프레임별로 녹화하고, 동일한 타임라인을 기반으로 한 배경 음악을 추가합니다.
아래 SKILL_DIR은 이 파일이 위치한 폴더입니다(Cursor 설치 시 보통 ~/.cursor/skills/teardown, ~/.agents/skills/teardown, 또는 프로젝트 내 .cursor/skills/teardown). 빌드 및 렌더링 결과물은 실행한 폴더의 ./teardown-out에 저장됩니다.
첫 실행
cd "$SKILL_DIR" && npm install && npx playwright install chromium
페이지에는 다른 것이 필요하지 않습니다. 비디오를 위해서는 PATH에 ffmpeg가 필요하고, 배경 음악을 위해서는 Python 3(표준 라이브러리만 사용)이 필요합니다. 다른 바이너리를 사용하려면 FFMPEG, PYTHON 또는 CHROMIUM 환경 변수를 설정하세요.
예제 3개
하나를 빌드하고, HTML을 열고, 버튼을 눌러보세요. 새 기계를 시작할 때 가장 유사한 예제를 복사하세요.
| 기계 | 구동 방식 | 참고할 만한 점 | |
|---|---|---|---|
v8-* | 유리 라이너가 있는 크로스플레인 V8: 추적하는 실린더 내부에서 연소가 일어나고, 밸브가 캠 위에서 움직이며, 8개의 피스톤이 정확한 슬라이더-크랭크 메커니즘으로 움직입니다. | 크랭크 각도. 점화 순서 1-8-4-3-6-5-7-2, 지시 다이어그램을 위한 실린더 압력 모델. | 단면도 모드(유리, 단면, 솔리드), 실린더 선택기로서의 점화 순서, 크랭크와 동기화된 라이브 차트. |
cessna-* | 세스나 337 주 착륙 장치가 이륙 시 동체 안으로 접히고 착륙 시 내려옵니다. | 스트로크 0..1: 201mm 랙이 32톱니 피니언(모듈 4mm)을 정확히 180° 회전시킵니다. | 하나의 자유도로 전체 메커니즘 포즈 구성, 시간 함수로서의 비행 단계, 모델 아래로 굴러가는 활주로. |
strandbeest-* | 테오 얀센의 스트랜드비스트, 하나의 크랭크축에 20개의 다리가 달려 모래 위를 옆으로 걷습니다. | 바람. 크랭크 속도는 바람으로부터 통합되며, 모든 관절은 얀센의 11개 링크 길이로부터 원 교차법으로 계산됩니다. | 67줄의 정확한 링키지 솔버, 인스턴스화된 튜브, 발자국 궤적, 20개 발 모두의 접촉 차트. |
각 예제는 3개의 폴더로 구성됩니다: <name>-shared/는 기계 자체를, <name>-film/은 녹화된 투어를, <name>-live/는 사용자가 조작하는 페이지를 담고 있습니다.
node "$SKILL_DIR/sims/build.mjs" v8-live # → teardown-out/dist/v8-live.html, 오프라인, ~800 KB
node "$SKILL_DIR/sims/build.mjs" # 전체 6개
기계가 어떻게 빌드되는지
기계당 하나의 폴더, 작업별로 분할됩니다. 예제들은 정확히 이 구조를 따릅니다:
| 파일 | 작업 |
|---|---|
kin.js / gear.js / jansen.js | 수학. 실제 단위의 실제 치수, 하나의 입력(크랭크 각도, 스트로크, 바람)과 그 함수로서의 모든 포즈 및 판독값. three.js는 여기에 없습니다. |
engine.js / gear.js / beast.js | 형상. 코드로 빌드: 선반 가공 부품, 튜브, 인스턴스화된 링크. update(input)이 포즈를 지정합니다. |
stage.js | 스튜디오, 조명, 그림자, 후처리(GTAO, 블룸). frame(state, cam)이 한 프레임을 그립니다. |
console.js | 오버레이: 고정 1600 x 900 CSS 레이아웃의 패널, 차트, 토글, 지시선이 있는 캘아웃. update(state)가 프레임 상태에서 이를 다시 그립니다. |
film.js | 연산자 동작(뷰, 격리, 단면도, 스로틀)의 SCRIPT와 시간의 순수 함수로서의 render(t). |
live.js | 실시간의 동일한 기계: 버튼, 슬라이더, 궤도 회전, 확대/축소, 키. 입력이 없으면 film.js의 스크립트를 커서가 있는 자동 투어로 재생합니다. 클릭, 드래그, 휠 또는 키 입력이 있으면 제어권을 가져오고, 25초간 조용히 있으면 다시 제어권을 반환합니다. |
score.py | 영화 타임라인의 사운드. |
SKILL_DIR 외부의 기계의 경우 main.js가 있는 폴더를 만들고 이름으로 키트를 가져오세요: import {runSim} from 'teardown-kit/runtime.js'. node "$SKILL_DIR/sims/build.mjs" ./my-machine으로 빌드합니다.
작동 여부를 결정하는 규칙
- 상상이 아닌 참고 자료에서 시작하세요. 사진, 매뉴얼의 단면도, 실제 장면의 클립. 이에 맞춰 빌드하고 프레임별로 비교하세요. 문장 하나로 발명된 기계는 항상 평범하게 나옵니다. 동일한 모델이 일치시킬 대상이 있을 때 실제 기계를 가깝게 재구성합니다.
- 실제 숫자, 하나의 소스. 먼저 실제 치수(보어, 스트로크, 톱니 수, 링크 길이)를 구하세요. 모든 게이지, 차트 및 레이블은 부품의 포즈를 지정하는 동일한 함수에서 값을 읽으므로 화면의 어떤 것도 움직임과 불일치할 수 없습니다. 하나를 수동으로 확인하세요: 세스나에서 32톱니 × 4mm 모듈은 128mm 피치 직경이고, 그 원주의 절반은 201mm 스트로크입니다.
- 하나의 입력이 모든 것을 구동합니다. 크랭크 각도, 스트로크 또는 바람에서 포즈를 지정하세요. 수동으로 키프레임을 지정하는 것은 없으므로 영화, 라이브 페이지 및 배경 음악이 절대 어긋나지 않습니다.
- 작동 중인 부품이 열립니다. 그것을 격리하고, 자르고, 엑스레이로 보여주세요. 내부로 들어가는 카메라는 열 개의 궤도 회전보다 가치가 있습니다.
- 밝은 스튜디오, 하나의 강조색. 창백한 배경은 피드에서 잘 읽히고, 어두운 배경은 처음 1초를 잃습니다. 강조색은 변화하는 것을 표시합니다. 창백한 배경에 거의 흰색인 부품을 조심하세요: 잉크 외곽선이나 더 어두운 바닥을 제공하세요.
- 메커니즘에 맞는 카메라를 선택하세요. 평면 링키지를 정면에서 보면 격자로 붕괴됩니다. 척추를 따라 3/4 뷰는 모든 다리를 읽을 수 있게 유지합니다.
- 충돌을 숫자로 수정하세요. 부품이 다른 부품을 관통할 때 매개변수 블록에서 크기를 조정하거나 이동하세요. 카메라로 숨기지 마세요.
라이브 페이지 규칙
- 통합 GPU에서 테스트하세요. 데스크톱 카드에서 60fps로 실행되는 페이지가 노트북의 내장 GPU에서는 15fps로 떨어질 수 있습니다. 예제는 품질 계층(
live.js의TIERS)을 제공합니다: AO 없음, 낮은 픽셀 비율, 작은 섀도우 맵, 매 다른 프레임마다 패널 다시 그리기. 먼저 비싼 셰이더를 찾으세요: 정점당 5번 계산되는 변위는 모든 계층을 합친 것보다 비용이 더 많이 듭니다. - 셰이더를 워밍업하세요.
kit/warm.js는 첫 번째 프레임 전에 모든 프로그램을 병렬로 컴파일하므로 페이지가 첫 번째 드로우에서 절대 멈추지 않습니다. - 페이지를 1MB 미만으로 유지하세요. 링크 크롤러(X, Slack)는 HTML에서 공유 카드를 읽고 15MB 페이지는 포기합니다. 큰 모델은 페이지 옆에 파일로 내보냅니다:
build.json→{"external": {"heavy.glb": "light.glb"}}.
render(t) 계약
import {runSim} from '../kit/runtime.js';
const DEFAULTS = {duration: 20, fps: 60, hud: {enabled: false}, director: {enabled: false}};
runSim(DEFAULTS, async ({cfg, canvas, capture}) => {
// 씬을 빌드하고, 상태 저장이 필요한 것은 미리 계산
return {render(t) { /* 처음부터 프레임 t를 그림 */ return {}; }, resize() {}};
});
render(t)는 순수 함수입니다:Math.random사용 금지(설정 시kit/util.js의rng(seed)사용),Date사용 금지, 프레임 간 상태 유지 금지. 캡처는 임의의 시간에 호출합니다.- 자체 규칙으로 움직이는 것(에이전트, 입자)은 로드 시 한 번 타입 배열로 시뮬레이션됩니다.
render는 읽기만 합니다. 시간에 따라 통합된 양(변화하는 바람 속 스트랜드비스트의 크랭크)은 폐쇄형으로 통합되거나 로드 시 테이블화됩니다. - 모든 비트는
<name>-film/timeline.json에 초 단위로 기록됩니다. 배경 음악도 동일한 파일을 읽습니다. - 프레임 0은 썸네일입니다. 이미 기계를 보여주고 있어야 합니다.
명령어
node "$SKILL_DIR/sims/build.mjs" v8-film
node "$SKILL_DIR/sims/capture.mjs" v8-film --size 1600x900 --dpr 1.2 --stills beats --cols 4 --out teardown-out/v8-beats.png
node "$SKILL_DIR/sims/capture.mjs" v8-film --size 1600x900 --dpr 1.2 --still 12.5 --out teardown-out/v8-12.5.png
node "$SKILL_DIR/sims/capture.mjs" v8-film --size 1600x900 --dpr 1.2 --out teardown-out/v8-silent.mp4
python "$SKILL_DIR/run_sfx.py" "$SKILL_DIR/sims/v8-shared/score.py"
ffmpeg -y -i teardown-out/v8-silent.mp4 -i teardown-out/v8-score.wav -map 0:v -map 1:a -c:v copy -c:a aac -b:a 256k -shortest -movflags +faststart teardown-out/v8.mp4
node "$SKILL_DIR/wave.mjs" teardown-out/v8.mp4 --timeline "$SKILL_DIR/sims/v8-film/timeline.json"
--size는 CSS 레이아웃이고 --dpr은 이를 곱합니다: 1600 x 900에 1.2를 곱하면 1920 x 1080이 됩니다. 캡처는 가져온 GPU를 출력합니다. 소프트웨어 렌더러는 paths.mjs의 GPU 플래그가 적용되지 않았음을 의미합니다.
검토 루프
비디오를 볼 수는 없지만 프레임을 볼 수 있습니다. 현재 렌더링의 시트를 읽지 않고 기계가 완료되었다고 보고하지 마세요.
--stills beats: 타임라인 비트당 하나의 타일, 해당 시점 0.3초 후, 각각t=로 레이블 지정.- 아래 체크리스트에 대해 모든 타일을 읽으세요.
- 확대: 전환을 위해
--stills every:0.2 --from A --to B, 전체 프레임 하나를 위해--still T. - 수정, 재빌드, 1번으로 돌아가기. 전체 패스에서 아무것도 찾지 못할 때 중지하세요.
- 최종:
node "$SKILL_DIR/sheet.mjs" --video <final.mp4> --timeline <timeline.json>을 실행하고 그것도 읽으세요: 인코더가 쓴 내용을 보여줍니다.
체크리스트:
- 메커니즘. 접촉해야 하는 모든 부품이 접촉합니다. 어떤 것도 다른 것을 통과하지 않습니다. 패널의 숫자가 포즈와 일치합니다.
- 구도. 프레임당 하나의 초점. 중요한 것은 가장자리에서 60px 이내에 없습니다. 레이블이 지명하는 부품을 가리지 않습니다.
- 타이포그래피. 잘린 것이 없습니다. 주요 판독값이 전화기 폭에서도 읽힙니다.
- 3D. 블룸이 디테일을 삼킵니다: 방출 레이어를 1.0 미만으로 유지하세요. 거의 흰색 표면은 날아갑니다. 낮은 조명 아래 광택 금속은 줄무늬가 생깁니다: 큰 표면에서는 거칠기 ≥ 0.45, envMapIntensity ≈ 0.5.
- 타이밍. 각 상태는 읽을 수 있을 만큼 충분히 유지됩니다: 짧은 구절에는 1초, 세 단어를 초과하면 단어당 0.25초 추가.
예제가 이미 부딪힌 three.js 함정
a > b인smoothstep(a, b, x)는 Windows(ANGLE/D3D)에서 0을 반환합니다.1.0 - smoothstep(b, a, x)로 작성하세요.- 바닥에서 1밀리미터 미만 떨어진
ShadowMaterial또는 데칼은 후처리 렌더 타겟 내에서 깊이 테스트를 잃습니다.polygonOffset을 제공하세요. - 미러 매핑으로 바닥에 배치된 쿼드는 뒷면으로 컬링됩니다.
DoubleSide를 사용하세요. - 하나의 NaN 픽셀이 블룸을 통해 전체 프레임을 검게 만듭니다. 셰이더에서 모든
pow()베이스를 클램프하세요. - 클리핑된(단면도) 모델의 GTAO는
gtao.normalMaterial에 동일한 클리핑 평면이 필요합니다. 그렇지 않으면 잘린 절반이 창백한 유령처럼 나타납니다.
사운드
sfx/는 모든 사운드를 순수 Python(48kHz, 재현 가능)으로 합성하고 영화의 타임라인을 읽으므로 사운드가 동기화에서 벗어날 수 없습니다. python "$SKILL_DIR/run_sfx.py" --list는 생성기를 보여줍니다. sample()은 sfx/samples/에 있는 녹음된 CC0 사운드를 추가합니다. sfx/score_kit.py에는 3개의 배경 음악이 사용하는 베드와 악센트가 있습니다: 코드 베드, 파워 스트로크당 부드러운 쿵, 모터, 항력 아래 공기.
- 모든 시간은 타임라인에서 나오며, 직접 입력한 숫자가 아닙니다.
- 마스터링은 자동입니다: -14 LUFS, 실제 피크 ≤ -2 dBFS.
- 악센트, 절대 나레이션하지 마세요: 연속적인 움직임은 조용히 유지됩니다. 음조 사운드당 하나의 키.
숫자로 표현하는 감각
- 이징: 진입
cubic-bezier(0.16, 1, 0.3, 1), 종료cubic-bezier(0.6, 0, 0.9, 0.35)(진입 길이의 절반), 상태 간cubic-bezier(0.65, 0, 0.35, 1). 선형은 연속적인 움직임에만 사용합니다. - 기계는 뷰포트의 60-70%를 채웁니다. 1080 캔버스에서 레이블은 절대 34px 미만이 아닙니다.
- 하나의 강조색, 그리고 그것은 의미가 있습니다: 지금 작동 중인 부품.
- 완전히 정지된 것은 없습니다: 하나의 요소는 항상 살아 있습니다.
크레딧
Cursor 포트: bugeng777/teardown-cursor (기반: elvarofficial/teardown, MIT). 키트, 프레임 캡처, sfx 엔진 및 검토 규칙: whaleyxbt/claude-motion (MIT). 녹음된 샘플은 Freesound의 CC0이며, Barty-Bart/motion-graphics (MIT)에서 트리밍되었습니다. 출처는 sfx/samples/SOURCES.md에 있습니다.