# Fast Ref API — Overview

Fast Ref API is a Python interface for automating Fast Ref workflows from external scripts. Designed for Technical Artists (TAs) at partner studios.

---

## v2 Key Changes

| Item | v1 | v2 |
| --- | --- | --- |
| Import | 5-line sys.path boilerplate required | One line: `from os_fast_ref.api import FastRefAPI` |
| Public methods | 16 | 20 |
| Write operations | Confirmation dialog may appear in some scene states | Always silent (no dialogs) |
| FBX export | `fbx_options=dict` only | `preset=` keyword added |
| slot type validation | Range/empty-slot only | int type check added (including bool) |
| Max supported versions | 2022 / 2025 | 2022 / 2025 / 2027 |

---

## Design Principles

| Item | Policy |
| --- | --- |
| READ operations | No UI required — reads directly from scene InfoNode |
| WRITE operations | UI-independent + always silent |
| Data loading | Session-level caching |
| FBX options | `preset` keyword or `dict` |
| Public surface | Fixed at 20 methods (semver guarantee) |

---

## API Method List (20 methods)

| Category | Method | Description |
| --- | --- | --- |
| Query | `get_reference_list()` | Returns the list of references in the scene |
| Query | `check_file_status()` | Checks source file status (latest/outdated/missing) |
| Query | `get_outdated_references()` | Returns only OUTDATED references [v2 new] |
| Query | `get_fbx_default_options()` | Returns current FBX default preset options |
| Query | `refresh()` | Force-rescans the InfoNode [v2 new] |
| Manage | `add_reference()` | Add a reference |
| Manage | `remove_reference()` | Remove a reference |
| Manage | `replace_reference()` | Replace a reference file |
| Manage | `reload_reference()` | Reload a single reference |
| Manage | `reload_all_references()` | Reload all references |
| Manage | `reload_outdated_references()` | Reload only OUTDATED references [v2 new] |
| FBX Export | `export_fbx()` | Export a single reference as FBX (preset support) |
| FBX Export | `export_fbx_all()` | Export all references as FBX in batch (preset support) |
| Advanced | `merge_reference()` | Convert a single reference to scene objects |
| Advanced | `merge_all_references()` | Convert all references to scene objects |
| Advanced | `set_space_activate()` | Toggle namespace ON/OFF |
| Advanced | `set_unpack()` | Toggle Unpack ON/OFF |
| Advanced | `convert_to_reference()` | Convert selected objects to a reference |
| UI | `update_ui()` | Manually refresh Fast Ref UI |

---

## Key Concepts

### Slot
Fast Ref manages references in slots 0–9. In v2, `slot` must be an `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
Controls whether namespace prefixes are applied to a reference. When OFF, namespace prefixes are removed from node, layer, and SelectionSet names.

### Unpack
Detaches reference nodes from their top-level group container and moves them to the world level.

### FBX Preset (v2 new)
Specifying the `preset=` keyword in `export_fbx` / `export_fbx_all` applies a saved preset with a single word.
```python
api.export_fbx(slot=0, output_path=r"J:\output\char.fbx", preset="Unreal_Ani")
```
Non-existent preset name → immediately raises `ValueError`.

---

## Return Value Structure
```python
{"success": bool, "message": str}
# on failure, also includes:
{"success": False, "message": str, "error": str}
```

---

## Error Handling Rules

| Situation | Behavior |
| --- | --- |
| File does not exist | Raises `FileNotFoundError` |
| Invalid slot number / empty slot | Raises `ValueError` |
| slot is not int (including bool) | Raises `TypeError` [v2 new] |
| Non-existent FBX preset name | Raises `ValueError` [v2 new] |
| Invalid argument type | Raises `TypeError` |
| License authentication failure | Raises `PermissionError` during initialization |
| Operation failure (recoverable) | Returns `{"success": False, ...}` |