대상: AEUScripts용 .aeu 스크립트를 만드는 개발자. 기준일: 2026-10-03 · Windows preview 0.1.0-preview.6 · VS Code 확장 0.6.1.
엔진과 파일 구조
AEUScripts는 After Effects 플러그인 AEUScript.aex 내부의 QuickJS-NG에서 JavaScript를 실행한다. 스크립트에서는 공개된 ae와 ui API를 사용한다. TypeScript는 편집·빌드 단계에서 JavaScript로 변환된다.
ExtendScript의 .jsx, app.project, File, Folder, new Window(...)를 사용하는 환경이 아니다. 브라우저 DOM, CSS, React, Node.js, fetch, timer, worker도 제공하지 않는다.
작업 폴더/
title.aeu ← JavaScript 또는 TypeScript 원본
title.aeui.xml ← 선택적 XML UI 원본
.aeuscript/
title.aeu ← AE에서 실행할 생성 JavaScript
title.aeu.map ← 원본 오류 위치 매핑
Plain Text
복사
순수 JavaScript .aeu는 직접 실행할 수 있다. TypeScript나 XML 리소스를 사용하는 개발 흐름에서는 항상 빌드한 파일을 실행한다. .aeuscript 안의 생성물을 직접 수정하지 않는다.
개발 환경 준비
1.
Windows x64용 AEUScript AEX와 aeuscripts-vscode-0.6.1.vsix를 준비한다. 현재는 개발 중인 preview이며 이 문서는 공개 다운로드 주소를 제공하지 않는다.
2.
AEX 설치·교체 전에는 AE를 정상 종료한다. 배포 패키지의 Install-AEUScript.ps1 및 RELEASE.md에 따라 설치한다. 스크립트만 수정할 때는 AEX 재설치가 필요 없다.
3.
VS Code의 Extensions: Install from VSIX...로 확장을 설치한다. 확장 사용자는 별도 Node.js/TypeScript 설치가 필요 없다.
4.
.aeu 파일을 UTF-8로 저장하고 언어 모드를 AEUScript로 확인한다. 자동완성, 호버, 인수 안내, F12 정의 이동과 Problems 진단을 사용할 수 있다.
5.
외부 UI 파일은 .aeui.xml로 저장한다. 일반 .xml도 AEUScript UI XML 언어 모드를 지정하면 자동완성과 진단을 사용한다.
검증 환경은 Windows x64 / AE 26.2.1이다. SDK 25.6으로 빌드하지만 AE 25.6 실기 검증을 뜻하지 않는다. 확장은 VS Code 1.96 이상을 대상으로 하며 파생 편집기는 개별 검증이 필요하다.
첫 번째 스크립트
다음을 hello.aeu로 저장한다. 좌표 [320, 240]은 고정 예시이며 컴포지션 중앙 계산이 아니다.
//@ID com.example.hello
//@NAME 'Hello AEUScripts'
//@DESC 'Create a text layer in the active composition.'
//@VERSION 1.0.0
//@TYPE script
const comp = ae.project.activeComp;
if (!comp) throw new Error('Open a composition first.');
const position: ae.Position = ae.transaction(() => {
const layer = comp.layers.addText('Hello AEUScripts');
layer.position = [320, 240];
return layer.position.value;
}, 'Create hello text');
console.log('Created at', position);
return position;
TypeScript
복사
1.
파일을 저장한 뒤 AEUScripts: Build Current Script를 실행한다. Problems 오류와 빌드 성공 여부를 확인한다.
2.
AE에서 컴포지션을 연다. Window > AEUScripts > Common > Add script...로 .aeuscript/hello.aeu를 추가한다.
3.
Run Selected Script를 누른다. 텍스트 생성과 Position을 확인하고 AE Undo 한 번으로 되돌릴 수 있는지 확인한다.
4.
로그와 오류는 Window > AEUScripts: Developer에서 확인한다. 활성 comp가 없다면 예제가 오류를 내며 레이어를 생성하지 않는다.
예제 ID는 배포 전에 자신의 namespace로 정한다. 이미 등록한 스크립트의 ID는 업데이트·파일 이동 때 유지한다.
실행 방식 선택
•
일회성 자동화 — 작성 방식: 일반 .aeu · AE에서 실행: Common에서 Run
•
일반 도구 창 — 작성 방식: ui.createWindow() · AE에서 실행: Common에서 Run; 본문 반환 후에도 콜백 유지
•
보조 다이얼로그 — 작성 방식: ui.createDialog() · AE에서 실행: modeless 창; 동기 결과 반환 없음
•
도킹 도구 — 작성 방식: @ID, @TYPE panel, ui.createPanel() · AE에서 실행: Panels 등록 → 새 ID는 AE 재시작 → Open Selected Panel
일반 Run에서는 createPanel()을 호출할 수 없다. 패널 임시 확인에는 Developer 패널 메뉴의 Preview UI script...를 사용한다. 이 미리 보기는 비도킹 창이다.
저장 → 빌드 → 다시 실행
원본과 XML을 저장하고 다시 빌드한다. AE는 저장된 생성 파일을 실행한다. 일반 스크립트의 Hot Reload는 생성 파일 변경을 감지하므로 원본 저장만으로 실행 코드가 갱신되지는 않는다.
빌드 실패 시 이전 생성물이 남는다. 성공 알림과 AEUScripts Output의 경로를 확인한 뒤 실행한다. Open Generated Script는 원본/XML/생성 코드가 빌드 기록과 다르면 경고한다.
지속 UI는 수정 후 Restart Script로 파일을 다시 읽는다. UI 자동 Hot Reload를 가정하지 않는다. 새 도킹 ID 등록은 AE 재시작이 필요하지만 기존 ID의 스크립트 내용 변경은 Restart로 반영한다.
오류 위치는 원본 편집기를 열고 AEUScripts: Go to Original Error Location에 생성 코드의 행:열을 입력한다. 두 숫자 모두 1부터 시작한다. 원본/XML/생성 코드 조합이 바뀌었으면 매핑이 거부되므로 재빌드 후 다시 실행한다.
TypeScript 지원 범위
기본 타입, 인터페이스, 제네릭, enum, async 함수 등을 지원하며 ES2023 JavaScript로 변환한다. 실행 래퍼가 top-level return을 지원한다. 반환 Promise의 microtask는 같은 실행 기한 안에서 처리한다.
import/export(타입 import 포함), npm 패키지, 외부 선언 참조, decorators, top-level await는 현재 빌드 프로필에서 지원하지 않는다. any나 타입 단언은 런타임 API를 추가하지 않는다. 표준 라이브러리 타입이 엔진의 모든 기능을 보장하지 않으며 Atomics.wait는 차단된다.
근거
저장소 docs/QUICKSTART.md, docs/RELEASE.md, AEUScripts for vscode/README.md, 공개 타입 AEUScripts for vscode/types/aeuscript.d.ts 및 실제 바인딩을 기준으로 작성했다. 코드 기준은 ea5c965이며 native/API 코드는 10월 3일 Release 빌드 기준과 동일하다.