이 가이드는 Legion Hosting에서 호스팅되는 Project Zomboid 서버의 고급 모드 문제 해결을 다룹니다. 아직 모드를 설치하지 않았다면 먼저 기본 모드 설치 가이드부터 시작하세요. 이 문서는 WorldDictionary 손상, 모드 형식 오류, 로드 순서 충돌, 서버와 클라이언트 간 버전 불일치를 포함하여 Legion Hosting 지원 티켓에서 가장 흔히 보이는 모드 관련 문제를 다룹니다.

시작하기 전에

• GPanel에 로그인하고 Project Zomboid 서버를 선택합니다.
• 구성 또는 파일 변경을 하기 전에 서버를 중지합니다.
• 수정을 시도하기 전에 SFTP 또는 GPanel을 통해 월드 세이브 폴더(/.cache/saves/multiplayer/)를 백업합니다. 파일 전송에 익숙하지 않다면 SFTP 가이드를 참조하세요.
• 서버의 .ini 파일 경로를 준비해 두세요: /.cache/server/<servername>.ini(예: servertest.ini).

---

1. 모드 형식 오류(B42 대 B41)

모드가 로드되지 않는 가장 흔한 이유는 서버의 .ini 파일에 있는 Mods= 줄의 형식이 잘못되었기 때문입니다. Build 42와 Build 41은 서로 다른 구문을 사용하며, 이를 혼동하면 모드가 조용히 로드에 실패합니다.

B42 형식(현재 기본값)

Build 42는 Mods= 줄에서 각 Mod ID 앞에 백슬래시 접두사가 필요합니다:

Mods=\ModID1;\ModID2;\ModID3;

DLMP 형식은 Workshop ID와 Mod ID를 백슬래시 구분자로 결합합니다:

Mods=2392987841\ModID1;1550458773\ModID2;2786383654\ModID3;

WorkshopItems= 줄은 두 빌드 모두에서 동일한 세미콜론으로 구분된 형식을 사용합니다:

WorkshopItems=2392987841;1550458773;2786383654

B41 형식(레거시)

Build 41은 백슬래시 없이 일반 세미콜론으로 구분된 Mod ID를 사용합니다:

Mods=ModID1;ModID2;ModID3

해결 방법

1. GPanel 파일 관리자에서 /.cache/server/<servername>.ini를 엽니다.
2. Mods= 줄을 찾아 위의 예시와 형식을 비교합니다.
3. 빌드 버전에 형식이 잘못되었다면 수정합니다. Legion Hosting Mod Organizer를 사용하여 올바르게 포맷된 줄을 자동으로 생성하세요.
4. 파일을 저장하고 서버를 시작합니다.

---

2. WorldDictionary 손상

WorldDictionary는 아이템 이름을 내부 숫자 ID에 매핑하는 파일(WorldDictionary.bin)입니다. 모드가 추가되거나 제거되면 사전이 손상되어 서버가 시작 시 WorldDictionaryException과 함께 충돌할 수 있습니다.

증상

• 콘솔 또는 debug.log에 WorldDictionaryException 또는 WorldDictionary 오류가 표시됩니다.
• 서버가 시작 중, 특히 월드 로딩 중에 즉시 충돌합니다.
• 모드를 추가, 제거 또는 업데이트한 후 충돌이 시작되었습니다.

위험 이해하기

복구 단계

1. GPanel에서 서버를 중지합니다.
2. SFTP를 통해 전체 세이브 폴더를 백업합니다: 전체 /.cache/saves/multiplayer/<YourWorldName>/ 디렉터리를 로컬 컴퓨터로 다운로드합니다.
3. 먼저 오류를 일으킨 모드 변경을 단순히 되돌려 보세요. 모드를 방금 추가했다면 .ini 파일의 Mods=와 WorkshopItems= 모두에서 제거합니다. 모드를 방금 제거했다면 다시 추가합니다. 서버를 시작하고 충돌이 해결되는지 확인합니다.
4. 모드 변경을 되돌려도 효과가 없으면 SFTP를 통해 연결하고 /.cache/saves/multiplayer/<YourWorldName>/로 이동합니다.
5. WorldDictionary.bin을 삭제합니다.
6. 서버를 시작합니다. Project Zomboid가 시작 시 사전을 다시 생성합니다.
7. 서버에 접속하여 손상된 아이템, 사라진 차량 또는 깨진 인벤토리가 있는지 월드를 검사합니다. 월드가 심각하게 손상된 경우 2단계에서 생성한 백업에서 복원하세요.

---

3. Authentic Z 모드 충돌

Authentic Z는 가장 인기 있는 Project Zomboid 모드 컬렉션 중 하나이지만, 서로 충돌하는 여러 하위 모드를 포함하고 있기 때문에 빈번한 지원 티켓의 원인이 됩니다.

규칙

흔한 실수

• Authentic Z - Current와 Authentic Z - Litemode를 동시에 추가하는 것.
• 싱글플레이어용으로 설계된 Authentic Z 하위 모드를 멀티플레이어 버전과 함께 추가하는 것.
• 서로 다른 Authentic Z 하위 모드가 동일한 Workshop ID를 공유하지만 서로 다른 Mod ID를 가지고 있어, Workshop 다운로드는 성공하지만 서버가 충돌하는 모드 파일을 로드한다는 것을 인지하지 못하는 것.

해결 방법

1. GPanel 파일 관리자에서 /.cache/server/<servername>.ini를 엽니다.
2. Mods= 줄에서 Authentic 또는 AuthenticZ를 포함하는 모든 항목을 검색합니다.
3. 하나의 Authentic Z 하위 모드만 유지합니다(권장: Authentic Z - Current). Mods=와 WorkshopItems= 줄 모두에서 다른 모든 Authentic Z 항목을 제거합니다.
4. 파일을 저장하고 서버를 재시작합니다.

---

4. Linux 대소문자 구분 문제

Legion Hosting 서버는 파일 및 폴더 이름이 대소문자를 구분하는 Linux에서 실행됩니다. MyMod.lua라는 이름의 파일과 mymod.lua는 완전히 다른 두 개의 파일로 취급됩니다. 이는 모드 제작자가 Windows(대소문자 구분 안 함)에서 개발하고 그들의 모드에 일치하지 않는 파일 참조가 포함되어 있을 때 문제를 일으킵니다.

증상

• 모드가 Windows PC의 싱글플레이어에서는 완벽하게 작동하지만 서버에서는 실패합니다.
• 콘솔 또는 debug.log에 모드 내부의 Lua 스크립트나 텍스처를 참조하는 FileNotFoundException 또는 can't find file 오류가 표시됩니다.
• 오류가 모드 폴더에 실제로 존재하는 파일을 가리키지만 다른 대소문자 표기를 가지고 있습니다(예: 코드는 Items.txt를 참조하지만 실제 파일 이름은 items.txt입니다).

진단 방법

1. 콘솔 또는 /.cache/Logs/ 로그 파일에서 오류에 언급된 정확한 파일 경로를 확인합니다.
2. SFTP를 통해 연결하고 /steamapps/workshop/content/108600/<WorkshopID>/에 있는 모드 폴더로 이동합니다.
3. 디스크의 파일 이름을 오류 메시지에 참조된 파일 이름과 비교합니다. 대소문자 차이를 찾으세요.

해결 방법

• 파일 이름을 바꿀 수 있는 경우: SFTP를 통해 연결하고 모드 코드가 예상하는 대소문자와 일치하도록 파일 이름을 변경합니다. 이 수정 사항은 모드가 Steam Workshop에서 업데이트되면 덮어쓰여진다는 점에 유의하세요.
• 문제가 모드 자체에 있는 경우: Steam Workshop 페이지에서 모드 제작자에게 버그를 보고합니다. 파일 참조에 대소문자 불일치가 있으며 Linux 서버에서 실패한다고 언급하세요. 많은 모드 제작자가 Linux 대소문자 구분을 인지하지 못하고 있습니다.
• 임시 해결책으로: 모드의 Workshop 페이지 댓글을 확인하세요 — 다른 Linux 서버 운영자가 수정 사항이나 호환되는 모드 포크를 게시했을 수 있습니다.

---

5. 모드 로드 순서 문제

Project Zomboid는 Mods= 줄에 나타나는 순서대로 모드를 로드합니다. 일부 모드는 다른 모드가 먼저 로드되는 것에 의존합니다. 의존성이 그것을 필요로 하는 모드보다 나중에 로드되면 의존하는 모드가 조용히 실패하거나 오류를 일으킬 수 있습니다.

증상

• 모드 기능이 부분적으로만 작동합니다 — 모드의 일부 아이템이나 시스템은 존재하지만 다른 것들은 누락됩니다.
• 콘솔에 모드의 Lua 스크립트를 참조하는 NullPointerException 또는 attempt to index a nil value 오류가 표시됩니다.
• 오류가 특정 모드 조합이 설치된 경우에만 나타나지만 각 모드는 개별적으로는 잘 작동합니다.

해결 방법

1. 각 모드의 Steam Workshop 페이지에서 "Required Mods" 또는 "Load Order" 섹션을 확인합니다. 많은 모드 제작자가 자신의 모드보다 먼저 로드되어야 하는 모드를 명시합니다.
2. /.cache/server/<servername>.ini를 열고 Mods= 줄을 찾습니다.
3. 의존성 모드가 그것을 필요로 하는 모드보다 먼저 나타나도록 항목을 재정렬합니다. 예를 들어 Mod B가 Mod A를 필요로 한다면 줄은 Mods=\ModA;\ModB;(B42 형식)로 읽혀야 합니다.
4. 프레임워크 및 라이브러리 모드(ModFramework, TsarLib, Shark's Mod Utils 등)는 항상 Mods= 줄에서 맨 먼저 나열되어야 합니다.
5. 파일을 저장하고 서버를 재시작합니다.

---

6. 모드 추가 후 서버 충돌

서버가 잘 실행되다가 하나 이상의 모드를 추가한 후 충돌한다면, 새 모드가 원인일 가능성이 높습니다. 이 섹션은 문제 모드를 격리하는 과정을 안내합니다.

단계별 격리

1. GPanel에서 서버를 중지합니다.
2. 파일 관리자에서 /.cache/server/<servername>.ini를 엽니다.
3. 방금 추가한 모든 모드를 기록합니다. Mods=와 WorkshopItems= 줄 모두에서 그것들 전부를 제거합니다.
4. 서버를 시작합니다. 성공적으로 시작되면 문제는 제거한 모드 중 하나에 있습니다.
5. 각 추가 후 서버를 재시작하면서 한 번에 하나씩 모드를 다시 추가합니다. 충돌이 다시 발생하면 마지막으로 추가한 모드가 원인입니다.
6. 식별이 되면 모드의 Workshop 페이지에서 다음을 확인하세요:
   • B42 호환성에 대한 참고 사항 — 많은 B41 모드가 B42용으로 업데이트되지 않았습니다.
   • 실행 중인 다른 모드와의 알려진 충돌.
   • 설치하지 않았을 수 있는 필수 의존성 모드.

충돌 로그 읽기

격리 과정을 수행하기 전에 충돌 로그를 확인하세요 — 종종 문제 모드를 직접 가리킵니다:

1. GPanel에서 Console 탭을 열고 출력의 끝으로 스크롤합니다.
2. STACK TRACE, Exception 또는 ERROR 줄을 찾습니다.
3. 스택 추적 바로 위의 줄은 일반적으로 모드 파일 이름이나 Mod ID를 참조합니다 — 이는 어떤 모드가 충돌을 일으켰는지 알려줍니다.
4. 더 자세한 내용은 SFTP를 통해 /.cache/Logs/에서 전체 로그 파일을 열고 가장 최근의 DebugLog-server.txt 또는 debug.log 파일을 확인하세요.

---

7. 모드 버전 불일치(서버 대 클라이언트)

Project Zomboid는 서버와 연결된 모든 클라이언트가 모든 모드의 동일한 버전을 가지고 있어야 합니다. 모드가 Steam Workshop에서 업데이트되고 서버는 새 버전을 다운로드하지만 플레이어는 여전히 이전 버전을 캐시에 가지고 있는 경우(또는 그 반대), 연결 실패나 충돌이 발생합니다.

증상

• 플레이어가 연결을 시도할 때 "Mod mismatch" 또는 "Version mismatch" 오류가 발생합니다.
• 일부 플레이어는 연결할 수 있지만 다른 플레이어는 할 수 없습니다 — 연결할 수 없는 플레이어는 로컬에 다른 모드 버전이 캐시되어 있습니다.
• 서버가 잘 작동하다가 모드가 Steam Workshop에서 업데이트되고 갑자기 일부 플레이어가 참가할 수 없게 되었습니다.
• 플레이어가 최근에 업데이트된 모드의 누락된 텍스처, 아이템 또는 깨진 UI 요소를 봅니다.

서버 운영자를 위한 해결책

1. GPanel에서 서버를 중지합니다.
2. 서버를 다시 시작합니다. 시작 시 서버는 모든 Workshop 모드의 최신 버전을 다시 다운로드합니다. 이렇게 하면 서버가 최신 버전을 실행하게 됩니다.
3. 서버에 여전히 이전 버전이 캐시되어 있으면 SFTP를 통해 연결하여 /steamapps/workshop/content/108600/<WorkshopID>/에 있는 해당 모드의 Workshop 캐시 폴더를 삭제합니다. 서버를 재시작하여 깨끗한 다운로드를 강제합니다.

플레이어를 위한 해결책

모드 버전 불일치로 인해 연결할 수 없는 플레이어는 다음을 수행해야 합니다:

1. Steam을 열고 Library → Project Zomboid로 이동합니다.
2. Project Zomboid를 마우스 오른쪽 버튼으로 클릭하고 Properties → Local Files → Verify Integrity of Game Files를 선택합니다.
3. 또한 로컬 컴퓨터에서 Project Zomboid의 Steam Workshop 폴더로 이동하여 캐시된 모드 파일을 삭제하여 다시 다운로드를 강제합니다.
4. 게임을 실행하고 서버에 다시 연결합니다.

---

8. Steam Workshop 캐시 지우기

여러 모드 문제가 지속되고 Workshop 다운로드 캐시가 손상되었다고 의심되면 모든 Workshop 모드의 완전한 재다운로드를 강제할 수 있습니다.

1. GPanel에서 서버를 중지합니다.
2. SFTP를 통해 연결하고 /steamapps/workshop/로 이동합니다.
3. 전체 workshop/ 폴더(또는 그 내용물)를 삭제합니다.
4. 서버를 시작합니다. Steam이 모든 Workshop 아이템을 처음부터 다시 다운로드합니다.
5. 서버가 월드 로딩을 시작하기 전에 모든 모드가 다운로드를 완료하는지 GPanel 콘솔에서 확인합니다.

---

빠른 진단 참조

---

여전히 모드 문제가 있나요?