v1 → v2 마이그레이션 가이드

v1에서 v2로 전환하는 방법을 설명합니다. 기존 코드 대부분은 그대로 동작합니다. 변경이 필요한 부분은 아래 두 가지뿐입니다.

1. Import 방식 변경 (필수)

v1 (5줄)

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

from os_fast_ref.api import FastRefAPI

v2 .mzp 설치 시 startup 스크립트(fast_ref_register_path.ms)가 자동으로 등록되어 Max 실행 직후부터 경로 설정 없이 import됩니다.

주의: v2 .mzp로 재설치하지 않으면 한 줄 import가 동작하지 않습니다. 반드시 최신 MZP로 재설치하세요.

2. slot 타입 규칙 강화 (확인 필요)

v2에서는 slot 인자에 int만 허용합니다. bool, str, float 등은 TypeError를 즉시 발생시킵니다.

영향받는 메서드

remove_reference, replace_reference, reload_reference, merge_reference, set_space_activate, set_unpack, export_fbx

확인 사항

# 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. 신규 메서드 (선택적 활용)

기존 코드에서 사용하지 않아도 무관합니다.

4. FBX preset 키워드 (선택적 활용)

export_fbx / export_fbx_all에 preset= 키워드가 추가되었습니다. 기존 fbx_options=dict 방식은 그대로 동작합니다.

# 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 보장

v1에서는 Space OFF 레퍼런스가 있는 씬에서 add/remove/replace 등을 호출하면 Smart Switch 확인창이 표시될 수 있었습니다.

v2 공개 API는 항상 silent 모드로 동작합니다. 확인창이 표시되지 않습니다.

빠른 변환 예시

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