에디터 API

type EditorField =
  | 'keys'
  | 'keyPositions'
  | 'statPositions'
  | 'graphPositions'
  | 'knobPositions'
  | 'spritePositions'
  | 'layerGroups';
 
interface EditorDocumentV1 {
  schemaVersion: 1;
  keys: KeyMappings;
  keyPositions: KeyPositions;
  statPositions: StatItemPositions;
  graphPositions: GraphItemPositions;
  knobPositions: KnobItemPositions;
  spritePositions: SpritePositions;
  layerGroups: LayerGroups;
}
 
type EditorPatchV1 = {
  schemaVersion: 1;
} & Partial<Pick<EditorDocumentV1, EditorField>>;

// 탭/모드 id(예: "4key")로 키잉
type SpritePositions = Record<string, ReactiveSpritePosition[]>;
 
interface ReactiveSpritePosition {
  id?: string; // 안정 요소 신원 (UUID)
  dx: number; // 요소 상자 원점과 크기. 상자가 곧 기본 이미지 상자이고 오버레이 창 크기 계산에 들어갑니다
  dy: number;
  width: number;
  height: number;
  rotation?: number; // 요소 상자 중심을 축으로 하는 배치 회전, -180–180도, 기본 0
  hidden: boolean;
  zIndex: number | null;
  layerName?: string | null; // 미설정이면 백엔드가 키를 생략합니다
  groupId?: string | null; // 미설정이면 백엔드가 키를 생략합니다
  className: string | null;
  useInlineStyles: boolean | null;
  baseImage: string | null; // 일치하는 자세가 없을 때 보여줄 이미지. 항상 요소 상자를 채웁니다
  referenceNaturalSize: {
    source: string | null;
    width: number;
    height: number;
  } | null; // 픽셀 배율의 기준이 되는 원본 크기(정수, 1–32768). baseImage가 있으면 source가 그 경로와 같아야 하고 없으면 null이어야 합니다. null이면 모든 이미지를 요소 상자에 그대로 그립니다
  pivot: { x: number; y: number }; // 정규화 공통 축, 각각 0–1, 기본 {0.5, 0.5}. 기본 이미지의 기준점이자 모든 자세 변환의 축
  idleTransform: SpriteTransform; // 일치하는 자세가 없을 때의 기본 변환
  poses: SpritePose[]; // 커밋은 최대 64개까지 허용
  activation: 'whileHeld' | 'onPress'; // 기본 whileHeld. onPress는 누른 순간 자세를 한 번 재생하고 idle로 복귀
  pressDurationMs: number; // onPress 재생 시간, 1–5000, 기본 300
  transitionMs: number; // 자세 전환 시간, 0–1000, 기본 0. onPress는 무시하고 pressDurationMs 동안 재생
  transitionEasing: string; // CSS easing, 기본 'cubic-bezier(0.4, 0, 0.2, 1)'
}
 
interface SpritePose {
  poseId?: string; // 안정 자세 신원 (UUID)
  name?: string | null; // 미설정이면 백엔드가 키를 생략합니다
  triggers: string[]; // 키 요소 id 목록, 커밋은 최대 512개까지 허용하며 정렬·중복 제거
  transform: SpriteTransform;
  pivot?: { x: number; y: number } | null; // 상태 이미지의 독립 기준점. null 또는 생략이면 스프라이트의 공통 기준점을 따라갑니다
  imageOverride: string | null; // 이 자세가 활성인 동안 baseImage를 대체
  imageOverrideMetrics: {
    source: string;
    width: number;
    height: number;
  } | null; // imageOverride의 원본 픽셀 크기(정수, 1–32768). 선택 사항이고, 있으면 source가 경로와 정확히 같아야 합니다. imageOverride가 없으면 null로 정규화됩니다
}
 
interface SpriteTransform {
  x: number; // -2000–2000 px
  y: number; // -2000–2000 px
  rotation: number; // -180–180 도
  scale: number; // 0.1–10
}

interface EditorGetResult {
  revision: number;
  document: EditorDocumentV1;
}
 
const { revision, document } = await dmn.editor.get();
console.log(revision, document.keyPositions);

interface EditorCommitRequest {
  baseRevision: number;
  mutationId: string;
  gestureId?: string;
  gestureIds?: string[];
  // keys를 포함한 커밋의 멀티 키 슬롯 지원 선언
  multiKey?: boolean;
  changes: EditorPatchV1;
}
 
interface EditorPluginCommitResult {
  revision: number;
  changedFields: EditorField[];
}
 
const snapshot = await dmn.editor.get();
const result = await dmn.editor.commit({
  baseRevision: snapshot.revision,
  mutationId: crypto.randomUUID(),
  changes: {
    schemaVersion: 1,
    statPositions: nextStatPositions,
    layerGroups: nextLayerGroups,
  },
});
 
console.log('커밋된 revision:', result.revision);

await dmn.editor.commit({
  baseRevision,
  mutationId: crypto.randomUUID(),
  multiKey: true,
  changes: {
    schemaVersion: 1,
    keys: nextKeys,
    keyPositions: nextKeyPositions,
  },
});

type EditorCommitErrorCode =
  | 'REVISION_CONFLICT'
  | 'PLUGIN_REVISION_CONFLICT'
  | 'VALIDATION_FAILED'
  | 'TOO_MANY_GESTURE_IDS'
  | 'INVALID_GESTURE_ID'
  | 'PAIRED_UPDATE_REQUIRED'
  | 'MULTI_KEY_UNSUPPORTED'
  | 'MUTATION_ID_REUSED'
  | 'HISTORY_IN_PROGRESS'
  | 'HISTORY_EPOCH_CONFLICT'
  | 'IO_ERROR';
 
interface EditorCommitError {
  errorCode: EditorCommitErrorCode;
  message: string;
  details?: {
    currentRevision?: number;
    validationCode?: string;
    field?: string;
    currentHistoryEpoch?: number;
  };
  retryable: boolean;
}

interface EditorCommittedV1 {
  schemaVersion: 1;
  revision: number;
  mutationId: string;
  gestureId?: string | null;
  gestureIds?: string[];
  origin?: string;
  changedFields: EditorField[];
  // patch.keys는 KeySlot union(string | MultiKeySlot)
  patch: EditorPatchV1;
}
 
const unsubscribe = dmn.editor.onCommitted((event) => {
  console.log(event.revision, event.changedFields);
  applyEditorPatch(event.patch);
});
 
await unsubscribe.ready;
 
dmn.plugin.registerCleanup(() => {
  unsubscribe();
});