# v1 → v2 마이그레이션 가이드

v1에서 v2로 전환하는 방법을 설명합니다. 기존 코드 대부분은 **그대로 동작**합니다. 변경이 필요한 부분은 아래 두 가지뿐입니다.

---

## 1. Import 방식 변경 (필수)

### v1 (5줄)
```python
import sys, os, pymxs

_p = os.path.join(pymxs.runtime.getDir(pymxs.runtime.Name("userScripts")), "os_fast_ref_package")
if _p not in sys.path:
    sys.path.append(_p)

from os_fast_ref.api import FastRefAPI
```

### v2 (1줄)
```python
from os_fast_ref.api import FastRefAPI
```

v2 `.mzp` 설치 시 startup 스크립트(`fast_ref_register_path.ms`)가 자동으로 등록되어 Max 실행 직후부터 경로 설정 없이 import됩니다.

> **주의:** v2 `.mzp`로 재설치하지 않으면 한 줄 import가 동작하지 않습니다. 반드시 최신 MZP로 재설치하세요.

---

## 2. slot 타입 규칙 강화 (확인 필요)

v2에서는 `slot` 인자에 `int`만 허용합니다. `bool`, `str`, `float` 등은 `TypeError`를 즉시 발생시킵니다.

### 영향받는 메서드
`remove_reference`, `replace_reference`, `reload_reference`, `merge_reference`, `set_space_activate`, `set_unpack`, `export_fbx`

### 확인 사항
```python
# This v1 pattern raises TypeError in v2
slot = "0"   # string slot
api.remove_reference(slot=slot)  # TypeError!

# Correct approach
slot = int(slot)
api.remove_reference(slot=slot)  # OK
```

---

## 3. 신규 메서드 (선택적 활용)

| 메서드 | 설명 |
| --- | --- |
| `get_outdated_references()` | OUTDATED 레퍼런스 목록만 반환 |
| `reload_outdated_references()` | OUTDATED 레퍼런스만 리로드 |
| `refresh()` | InfoNode 강제 재스캔 |

기존 코드에서 사용하지 않아도 무관합니다.

---

## 4. FBX preset 키워드 (선택적 활용)

`export_fbx` / `export_fbx_all`에 `preset=` 키워드가 추가되었습니다. 기존 `fbx_options=dict` 방식은 그대로 동작합니다.

```python
# v1 style (still works in v2)
api.export_fbx(slot=0, output_path=r"J:\output\char.fbx",
               fbx_options={"Animation": False})

# v2 new — specify by preset name
api.export_fbx(slot=0, output_path=r"J:\output\char.fbx", preset="Unreal_Ani")
```

---

## 5. 쓰기 작업의 silent 보장

v1에서는 Space OFF 레퍼런스가 있는 씬에서 add/remove/replace 등을 호출하면 Smart Switch 확인창이 표시될 수 있었습니다.

v2 공개 API는 **항상 silent 모드**로 동작합니다. 확인창이 표시되지 않습니다.

---

## 빠른 변환 예시

### Before (v1)
```python
import sys, os, pymxs

_p = os.path.join(pymxs.runtime.getDir(pymxs.runtime.Name("userScripts")), "os_fast_ref_package")
if _p not in sys.path:
    sys.path.append(_p)

from os_fast_ref.api import FastRefAPI

api = FastRefAPI()
api.reload_all_references()
api.export_fbx_all(output_folder=r"J:\output")
api.update_ui()
```

### After (v2)
```python
from os_fast_ref.api import FastRefAPI

api = FastRefAPI()
api.reload_outdated_references()          # reload only OUTDATED
api.export_fbx_all(
    output_folder=r"J:\output",
    preset="Unreal_Ani"                   # specify preset by name
)
api.update_ui()
```