[Week14] FMOD 연동

[Unity/FMOD] FMOD Studio와 Unity Integration 버전 불일치로 인한 ERR_VERSION 에러 해결기

이슈 1: ERR_VERSION — FMOD Studio와 Unity Integration 버전 불일치

1. 이슈

FMOD Studio에서 새 이벤트(event:/SFX/Player/PlayerFootsteps)를 만들고 빌드까지 정상적으로 마쳤는데, Unity에서 다음과 같은 에러가 발생했음.

FMOD Studio: Encountered Error: ERR_VERSION The version number of this file format is not supported.
UnityEngine.Debug:LogError (object)
FMODUnity.RuntimeUtils:DebugLogError (string)
FMODUnity.EditorUtils:CheckResult (FMOD.RESULT)
FMODUnity.EventManager:UpdateCache ()
FMODUnity.EventManager:RefreshBanks ()
FMODUnity.EventManager:Startup ()

뱅크 파일(.bank)은 정상적으로 빌드되었고, 경로 설정도 문제없었음. 하지만 Unity가 해당 뱅크 파일의 "포맷 버전"을 인식하지 못하는 상황이었음.

추가로, 그 직전 단계에서는 아래와 같은 에러도 함께 발생했었음.

FMOD: Bank refresh failed: .../Build/Desktop/Master.strings.bank is not a valid bank.

이 두 에러는 증상은 비슷해 보이지만 원인이 서로 다르다는 걸 나중에 알게 됐음.

2. 해결 시도

처음에는 "뱅크 파일 자체가 문제"라고 생각하고 다음 순서로 시도했음.

1. Unity 재시작
   • "Bank refresh failed: ... is not a valid bank" 에러는 Unity를 껐다 켜니 사라졌음.
   • 원인은 FMOD Studio가 .bank 파일을 디스크에 다 쓰기 전에 Unity의 자동 Bank Refresh가 먼저 트리거되어, 아직 완전히 쓰여지지 않은 파일을 읽으려다 발생한 것이었음. 재시작 시점에는 빌드가 끝나 있어서 정상 파일을 읽게 되어 해결된 것이었음.
2. 뱅크 재빌드 + Refresh Banks 수동 실행
   • FMOD Studio에서 다시 빌드하고, Unity 메뉴의 FMOD > Refresh Banks를 수동으로 눌러봄.
   • "invalid bank" 에러는 더 이상 나지 않았지만, 이번엔 ERR_VERSION 에러가 새로 나타났음.
3. FMOD 캐시/경로 점검
   • Assets/Plugins/FMOD/Cache 폴더, Build Path, Source Bank Path 설정을 모두 다시 확인.
   • 경로 자체는 정상이었고, 뱅크 파일도 존재했음. → 경로/캐시 문제는 아니라고 판단했음.

여기까지 시도하면서 "파일은 정상적으로 존재하고 빌드도 되는데, 왜 읽지를 못할까?"라는 의문이 들었고, 결국 버전 정보를 확인해보게 됐음.

3. 해결 방법

원인은 FMOD Studio 앱 버전과 Unity의 FMOD Integration 버전이 서로 다른 것이었음.

• FMOD Studio: 2.03.14
• Unity의 FMOD Integration: 2.02.x (Welcome 패키지의 문서 링크가 /docs/2.02/unity를 가리키고 있어서 확인 가능했음)

FMOD는 .bank 파일의 포맷이 메이저.마이너 버전(2.02 vs 2.03)에 따라 달라지기 때문에, FMOD Studio에서 2.03 버전으로 빌드한 뱅크 파일을 2.02 버전의 Unity Integration이 읽으려고 하면 ERR_VERSION 에러가 발생함.

해결은 두 가지 방법 중 하나로 가능했음.

• 방법 A (선택한 방법): Unity Integration을 2.03으로 업그레이드
  1. fmod.com/download에서 FMOD Studio와 동일한 2.03.x 버전의 "Unity Integration" 패키지(.unitypackage)를 다운로드
  2. Unity 프로젝트에 임포트하여 기존 Assets/Plugins/FMOD를 덮어쓰기
  3. FMOD > Edit Settings에서 버전이 2.03으로 표시되는지 확인
  4. Assets/Plugins/FMOD/Cache 폴더 삭제 후 Unity 재시작
• 방법 B: FMOD Studio를 2.02.x로 다운그레이드
  • 팀 전체가 같은 FMOD Studio 버전을 쓴다는 전제하에 가능한 선택지지만, 이미 2.03으로 작업한 이벤트/뱅크가 있다면 다시 호환성 문제가 생길 수 있어 권장하지 않음.

업그레이드 후 Unity를 재시작하니 ERR_VERSION 에러가 사라지고, PlayerFootsteps 이벤트도 정상적으로 인식됐음.

4. 알게 된 점

• "빌드는 됐는데 Unity에서 안 읽히는" 에러는 크게 두 종류로 나뉠 수 있었음.
  • 파일이 일시적으로 불완전한 경우 (is not a valid bank) → 보통 타이밍 문제, 재시작이나 수동 Refresh로 해결.
  • 파일 포맷 버전 자체가 안 맞는 경우 (ERR_VERSION) → 재시작/재빌드로는 절대 해결되지 않으며, 버전을 맞춰야만 해결됨.
• FMOD Studio와 FMOD for Unity Integration은 한 쌍으로 관리해야 함.
  • 둘 중 하나만 업데이트하면 마이너 버전 차이만으로도 뱅크를 읽을 수 없게 됨.
  • 팀 프로젝트라면 "우리 프로젝트는 FMOD 버전 X.XX.XX를 사용한다"는 걸 README나 위키에 명시해두는 게 좋음. (Unity 버전을 통일하는 것처럼 FMOD 버전도 통일이 필요했음.)
• Welcome 메시지의 문서 링크에 버전 정보가 숨어있었음.
  • FMOD > Edit Settings뿐만 아니라, 패키지 임포트 시 뜨는 Welcome 메시지의 문서 URL(/docs/2.02/unity 등)로도 현재 Integration 버전을 짐작할 수 있었음.
• 에러 메시지를 그대로 검색하기보다, "왜 이 메시지가 나왔는지"를 역추적하는 게 빨랐음.
  • ERR_VERSION이라는 키워드 자체보다, "파일은 존재하는데 왜 못 읽지?"라는 질문에서 버전 호환성으로 사고를 확장한 게 해결의 핵심이었음.

---

이슈 2: Unity Integration 업그레이드 시 마법사 단계들 (Setup Wizard / File Reorganizer)

1. 이슈

이슈 1의 해결책으로 "FMOD for Unity"의 최신 패키지를 다운로드해서 임포트했음. 그런데 임포트 후 FMOD Studio Unity Integration 정보 창을 확인해보니 버전이 2.02.34로 표시됨.

FMOD Studio Unity Integration
Version: 2.02.34

FMOD Studio는 2.03.14인데, 다운로드한 "최신 버전"이 왜 2.02.34인지 의문이 들었음. 다운로드 폴더를 다시 확인해보니 두 개의 파일이 있었음.

• fmodstudio20313 (Unity package file)
• fmodstudio20314win64-installer (응용 프로그램)

즉, FMOD for Unity 2.03.13 패키지는 이미 다운로드되어 있었지만, 실제로 Unity에 임포트된 건 그 전에 받아둔 구버전(2.02.34)이었던 것.

2. 해결 시도 / 진행 과정

fmodstudio20313 파일을 Unity로 가져와 덮어쓰기 임포트를 진행했음. 이때부터 단순 파일 복사가 아니라, FMOD가 자동으로 띄우는 두 개의 마법사 창을 순서대로 처리해야 했음.

(1) FMOD Setup Wizard — 네이티브 라이브러리 교체

Welcome to FMOD for Unity 2.03.13.
To complete the installation, we need to update the FMOD native libraries.

1. Disable Existing Native Libraries
2. Restart Unity
3. Copy New Native Libraries

버전이 바뀌면서 fmodstudioL.dll 등 네이티브 플러그인 파일도 함께 교체해야 하는데, Unity가 기존 파일을 사용 중(잠금)이라 다음 순서가 필요했음.

1. 기존 네이티브 라이브러리 비활성화
2. Unity 재시작 (잠금 해제)
3. 새 버전 라이브러리 복사 및 활성화

(2) FMOD File Reorganizer — 오래된 플랫폼 파일 정리

Task 1: Move .../platforms/html5/lib/libfmodstudiounityplugin.bc
        to .../platforms/obsolete/libfmodstudiounityplugin.bc
Task 2: Move .../platforms/html5/lib/libfmodstudiounitypluginL.bc
        to .../platforms/obsolete/libfmodstudiounitypluginL.bc
Task 3~5: 비어있는 html5 관련 폴더 제거

버전업 과정에서 폴더 구조가 일부 바뀌면서, 더 이상 쓰지 않는 HTML5 플랫폼용 플러그인 파일을 obsolete 폴더로 옮기고 빈 폴더를 정리하는 작업이었음.

3. 해결 방법

두 마법사 모두 버튼을 순서대로 눌러서 그대로 진행하면 됐음.

1. Setup Wizard에서 Disable Existing Native Libraries → Restart Unity → Copy New Native Libraries 순서로 클릭
2. File Reorganizer에서 Process 5 Tasks 클릭 (HTML5 빌드를 쓰지 않는 프로젝트라 영향 없음)
3. 모든 단계 완료 후 Assets/Plugins/FMOD/Cache 폴더 삭제
4. Unity 재시작 후 FMOD > Refresh Banks 실행

이후 Integration 버전이 2.03.13으로 정상 반영되었고, FMOD Studio(2.03.14)와 마이너 버전(2.03)이 일치하게 되어 ERR_VERSION 에러 없이 PlayerFootsteps 이벤트가 정상 인식됐음.

4. 알게 된 점

• "최신 버전 다운로드"가 항상 "최신 임포트"를 의미하지는 않음.
  • 이미 다운로드해놓은 구버전 패키지가 있으면, 실수로 그걸 임포트하게 될 수 있음. 다운로드 폴더에 여러 버전의 .unitypackage가 섞여 있을 때는 파일명에 적힌 버전 숫자를 직접 확인하는 습관이 필요함.
• Integration 버전을 올릴 때는 단순 파일 덮어쓰기가 아니라 "마법사"가 동반됨.
  • 네이티브 플러그인(DLL 등) 교체는 Unity의 파일 잠금 때문에 Disable → Restart → Copy 단계가 필요하고, 폴더 구조 변경 사항은 File Reorganizer가 자동으로 정리해줌. 둘 다 FMOD가 제공하는 정상 절차이므로 안내대로 따라가면 됨.
• 버전 정보는 여러 군데서 확인 가능함.
  • Welcome 창의 문서 링크(/docs/2.0x/unity), FMOD Studio Unity Integration 정보 창(Version: x.xx.xx), Setup Wizard 제목(Welcome to FMOD for Unity x.xx.xx) 등에서 모두 현재 Integration 버전을 교차 확인할 수 있었음.