현재 공개된 AE API 전체 범위를 다룬다. 기준일: 2026-10-03. 이 문서에 없는 ExtendScript/AE SDK 기능은 .aeu에서 사용할 수 있다고 가정하지 않는다.
타입과 접근 경로
// 설명용 타입. 실행 스크립트에 선언을 복사할 필요는 없다.
type Position = [x: number, y: number] | [x: number, y: number, z: number];
// ae.project: ae.Project
// ae.project.activeComp: ae.Comp | null
// comp.layers: ae.LayerCollection
// comp.layers.addText(text: unknown): ae.Layer
// layer.property(name: ae.PositionName): ae.Property
// layer.position getter: ae.Property
// layer.position setter: ae.Position
// property.value getter/setter: ae.Position
// ae.transaction<T>(callback: () => T, name?: unknown): T
TypeScript
복사
Project, Comp, Layer, Property는 호스트가 반환하는 객체다. 직접 new로 생성하지 않는다. ae.PositionName은 position의 ASCII 대소문자 조합만 허용한다.
ae.project.activeComp
읽기 전용 ae.Comp | null. 활성 Project item이 컴포지션이 아니면 null이다. 매 실행·이벤트에서 다시 조회하고 null을 처리한다. 현재 Project/Comp에 경로, 이름, width/height, 시간 또는 선택 레이어 속성은 노출되어 있지 않다.
const comp = ae.project.activeComp;
if (!comp) throw new Error('Open a composition first.');
const layer = comp.layers.addText('Title');
console.log(layer.position.value);
TypeScript
복사
comp.layers.addText(text)
인수: unknown. 런타임에서 문자열로 변환한다. 반환: ae.Layer. 활성 comp에 가로 텍스트 레이어를 생성한다. 현재 LayerCollection의 공개 메서드는 addText 하나이며 열거·검색·선택 API는 없다.
반환 Layer는 현재 실행/이벤트 안에서 사용한다. 텍스트 내용이나 스타일을 나중에 수정하는 별도 API는 아직 없다.
layer.position / layer.property(name) / property.value
layer.position 읽기는 좌표가 아니라 Property 객체다. 좌표는 layer.position.value로 읽는다. 쓰기는 layer.position = [x, y] 또는 layer.position.value = [x, y]를 사용한다.
layer.property('position')은 같은 Position 속성을 반환한다. ASCII 대소문자를 무시하지만 opacity, scale 등 다른 속성은 현재 지원하지 않는다.
const comp = ae.project.activeComp;
if (!comp) throw new Error('Open a composition first.');
const layer = comp.layers.addText('Position example');
layer.position = [320, 240];
const property = layer.property('Position');
const current: ae.Position = property.value;
property.value = [current[0] + 20, current[1]];
console.log(property.value);
TypeScript
복사
좌표는 유한한 숫자여야 한다. 2D에는 2개 또는 3개 좌표, 3D에는 3개 좌표가 필요하다. 읽기는 현재 layer time 기준이다. 키프레임이 있는 속성 쓰기는 지원하지 않는다. 실제 호스트 상태·차원 불일치는 런타임 오류가 될 수 있다. 실제 3D Position 동작은 별도 실기 검증 대상이다.
ae.transaction(callback, name?)
function transaction<T>(callback: () => T, name?: unknown): T;
TypeScript
복사
첫 번째 인수는 함수, 두 번째는 선택적 Undo 이름이다. callback 결과를 그대로 반환하며 중첩 transaction은 외부 그룹을 공유한다. callback이 반환하면 내부 그룹이 닫힌다. 반환한 Promise가 나중에 완료될 때까지 내부 그룹을 유지하지 않는다.
일반 실행의 AE 변경과 UI 이벤트의 AE 변경은 호스트가 각각 Undo로 묶는다. 순수 UI 이벤트는 AE Undo를 만들지 않고 첫 AE 변경/transaction 때 시작한다.
transaction은 rollback이 아니다. 예외·시간 초과 전에 완료된 AE 변경은 남을 수 있다. 사용자가 AE Undo로 되돌려야 한다. try/catch로 오류를 처리해도 이미 완료된 변경이 자동으로 취소되지는 않는다.
객체 수명
Comp/Layer/Property는 현재 실행 또는 UI 이벤트에만 유효하다. JS 클로저에 저장해 다음 이벤트에서 사용하면 안 된다. 프로젝트가 바뀌지 않았어도 이전 이벤트의 wrapper는 거부된다.
UI 상태로 문자열·숫자·배열 같은 일반 데이터를 유지하고, AE 객체는 매 이벤트 다시 조회한다. 현재 기존 레이어를 ID/이름으로 재조회하는 API도 없으므로 이전 이벤트에서 만든 Layer를 다음 이벤트에 다시 찾는 기능은 구현할 수 없다. 생성과 위치 변경을 같은 이벤트에서 끝내는 설계를 사용한다.
등록 도킹 패널 초기화와 Preview UI script 초기화에서는 AE 접근을 하지 않는다. UI와 콜백만 구성하고 AE 작업은 콜백 안에 둔다. 일반 Common Run 본문은 AE 접근이 가능하다.
console
console.log(...values: unknown[]): void;
console.warn(...values: unknown[]): void;
console.error(...values: unknown[]): void;
TypeScript
복사
인수를 String 변환하여 Developer/스크립트 패널 로그에 기록한다. 객체를 브라우저 개발자 도구처럼 탐색하는 콘솔이 아니다. 필요한 구조는 JSON.stringify()로 출력할 수 있다. 출력·문자열 변환에도 실행 기한이 적용된다.
로그는 실행당 32 KiB, UI 세션 누적 64 KiB로 제한된다. 대량 로그에 의존하지 않는다.
저수준 진단 함수
aeuscript.nativeAdd(left: unknown, right: unknown): number;
TypeScript
복사
인수는 정확히 2개이며 QuickJS가 각각 숫자로 변환한다. C++/JS 연결 검증용 함수로 AE 자동화 기능은 아니다.
실행 제한과 오류
•
일반 Run — 실행마다 독립 context; UI 창이 있으면 콜백을 위해 유지
•
일반 AE Run heap / stack — 64 MiB / 256 KiB
•
Common 실행 제한 — 250 / 1,000 / 5,000 ms 선택
•
UI 전용 초기화 / 콜백 — 최대 250 ms; UI 전용 heap 16 MiB, stack 256 KiB
•
스크립트 파일 — 최대 4 MiB, UTF-8; BOM 허용, UTF-16/NUL/잘못된 UTF-8 거부
•
Promise — 같은 기한의 microtask만 처리; 반환된 미완료 Promise와 미처리 rejection은 오류
UI 콜백과 AE 변경은 호스트 main-thread idle에서 순차 실행한다. worker에서 실행되는 구조가 아니며 긴 작업은 AE UI 응답을 늦출 수 있다. 일반 Run 제한을 올려도 UI 콜백의 250 ms 제한은 해제되지 않는다. 진행 중인 native SDK 호출은 강제로 끊지 못한다.
Stopped는 수동 취소, Timed out은 실행 제한 초과, Failed는 스크립트/파일 오류다. 일반 실행의 실패·중지는 Hot Reload를 멈추고 이전 로그와 스택을 보존한다. 원인을 해결하고 Run으로 다시 실행한다.
UI 이벤트 실패 시 UI 모델은 이전 상태로 복원하고 세션은 중지된다. JS 변수와 완료된 AE 변경은 자동으로 되감기지 않는다. Restart Script로 파일·JS 상태·UI를 새로 초기화한다.
현재 제공하지 않는 기능
레이어 열거·선택 조회, 기존 레이어 검색, 컴포지션 생성/크기 조회, 효과·키프레임·텍스트 스타일 편집, 일반 파일/네트워크 접근, 외부 모듈, 스크립트에서 timer/worker 호출은 현재 공개 API에 없다. C++ SDK에 해당 기능이 있어도 .aeu 바인딩이 생기는 것은 아니다.
근거
AEUScripts for vscode/types/aeuscript.d.ts, src/runtime.cpp, plugin/AEHostBridge.cpp, src/ui_session.cpp, docs/CURRENT_IMPLEMENTATION.md, docs/SCRIPT_UI_API.md. public API 기준: ea5c965.