# 설치 & 빠른 시작

## 요구 사항
- 3ds Max 2022 / 2025 / 2027
- Fast Ref 공식 `.mzp` 인스톨러로 설치 완료
- 유효한 Fast Ref 라이센스

---

## 임포트 — 한 줄로 시작 (v2)
v2부터는 **경로 설정이 필요 없습니다.** `.mzp` 설치 시 startup 스크립트(`fast_ref_register_path.ms`)가 자동으로 등록되어, Max 실행 직후부터 아래 한 줄로 임포트할 수 있습니다.
```python
from os_fast_ref.api import FastRefAPI
```
> **v1 사용자 참고:** 기존 `sys.path` 5줄 보일러플레이트는 더 이상 필요하지 않습니다. → [v1 → v2 마이그레이션 가이드](migration-v1-to-v2.md)

---

## 초기화
`FastRefAPI()` 인스턴스를 생성하면 자동으로 두 가지 작업이 실행됩니다:
1. **라이센스 인증** — 라이센스가 유효하지 않으면 `PermissionError` 발생
2. **씬 데이터 로드** — InfoNode에서 현재 씬의 레퍼런스 데이터를 로드
```python
api = FastRefAPI()
```
On initialization failure:
```python
# Invalid or missing license
# → PermissionError: 🔐 License authentication failed.

# License module not found (installation error)
# → ImportError: 🔐 Fast_Ref license system is missing.
```

---

## 빠른 시작 예제

### 씬 레퍼런스 목록 조회
```python
from os_fast_ref.api import FastRefAPI

api = FastRefAPI()
refs = api.get_reference_list()

print(f"{refs['count']} references in scene")
for ref in refs['data']:
    print(f"  [{ref['slot']}] {ref['name']}  ({ref['namespace']})")
```

### 파일 상태 확인
```python
from os_fast_ref.api import FastRefAPI

api = FastRefAPI()
status = api.check_file_status()
for s in status['data']:
    print(f"  {s['name']}: {s['status']}")
    # status: "latest" / "outdated" / "missing" / "converted"
```

### OUTDATED 레퍼런스만 확인
```python
from os_fast_ref.api import FastRefAPI

api = FastRefAPI()
outdated = api.get_outdated_references()
for r in outdated['data']:
    print(f"  [{r['slot']}] {r['name']} — source file changed")
```

### 레퍼런스 추가
```python
from os_fast_ref.api import FastRefAPI

api = FastRefAPI()
result = api.add_reference(r"J:\assets\character.max")
if result['success']:
    print(f"Added to slot {result['slot']}")
```

### 레퍼런스 교체
```python
from os_fast_ref.api import FastRefAPI

api = FastRefAPI()
result = api.replace_reference(slot=0, new_file=r"J:\assets\character_v2.max")
```

### FBX 내보내기 (단일)
```python
from os_fast_ref.api import FastRefAPI

api = FastRefAPI()
result = api.export_fbx(slot=0, output_path=r"J:\output\character.fbx")
```

### FBX 내보내기 — 프리셋 지정 (v2 신규)
```python
from os_fast_ref.api import FastRefAPI

api = FastRefAPI()
result = api.export_fbx(
    slot=0,
    output_path=r"J:\output\character.fbx",
    preset="Unreal_Ani"
)
```

### FBX 전체 일괄 내보내기
```python
from os_fast_ref.api import FastRefAPI

api = FastRefAPI()
result = api.export_fbx_all(output_folder=r"J:\output")
print(f"Exported: {result['exported_count']}, Failed: {result['failed_count']}")
```

### 파이프라인 전체 흐름 예제
```python
from os_fast_ref.api import FastRefAPI

api = FastRefAPI()

# 1. Reload only OUTDATED references
result = api.reload_outdated_references()
print(f"Reloaded: {result['success_count']} succeeded")

# 2. Export all FBX (Unreal preset)
result = api.export_fbx_all(
    output_folder=r"J:\pipeline\output",
    preset="Unreal_Ani"
)

for r in result['results']:
    status_str = "OK" if r['success'] else "FAIL"
    print(f"  [{r['slot']}] {r['name']}: {status_str}")

# 3. Refresh Fast Ref UI (if open)
api.update_ui()
```

---

## 주의 사항
- API는 **현재 3ds Max에 열린 씬**에서 동작합니다. 대상 씬을 먼저 열어두고 호출하세요.
- 쓰기 작업(add / remove / replace 등)은 씬을 직접 수정합니다. 변경 사항을 유지하려면 씬 파일을 수동으로 저장하세요.
- 공개 API의 모든 쓰기 작업은 **자동으로 silent 모드**로 실행됩니다. 확인 다이얼로그가 표시되지 않습니다.
- Fast Ref UI가 열려 있는 상태에서 API 작업 후 화면을 동기화하려면 `api.update_ui()`를 호출하세요.