# Fast Ref API 개요 (v2)

Fast Ref API는 외부 스크립트에서 Fast Ref 워크플로를 자동화하기 위한 Python 인터페이스입니다.

---

## v2 주요 변경점

| 항목 | v1 | v2 |
| --- | --- | --- |
| Import | sys.path 5줄 보일러플레이트 필수 | 한 줄: `from os_fast_ref.api import FastRefAPI` |
| 공개 메서드 수 | 16개 | 20개 |
| 쓰기 작업 | 일부 씬 상태에 따라 확인창 표시 가능 | 항상 silent (확인창 없음) |
| FBX 내보내기 | fbx_options=dict 만 지원 | preset= 키워드 추가 지원 |
| slot 타입 검증 | 범위/빈슬롯만 검증 | int 타입 검증 추가 (bool 포함) |
| Max 지원 버전 | 2022 / 2025 | 2022 / 2025 / 2027 |

---

## 설계 원칙

| 항목 | 방침 |
| --- | --- |
| 읽기(READ) | UI 불필요 — 씬 InfoNode에서 직접 읽기 |
| 쓰기(WRITE) | UI 독립 + 항상 silent |
| 데이터 로드 | 세션 내 캐시 활용 |
| FBX 옵션 | preset 키워드 또는 dict |
| 공개 표면 | 20개 고정 (semver 약속) |

---

## API 메서드 목록 (20개)

| 카테고리 | 메서드 | 설명 |
| --- | --- | --- |
| 조회 | `get_reference_list()` | 씬의 레퍼런스 목록 반환 |
| 조회 | `check_file_status()` | 소스 파일 최신/변경/누락 상태 확인 |
| 조회 | `get_outdated_references()` | OUTDATED 레퍼런스만 반환 [v2 신규] |
| 조회 | `get_fbx_default_options()` | 현재 FBX 기본 프리셋 옵션 조회 |
| 조회 | `refresh()` | InfoNode 강제 재스캔 [v2 신규] |
| 관리 | `add_reference()` | 레퍼런스 추가 |
| 관리 | `remove_reference()` | 레퍼런스 제거 |
| 관리 | `replace_reference()` | 레퍼런스 파일 교체 |
| 관리 | `reload_reference()` | 단일 레퍼런스 리로드 |
| 관리 | `reload_all_references()` | 전체 레퍼런스 리로드 |
| 관리 | `reload_outdated_references()` | OUTDATED 레퍼런스만 리로드 [v2 신규] |
| FBX 내보내기 | `export_fbx()` | 단일 레퍼런스 FBX 내보내기 (preset 지원) |
| FBX 내보내기 | `export_fbx_all()` | 전체 레퍼런스 일괄 FBX 내보내기 (preset 지원) |
| 고급 | `merge_reference()` | 단일 레퍼런스를 씬 오브젝트로 변환 |
| 고급 | `merge_all_references()` | 전체 레퍼런스 일괄 변환 |
| 고급 | `set_space_activate()` | 네임스페이스 ON/OFF 전환 |
| 고급 | `set_unpack()` | Unpack ON/OFF 전환 |
| 고급 | `convert_to_reference()` | 선택 오브젝트를 레퍼런스로 변환 |
| UI 연동 | `update_ui()` | Fast Ref UI 수동 갱신 |

---

## 핵심 개념

### 슬롯 (Slot)
Fast Ref는 레퍼런스를 0~9번 슬롯으로 관리합니다. v2에서는 `slot`이 반드시 `int`여야 합니다.
```python
api.remove_reference(slot=0)     # OK
api.remove_reference(slot="0")   # TypeError: slot must be int
api.remove_reference(slot=True)  # TypeError: slot must be int
```

### Space Activate
레퍼런스의 네임스페이스 적용 여부를 제어합니다. OFF 상태에서는 노드, 레이어, SelectionSet 이름에서 네임스페이스 접두사가 제거됩니다.

### Unpack
레퍼런스 노드들을 최상위 그룹 컨테이너에서 분리해 월드로 꺼냅니다.

### FBX 프리셋 (v2 신규)
`export_fbx` / `export_fbx_all`에 `preset` 키워드를 지정하면 저장된 프리셋을 이름 한 단어로 적용합니다.
```python
api.export_fbx(slot=0, output_path=r"J:\output\char.fbx", preset="Unreal_Ani")
```
존재하지 않는 프리셋 이름 → `ValueError` 즉시 발생.

---

## 반환값 구조
```python
{"success": bool, "message": str}
# on failure, also includes:
{"success": False, "message": str, "error": str}
```

---

## 예외 처리 규칙

| 상황 | 동작 |
| --- | --- |
| 파일이 존재하지 않음 | `FileNotFoundError` 발생 |
| 잘못된 슬롯 번호 / 빈 슬롯 | `ValueError` 발생 |
| slot이 int가 아님 (bool 포함) | `TypeError` 발생 [v2 추가] |
| 존재하지 않는 FBX 프리셋 이름 | `ValueError` 발생 [v2 추가] |
| 잘못된 인수 타입 | `TypeError` 발생 |
| 라이센스 인증 실패 | 초기화 시 `PermissionError` 발생 |
| 작업 실패 (복구 가능) | `{"success": False, ...}` 반환 |