Unreal PSK/PSA 파일을 위한 블렌더 플러그인: 기초부터 활용까지

이 플러그인은 블렌더(Blender)에서 언리얼 엔진(Unreal Engine)의 PSK(정적 메시) 및 PSA(애니메이션) 파일을 가져오고 내보낼 수 있게 해줍니다. 프로젝트 주소: https://gitcode.com/gh_mirrors/io/io_scene_psk_psa

핵심 기능: PSK/PSA 파일 처리 방법

PSK와 PSA 포맷의 차이점

• PSK 포맷: 정적 메시 모델 파일로, 정점, 텍스처 좌표, 그리고 뼈대 데이터를 포함합니다. 캐릭터나 객체의 기본 모델을 가져올 때 사용됩니다.
• PSA 포맷: 애니메이션 시퀀스 파일로, 뼈대 애니메이션의 키프레임 데이터를 저장합니다. PSK 모델과 함께 사용해야 애니메이션 효과를 구현할 수 있습니다.

핵심 파일 기능 지도

파일 경로	기능 설명	연관성
io_scene_psk_psa/psk/import_/operators.py	PSK 파일 가져오기 로직을 구현하며, 파일 파싱 및 씬 재구성을 포함합니다.	psk/importer.py의 모델 빌드 기능에 의존합니다.
io_scene_psk_psa/psa/export/operators.py	PSA 애니메이션 내보내기를 처리하며, NLA 트랙과 키프레임 압축을 지원합니다.	shared/helpers.py의 뼈대 변환 도구를 호출합니다.
io_scene_psk_psa/shared/types.py	PSK/PSA 데이터 구조(PsxBone, PskBuildOptions 등)를 정의합니다.	모든 가져오기/내보내기 모듈에서 참조하는 데이터 기반이 됩니다.
io_scene_psk_psa/__init__.py	플러그인 등록 진입점으로, 블렌더 호환성 정보를 선언합니다.	psk/psa 하위 모듈의 등록 함수를 통합합니다.

빠른 시작: 3단계로 PSK 모델 가져오기

준비: 플러그인 설치

1. 프로젝트 소스코드 다운로드: git clone https://gitcode.com/gh_mirrors/io/io_scene_psk_psa
2. 블렌더 실행 → 편집 → 기본 설정 → 플러그인 → 설치
3. 다운로드한 디렉터리의 io_scene_psk_psa 폴더를 선택하고 플러그인을 활성화합니다.

작업 흐름: PSK 파일 가져오기 단계

PSK 가져오기 핵심 매개변수

• 축척 비율: 0.01을 권장합니다 (블렌더와 언리얼의 단위 차이를 맞추기 위해)
• 뼈대 공간: "WORLD"를 선택하여 전역 좌표 일관성을 유지합니다.
• 재질 가져오기: "재질 가져오기"를 선택하면 원본 텍스처 연결을 유지할 수 있습니다.

플러그인 등록 메커니즘 상세: 블렌더가 플러그인을 어떻게 인식하는가?

기술적 배경: 블렌더 플러그인 작동 원리

블렌더는 __init__.py 파일의 bl_info 메타데이터와 register() 함수를 스캔하여 플러그인을 로드합니다. 사용자가 플러그인을 활성화하면, register() 함수가 각 모듈의 등록 함수를 호출하여 가져오기/내보내기 옵션을 블렌더의 메뉴 시스템에 추가합니다.

등록 흐름 분석

1. 메타데이터 정의: bl_info 딕셔너리가 플러그인 이름, 버전, 호환성 정보를 선언합니다.
2. 모듈 가져오기: psk와 psa 하위 모듈의 등록 함수를 가져옵니다.
3. 등록 구현: register() 함수가 모든 기능 구성 요소를 일괄 등록합니다.

핵심 코드 예제:

plugin_info = {
    "name": "Unreal PSK/PSA Importer/Exporter",
    "author": "Darklight Games",
    "version": (7, 1, 0),
    "blender": (2, 80, 0),
    "location": "파일 > 가져오기-내보내기",
    "description": "PSK/PSA 파일 가져오기 및 내보내기",
    "category": "가져오기-내보내기"
}

def activate_plugin():
    # PSK 가져오기 및 내보내기 기능 등록
    from .psk.import_ import operators as psk_import_ops
    from .psk.export import operators as psk_export_ops
    psk_import_ops.register()
    psk_export_ops.register()
    # PSA 관련 기능 등록...

개인화된 설정 가이드: 작업 흐름 최적화

시나리오별 설정 제안

게임 애니메이터 설정 방안

• 가져오기 설정:
  • "뼈대 애니메이션 최적화"를 활성화하여 키프레임 수를 줄입니다.
  • FPS 소스를 "사용자 지정"으로 설정하고 게임 엔진 프레임율(예: 30fps)과 일치시킵니다.
• 내보내기 설정:
  • "선택된 뼈대만"을 선택하여 애니메이션 데이터 양을 줄입니다.
  • "압축 비율"을 0.1로 활성화합니다 (품질과 파일 크기의 균형).

기술 아티스트 설정 방안

• 재질 처리:
  • psk/export/properties.py에서 재질 명명 규칙을 조정합니다.
  • "재질 목록 필터" 기능을 사용하여 임시 재질을 제외합니다.
• 메시 최적화:
  • "삼각형화 메시"를 활성화하여 엔진 호환성을 보장합니다.
  • "법선 계산"을 "가중 평균"으로 설정하여 모델의 부드러움을 향상시킵니다.

설정 파일 위치

모든 사용자 설정은 블렌더의 기본 설정 디렉터리에 저장됩니다. 플러그인 패널에서 수정한 매개변수는 자동으로 저장되므로, 수동으로 설정 파일을 편집할 필요가 없습니다.

일반적인 문제 해결: 가져오기 및 내보내기 실패 문제 해결

문제 1: PSK 파일을 가져온 후 모델 위치가 잘못됨

가능한 원인: 좌표계 불일치
해결책:

1. 가져오기 대화 상자에서 "앞면 축"을 X, "위쪽 축"을 Z로 설정합니다.
2. 축척 비율을 0.01로 조정합니다 (언리얼 단위 변환).

문제 2: PSA 애니메이션을 가져온 후 뼈대가 비틀림

주의사항:

• PSK 모델과 PSA 애니메이션의 뼈대 이름이 완전히 일치하는지 확인합니다.
• "뼈대 매핑" 설정을 확인하고, shared/helpers.py의 뼈대 이름 변경 도구를 사용하여 명명 규칙을 통일합니다.

문제 3: PSA 내보내기 시 진행률 표시줄이 멈춤

기술 분석:

• 대형 애니메이션 시퀀스는 메모리 오버플로를 유발할 수 있습니다. psa/export/operators.py에서 frame_step 매개변수를 조정하여 샘플링률을 줄여보세요.
• 순환 종속성이 있는 NLA 트랙이 있는지 확인하고, "불필요한 트랙 정리" 기능을 사용하여 애니메이션 데이터를 최적화하세요.

고급 기능 탐색: 가져오기 및 내보내기 로직 사용자 정의

확장 개발 입문

psk/builder.py와 psa/builder.py를 수정하여 모델과 애니메이션의 빌드 로직을 사용자 정의할 수 있습니다. 예를 들어:

• 사용자 정의 정점 색상 처리 추가
• 특정 뼈대 제약 조건의 변환 구현

기능 확장 예제

# psk/builder.py에 사용자 정의 메시 처리 추가
def create_psk_model(context, selected_objects, options):
    # 기존 빌드 로직...
    # 사용자 정의 정점 법선 계산 추가
    mesh.calculate_split_normals()
    # 사용자 정의 UV 매핑 적용
    apply_custom_uv_mapping(mesh)
    return final_result

라이선스 정보

이 프로젝트는 GPL-3.0 라이선스(오픈 소스 소프트웨어 허가 계약)를 채택하여 자유롭게 사용 및 수정이 가능하지만, 파생 작품도 동일하게 오픈 소스로 유지해야 합니다. 전체 라이선스 텍스트는 프로젝트 루트 디렉터리의 COPYING 파일에서 확인할 수 있습니다.

테스트 및 검증

프로젝트는 tests/ 디렉터리에 완전한 테스트 케이스를 제공합니다. test.sh를 실행하면 PSK/PSA 가져오기 및 내보내기 테스트를 실행하여 플러그인 기능이 정상적으로 작동하는지 확인할 수 있습니다. 테스트 데이터에는 tests/data/Shrek.psk 및 tests/data/Shrek.psa와 같은 다양한 포맷 샘플이 포함되어 있습니다.