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.

from os_fast_ref.api import FastRefAPI

v1 Users: The 5-line sys.path boilerplate is no longer needed. → v1 → v2 Migration Guide

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

api = FastRefAPI()

On initialization failure:

# 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

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

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

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

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

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)

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)

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

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

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().