설치 & 빠른 시작

요구 사항

• 3ds Max 2022 / 2025 / 2027
• Fast Ref 공식 .mzp 인스톨러로 설치 완료
• 유효한 Fast Ref 라이센스

임포트 — 한 줄로 시작 (v2)

v2부터는 경로 설정이 필요 없습니다. .mzp 설치 시 startup 스크립트(fast_ref_register_path.ms)가 자동으로 등록되어, Max 실행 직후부터 아래 한 줄로 임포트할 수 있습니다.

from os_fast_ref.api import FastRefAPI

v1 사용자 참고: 기존 sys.path 5줄 보일러플레이트는 더 이상 필요하지 않습니다. → v1 → v2 마이그레이션 가이드

초기화

FastRefAPI() 인스턴스를 생성하면 자동으로 두 가지 작업이 실행됩니다:
1. 라이센스 인증 — 라이센스가 유효하지 않으면 PermissionError 발생
2. 씬 데이터 로드 — 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.

빠른 시작 예제

씬 레퍼런스 목록 조회

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']})")

파일 상태 확인

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"

OUTDATED 레퍼런스만 확인

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

레퍼런스 추가

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']}")

레퍼런스 교체

from os_fast_ref.api import FastRefAPI

api = FastRefAPI()
result = api.replace_reference(slot=0, new_file=r"J:\assets\character_v2.max")

FBX 내보내기 (단일)

from os_fast_ref.api import FastRefAPI

api = FastRefAPI()
result = api.export_fbx(slot=0, output_path=r"J:\output\character.fbx")

FBX 내보내기 — 프리셋 지정 (v2 신규)

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

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']}")

파이프라인 전체 흐름 예제

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

주의 사항

• API는 현재 3ds Max에 열린 씬에서 동작합니다. 대상 씬을 먼저 열어두고 호출하세요.
• 쓰기 작업(add / remove / replace 등)은 씬을 직접 수정합니다. 변경 사항을 유지하려면 씬 파일을 수동으로 저장하세요.
• 공개 API의 모든 쓰기 작업은 자동으로 silent 모드로 실행됩니다. 확인 다이얼로그가 표시되지 않습니다.
• Fast Ref UI가 열려 있는 상태에서 API 작업 후 화면을 동기화하려면 api.update_ui()를 호출하세요.