# Installation & Quick Start

## Requirements
- 3ds Max 2022 / 2025 / 2027
- Fast Ref installed via the official `.mzp` installer
- A valid Fast Ref license

---

## Import — One Line to Start (v2)
From v2 onwards, **no path setup is required.** The `.mzp` installer automatically registers a startup script (`fast_ref_register_path.ms`) so you can import immediately after launching Max with a single line.
```python
from os_fast_ref.api import FastRefAPI
```
> **v1 Users:** The 5-line `sys.path` boilerplate is no longer needed. → [v1 → v2 Migration Guide](migration-v1-to-v2.md)

---

## Initialization
Creating a `FastRefAPI()` instance automatically performs two tasks:
1. **License authentication** — raises `PermissionError` if the license is invalid
2. **Scene data loading** — loads the current scene's reference data from the 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.
```

---

## Quick Start Examples

### List Scene References
```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']})")
```

### Check File Status
```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"
```

### Filter OUTDATED References Only
```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")
```

### Add a Reference
```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']}")
```

### Replace a Reference
```python
from os_fast_ref.api import FastRefAPI

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

### Export FBX (Single)
```python
from os_fast_ref.api import FastRefAPI

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

### Export FBX — Named Preset (v2 new)
```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"
)
```

### Export All 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']}")
```

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

---

## Notes
- The API operates on **the currently open scene** in 3ds Max. Open the target scene before calling.
- Write operations (add / remove / replace, etc.) directly modify the scene. Save the scene file manually to keep changes.
- All public API write operations run in **automatic silent mode**. No confirmation dialogs are shown.
- To synchronize the display after API operations while Fast Ref UI is open, call `api.update_ui()`.