# v1 → v2 Migration Guide

This guide explains how to migrate from v1 to v2. Most existing code will **work as-is**. Only the two items below require changes.

---

## 1. Import Change (Required)

### v1 (5 lines)
```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 line)
```python
from os_fast_ref.api import FastRefAPI
```

When you install the v2 `.mzp`, a startup script (`fast_ref_register_path.ms`) is automatically registered, so you can import without any path setup from the moment Max starts.

> **Note:** If you don't reinstall with the v2 `.mzp`, the single-line import will not work. Make sure to reinstall with the latest MZP.

---

## 2. Strict slot Type Rule (Review Required)

In v2, only `int` is accepted for the `slot` argument. `bool`, `str`, `float`, etc. immediately raise `TypeError`.

### Affected Methods
`remove_reference`, `replace_reference`, `reload_reference`, `merge_reference`, `set_space_activate`, `set_unpack`, `export_fbx`

### What to Check
```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. New Methods (Optional)

| Method | Description |
| --- | --- |
| `get_outdated_references()` | Returns only OUTDATED reference list |
| `reload_outdated_references()` | Reloads only OUTDATED references |
| `refresh()` | Force-rescans InfoNode |

Not required if not used in existing code.

---

## 4. FBX preset Keyword (Optional)

The `preset=` keyword has been added to `export_fbx` / `export_fbx_all`. The existing `fbx_options=dict` approach still works.

```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 Write Operations Guaranteed

In v1, calling add/remove/replace etc. on a scene with Space OFF references could trigger a Smart Switch confirmation dialog.

The v2 public API always runs in **silent mode**. No confirmation dialogs are shown.

---

## Quick Migration Example

### 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()
```