Fast Ref API
/
Overview
Fast Ref API — Overview
Download MarkdownFast 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 | 30 |
| Write operations | Confirmation dialog may appear in some scene states | Always silent (no dialogs) |
| FBX export | fbx_options=dict only |
preset= keyword added |
| Alembic export | none | export_abc / export_abc_all / get_abc_default_options |
| Get Nodes | none (old select_* only) |
seven get_* APIs (query + optional scene select) |
| 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 / Alembic options | preset keyword or dict (+ Export Type: ExportMeshes/ExportBones) |
| Public surface | 30 methods (semver guarantee) |
API Method List (30 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 | get_abc_default_options() |
Returns current Alembic default preset options |
| Query | refresh() |
Force-rescans the InfoNode [v2 new] |
| Get Nodes | get_all_objects() |
Query all reference nodes in a slot (optional scene select) |
| Get Nodes | get_skin_meshes() |
Query skin mesh nodes (optional scene select) |
| Get Nodes | get_skin_bones() |
Query skin bone nodes (optional scene select) |
| Get Nodes | get_all_skin_objects() |
Query skin meshes + bones (optional scene select) |
| Get Nodes | get_duplicate_nodes() |
Query duplicate-name nodes (optional scene select) |
| Get Nodes | get_biped_com() |
Query Biped COM nodes (optional scene select) |
| Get Nodes | get_biped_nodes() |
Query all Biped nodes (optional scene select) |
| 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 / Export Type) |
| FBX Export | export_fbx_all() |
Export all references as FBX in batch (preset / Export Type) |
| Alembic Export | export_abc() |
Export a single reference as Alembic (preset / Export Type) |
| Alembic Export | export_abc_all() |
Export all references as Alembic in batch |
| 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 |
| Advanced | set_namespace() |
Rename reference namespace |
| 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.
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.
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
{"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 / Alembic preset name | Raises ValueError |
| Invalid argument type | Raises TypeError |
| License authentication failure | Raises PermissionError during initialization |
| Operation failure (recoverable) | Returns {"success": False, ...} |