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)

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)

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

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

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.

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

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)

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