EffectCraft

EffectCraft — 에이전트 사용법

EffectCraft는 네이티브 Rust 모션그래픽/VFX 컴포지터(After Effects급)로, 에이전트 인터페이스가 내장되어 있습니다. 모든 동작은 명령에 ID가 부여된 형태로 실행됩니다. GUI, 메뉴, CLI, 제어 채널 및 MCP 서버가 모두 동일한 엔진을 구동합니다. Windows에서 0.17.0 버전으로 검증되었습니다.

시스템 및 환경 경로

플랫폼	바이너리	CLI	기본 데이터 디렉터리
Windows	C:\Program Files\EffectCraft\effectcraft.exe	C:\Program Files\EffectCraft\effectcraft-cli.exe	%LOCALAPPDATA%\EffectCraft (디스크 캐시)
Linux	/usr/bin/effectcraft	/usr/bin/effectcraft-cli	~/.local/share/effectcraft

• 제어 포트: --control <port> 또는 EFFECTCRAFT_CONTROL_PORT 환경 변수 (토큰 불필요 — 브릿지가 일반 루프백 연결을 허용하며, FilmCraft와 다름)
• 명령: 55개 네임스페이스에 734개 (새 헤드리스 컨텍스트에서 439개 활성화; 나머지는 선택/활성 컴포지션/툴 모드 필요)
• 효과: 레지스트리에 307개 (list_effects); 149개 폰트 패밀리 (list_fonts)

개념 모델

• 프로젝트(.ecproj)는 항목(Composition, Folder, Solid, Footage)을 담습니다. get_project는 항목 트리, 더티 플래그, 활성 컴포지션을 반환합니다. 하나의 컴포지션이 활성 상태이며, 대부분의 명령이 이 활성 컴포지션에 적용됩니다.
• 컴포지션(comp) 은 {width, height, frameRate, duration, startTime, background, renderer: classic3D|advanced3D}로 구성됩니다. 시간은 초 단위(부동소수점, 틱 사용 안 함 — FilmCraft와 달리 틱 연산 없음)입니다.
• 레이어는 텍스트, 쉐이프, 솔리드, 널, 컴포지션(프리컴프), 조정 레이어, 라이트 또는 카메라입니다. 레이어는 1이 최상단으로 쌓입니다. 레이어는 id, #n(스택 인덱스) 또는 name으로 주소 지정합니다.
• 모든 레이어에는 프로퍼티 트리가 있습니다: Transform (anchor, position, scale, rotation, opacity), 그리고 effects, masks, 텍스트 또는 쉐이프 contents. 프로퍼티 경로는 transform.position 및 Transform/Position을 허용하지만, 그룹 없는 단순 position은 거부됩니다.
• 애니메이션 = 프로퍼티의 키프레임(prop.addKey) 또는 표현식(prop.setExpression, AE JavaScript)입니다. prop.get {time}은 보간된 값, 키 목록 및 animated 플래그를 반환합니다.
• 파라미터는 엄격하게 검증됩니다: 알 수 없는 파라미터 이름은 허용된 키 목록과 함께 명령 실패를 초래합니다. 알 수 없는 명령 ID도 마찬가지입니다. 이는 FilmCraft의 무시되는 파라미터와 반대입니다 — 오류 메시지를 읽고 호출을 수정하세요. 맹목적으로 재시도하지 마십시오.
• 읽어서 확인하세요 (get_state, get_project, get_comp, get_layer, get_property) 또는 렌더링(render_frame — PNG는 잘못된 위치, 보이지 않는 레이어, 누락된 효과를 찾아냅니다)으로 확인합니다.

두 가지 연결 모드

모드	시작 방법	용도
헤드리스	effectcraft-cli mcp --demo (--project p.ecproj, --empty, --autosave)	창 없음, 배치 빌드, 렌더링, 스크립트
앱 브릿지	effectcraft --control 50052 + effectcraft-cli mcp --bridge 50052	실제 창: UI 상태, 스크린샷, 클릭, 키 입력, GUI 전용 명령

각 CLI 호출은 자체 세션입니다. 한 run에서 생성된 상태는 프로세스가 종료되면 사라집니다 — file.saveAs + --save-as로 마무리하거나, 모든 작업(빌드 → 렌더링)을 단일 render/run 호출로 수행하세요.

사용자 요청 시 EffectCraft 실행 ("起動して" / "start EffectCraft")

1. 이미 실행 중인지 확인: Get-Process effectcraft / pgrep effectcraft. 실행 중이면 포트를 테스트: effectcraft-cli --bridge 50052 info. 제어 포트 없이 실행 중이면 --control로 다시 시작하도록 사용자에게 요청(저장되지 않은 작업 손실 방지).
2. --control <port>(기본값 50052)로 실행:
   • Windows — scripts/launch.ps1 사용 — 창이 백그라운드 세션이 아닌 보이는 데스크톱에 표시됨: powershell -File scripts/launch.ps1 -Port 50052
   • Linux: ./scripts/launch.sh 50052
3. 확인: 1~3초 대기 후 effectcraft-cli --bridge 50052 info 실행 — 버전, 명령/효과 개수 및 열린 프로젝트를 출력합니다.

MCP 도구들

헤드리스는 27개의 도구를 제공하고, 브릿지는 9개의 UI 도구(ui_inspect, ui_elements, ui_click, ui_drag, ui_key, ui_set, ui_type, screenshot, control)와 ScriptUI 대화상자용 script_ui를 추가하여 총 36개입니다.

도구	목적
command_list / list_commands	모든 명령 (--filter, --enabled)
command_run / execute_command	하나의 {id, params} 실행 (실행취소 가능)
command_batch / batch	여러 명령, 하나의 실행취소 단위 (batch)
describe_command	하나의 명령 스키마
doc_inspect / get_project	한 번에 프로젝트 트리 + 활성 컴포지션
get_comp	하나의 컴포지션: 설정, 레이어, 작업 영역
get_layer	레이어의 전체 프로퍼티 트리
get_property / set_property	하나의 프로퍼티 읽기/쓰기 (애니메이션 시 키 설정)
add_keyframe	프로퍼티에 키프레임 추가 (스톱워치 켜기)
add_effect / list_effects	효과 적용 (+파라미터 한 번에) / 307개 효과 레지스트리
list_fonts	텍스트 레이어에 사용 가능한 149개 폰트 패밀리
run_script	After Effects 스타일 ExtendScript (app.project, 컴포지션, 레이어)
render_frame / render_preview	time 시점의 (활성) 컴포지션 PNG
open_project / save_project	열기 (path, demo:true, empty:true) / 저장 (+다른 이름으로 저장)
undo / redo / history	분기형 실행취소 기록
get_state	활성 컴포지션, 현재 시간, 선택 항목, 재생 상태
script_ui	ScriptUI 대화상자/팔레트 스크립트 구동

리소스: effectcraft://document 및 effectcraft://commands.

표준 워크플로우

1. 탐색. get_state + get_project; 헤드리스는 --demo/--project 없으면 빈 상태로 시작. 브릿지 모드에서는 먼저 ui_inspect.
2. 빌드. comp.new {name,width,height,frameRate,duration} → layer.newText/newShape/newSolid/newNull (인라인 스타일링 파라미터) → 푸티지용 file.import {paths} → layer.addItem 스타일 배치.
3. 애니메이션. 키당 prop.addKey {layer,path,time,value}; keys.setEase, keys.interpolation, prop.setExpression.
4. 스타일링. effect.apply {effect:"Gaussian Blur", layers:[id]} + effects/#1/... 아래 파라미터 경로; 마스크(mask.new), 텍스트 애니메이터, 쉐이프 그라디언트 스트로크.
5. 확인. 알맞은 시간에 get_property; 해당 시간에 render_frame으로 PNG를 보고 확인(위치, 이징, 블러 모두 시각적으로 확인 가능).
6. 렌더링. render --out file.mp4 --format h264 (CLI), 또는 renderQueue.add + renderQueue.render; RGBA용 render-frame --transparent; 템플릿 작업용 render --template t.ectemplate --values v.json.
7. 저장. file.saveAs {path} (또는 CLI --save-as); get_project를 다시 읽어 확인 — 저장 후 더티 플래그가 지워집니다.

명령 찾기

command_list {filter:"mask"}는 ID, 레이블, 메뉴를 매칭합니다. 셸에서: effectcraft-cli commands --filter mask, 그리고 단일 명령 스키마 확인용 describe_command/describe. 734개 ID 전체와 파라미터 문서는 references/catalog/commands.md에 있습니다. 단계별 JSON 검증 예제는 references/recipes.md에 있습니다.

다음으로 시작하세요: comp.new, comp.settings, comp.open, layer.newText, layer.newShape, layer.newSolid, layer.newNull, layer.select, layer.moveLater, layer.setTransform, layer.setText, prop.get, prop.set, prop.addKey, keys.setEase, keys.interpolation, prop.setExpression, effect.apply, mask.new, time.set, file.import, file.saveAs, renderQueue.add, renderQueue.render, app.quit.

시간을 낭비하는 함정들

1. 모든 곳에서 엄격한 검증. 알 수 없는 파라미터 → invalid parameters … accepted: name, width, … (전체 키 목록 포함); 알 수 없는 명령 ID → unknown command. 오류 메시지가 문서입니다. 하지만 유효한 파라미터에 잘못된 값 타입이 들어가도 오작동할 수 있으므로 상태를 다시 읽어 확인하세요.
2. 레이어 시간 vs 컴포지션 시간. 쓰기 명령(prop.addKey, keys.set, prop.set)은 기본적으로 time을 레이어 초(timeBase:"layer"|"comp"로 전환 가능)로 받습니다; prop.get은 time을 컴포지션 초로 읽습니다. 레이어 시작이 0이면 일치하지만 layer.move 후에는 일치하지 않습니다. 잘못된 기준 = 키가 레이어 시작 시간만큼 조용히 밀려납니다.
3. 많은 명령이 선택(selection)을 필요로 합니다. prop.set, effect.apply, keys.easyEase는 선택된 항목이 없으면 enabled:false를 표시합니다(헤드리스는 빈 상태로 시작). 명시적으로 layer/layers 파라미터를 전달하거나, 먼저 layer.select를 실행하세요.
4. comp.new는 {comp: id}를 반환하고 이를 활성 컴포지션으로 만듭니다 (검증됨: 두 번의 comp.new 호출, 텍스트 레이어는 두 번째 컴포지션에 생성됨). comp.open {comp: id|name}으로 전환하고 get_state로 확인하세요 — "the active comp"를 대상으로 하는 명령과 렌더는 --empty 프로젝트에서 첫 comp.new 전에 활성 컴포지션 없음 오류로 실패합니다.
5. 프로퍼티 경로에는 그룹이 필요합니다: transform.position / Transform/Position은 작동하지만, 단순 position은 프로퍼티 없음 오류를 냅니다. 정확한 경로는 props <comp> <layer> --flat 또는 get_layer로 찾으세요.
6. 효과 파라미터는 효과 아래의 경로입니다. 예: effects/#1/Blurriness (인덱스 = 적용 순서). effect.apply는 paths:["effects/#1"]을 반환하므로 이를 사용하세요.
7. 각 CLI 호출은 새로운 세션입니다 (위 참조). MCP 세션은 서버가 종료될 때까지 상태를 유지합니다.
8. render는 상대 --out 경로를 프로세스 작업 디렉터리에 저장합니다. 예측 가능한 출력을 위해 항상 절대 경로를 전달하세요.
9. 텍스트 레이어는 생성 시 완전한 스타일링을 지원합니다(layer.newText {size,fill,tracking,…} — 수십 개의 파라미터). 이후 스타일 변경은 텍스트 소스/문서 프로퍼티를 통해 이루어집니다. 정확한 경로는 get_layer를 확인하세요.
10. GUI 전용 표면: ui_*, screenshot, control, script_ui는 브릿지에만 존재합니다. window.*, view.*, help.*는 대부분 GUI가 필요합니다.
11. mcp --autosave 는 종료 시 저장되지 않은 헤드리스 편집 내용을 유지합니다. 이 옵션이 없으면 사라집니다(임시 실행에는 예상된 동작이지만 실제 작업에는 놀라운 일입니다).

참조 맵

파일	내용
references/recipes.md	검증된 JSON: 빌드, 텍스트, 쉐이프, 키프레임, 이징, 표현식, 효과, 마스크, 렌더링, 내보내기, GUI
references/catalog/commands.md	파라미터 문서가 포함된 네임스페이스별 734개 명령 전체
references/mcp-and-control.md	27+9개 도구, 오류 형식, 리소스, 브릿지 세부 정보
references/cli.md	effectcraft-cli 하위 명령, 렌더 포맷, 템플릿, 벤치마크
references/bugs-and-workarounds.md	최소 재현 코드와 함께 재현된 결함
references/maintenance.md	버전 재확인, 명령 덤프, 스킬 새로고침
scripts/probe.sh / .ps1	MCP 핸드셰이크 + 도구 개수 + 버전
scripts/dump-commands.sh / .ps1	명령 카탈로그 재생성
scripts/launch.sh / .ps1	제어 포트로 GUI 시작 (보이는 데스크톱)
scripts/smoke-test.sh / .ps1	빌드 → 키프레임 → 렌더 → 검증

커뮤니티: https://discord.gg/artcraft · https://getartcraft.com/apps/effectcraft.