디버깅과 유효성 검사

컴파일 오류 대응

셰이더 코드를 작성하다 오타나 타입 불일치 등 문법 실수가 발생해도 MMDX12가 강제 종료되지 않습니다:

1. 자동 안전 복구: 오류가 발생한 캐릭터는 즉시 기본 MMD 셰이딩으로 전환되어 화면이 깨지지 않고 유지됩니다.
2. 화면 알림: 상단에 빨간색 오류 알림 바가 표시됩니다.
3. 셰이더 관리자 진단: 상단 셰이더 탭을 열면 해당 팩의 상태가 컴파일 오류(Compile Error)로 표시되며, 오른쪽 상세 패널에 DXC 컴파일러의 원문 오류 메시지가 출력됩니다.
4. 로그 파일 확인: MMDX12.exe 실행 파일 바로 옆에 생성되는 mmdx12.log 파일에서 [E]로 시작하는 라인을 확인하면 정확한 소스 파일명과 줄 번호를 찾을 수 있습니다:

   [E] surface.hlsl:48:12: error: no matching function for call to 'smoothstep'

독립 검증 도구: pack_check.exe

MMDX12.exe와 같은 폴더에 함께 배포되는 pack_check.exe는 앱을 실행하지 않고도 팩의 정합성을 검사할 수 있는 명령줄 도구입니다.

사용법

pack_check.exe <팩 폴더 또는 팩.zip> [--compile]

주요 검사 항목

• 매니페스트 구조: pack.json 필수 필드(version, name), ID 규칙, 파라미터 개수(최대 16개), 재질 클래스 구문 검사.
• 파일 제약 조건: 압축 해제 용량 32MB 이하, 파일 개수 200개 이하, 허용되지 않은 파일 확장자나 심볼릭 링크 포함 여부.
• 오프라인 셰이더 컴파일 (--compile): DXC를 호출하여 래스터 및 레이 트레이싱 셰이더를 실제로 컴파일해 봅니다.

종료 코드 및 CI 활용

• 0: 검증 성공 (문제 없음)
• 1: 경고 또는 치명적 오류 발견

GitHub Actions나 자동화 빌드 파이프라인에서 풀 리퀘스트 시 팩의 유효성을 검증하는 데 최적화되어 있습니다:

# CI 스크립트 예시
pack_check.exe ./my_pack --compile
if [ $? -ne 0 ]; then
  echo "셰이더 팩 검증 실패"
  exit 1
fi

템플릿 제작과 실시간 핫 리로드

1. 앱 내 셰이더 관리자에서 새 팩 만들기를 클릭하여 템플릿 기반으로 시작합니다.
2. MMDX12는 백그라운드에서 팩 폴더를 지속적으로 감시합니다.
3. pack.json, *.hlsl, *.hlsli, 미리보기 이미지를 저장하는 즉시 캐시를 갱신하고 재컴파일을 수행합니다.
4. 상단 메뉴나 단축키 조작 없이 편집기에서 Ctrl + S를 누르는 것만으로 화면이 즉시 새로고침됩니다.

헤드리스(Headless) 캡처 테스트

화면을 일일이 조작하지 않고 특정 프레임의 렌더링 결과를 이미지 파일로 추출하여 셰이더 결과를 빠르게 확인할 수 있습니다:

MMDX12.exe --character "ModelName" --song "SongName" --autoplay --shader-pack my_pack --frames 600 --capture out.png

이 명령은 600번째 프레임까지 자동 재생한 뒤 out.png로 캡처하고 종료하므로, 셰이더 변경 전후의 시각적 비교에 매우 유용합니다.