이 가이드는 Legion Hosting에서 호스팅하는 Project Zomboid 서버에 Steam Workshop 모드를 설치하는 과정을 안내합니다. B42 및 B41 모드 형식, Legion Hosting Mod Organizer 도구, 대형 모드 팩에 대한 호환성 참고 사항, 그리고 일반적인 모드 관련 월드 손상에서 복구하는 방법을 다룹니다.

사전 요구 사항

• gpanel.legionhosting.net에서 접근 가능한 Legion Hosting의 활성 Project Zomboid 서버
• 모드 설정을 편집하기 전에 서버가 Offline 상태여야 합니다 — 먼저 GPanel에서 중지하세요
• 설치하려는 각 모드의 Steam Workshop ID와 Mod ID(각 모드의 Steam Workshop 페이지에서 확인)
• 현재 월드 세이브의 백업(강력히 권장 — 위 경고 참조)

1단계 — 각 모드의 Workshop ID와 Mod ID 찾기

설치하려는 모든 모드에는 두 개의 별도 식별자가 필요합니다:

• Workshop ID — Steam Workshop URL의 숫자 ID, 예: https://steamcommunity.com/sharedfiles/filedetails/?id=2392987841
• Mod ID — 모드 제작자가 정의한 내부 ID로, Workshop 페이지의 모드 설명에서 찾을 수 있으며, 보통 "Mod ID:"로 표시되거나 모드의 mod.info 파일 안에 있습니다

계속하기 전에 모든 모드에 대해 두 ID를 모두 적어 두세요. 하나의 Workshop 항목에 각자 고유한 Mod ID를 가진 여러 하위 모드가 포함되어 있는 경우도 있습니다.

2단계 — Legion Hosting Mod Organizer 사용 (권장)

모드 목록을 만드는 가장 쉬운 방법은 Legion Hosting Zomboid Mod Organizer입니다. Workshop을 검색하고, URL이나 ID로 모드를 추가하며, GPanel에 붙여넣어야 하는 올바르게 형식화된 구성 라인을 자동으로 생성할 수 있습니다.

1. legionhosting.net/zomboid-mod-organizer.php로 이동합니다.
2. 이름으로 모드를 검색하거나 Steam Workshop URL을 검색 상자에 붙여넣습니다.
3. Add 버튼을 사용하여 각 모드를 목록에 추가합니다.
4. 목록이 완성되면 Generate Config를 클릭합니다. 이 도구는 서버의 빌드 버전에 맞게 형식화된 즉시 사용 가능한 WorkshopItems 및 Mods 라인을 출력합니다.
5. 생성된 라인을 복사하고 4단계로 진행하여 서버 설정에 붙여넣습니다.

ID를 수동으로 입력하려면 3단계를 계속하여 빌드 버전에 맞게 올바르게 형식화하세요.

3단계 — 모드 목록을 올바르게 형식화하기

WorkshopItems (모든 빌드에서 동일)

WorkshopItems 라인은 세미콜론을 사용하여 Workshop ID를 구분합니다. 이 형식은 B41과 B42 모두 동일합니다:

Mods — Build 42 (B42) 형식

B42는 각 Mod ID 앞에 백슬래시 접두사(\)를 사용합니다:

DLMP 형식 (B42)

일부 구성은 DLMP 형식을 사용하며, 이는 Workshop ID와 Mod ID를 하나의 필드에서 백슬래시로 결합합니다:

Mods — Build 41 (B41) 형식

B41은 백슬래시 접두사 없이 세미콜론으로 구분된 단순한 Mod ID를 사용합니다:

4단계 — 서버 설정 파일에서 모드 목록 적용하기

1. GPanel에 로그인하고 Project Zomboid 서버를 선택합니다.
2. 서버가 Offline 상태인지 확인합니다. 필요하면 중지합니다.
3. File Manager를 열고 /.cache/server/로 이동합니다.
4. 서버 설정 파일을 엽니다 — <servername>.ini로 이름이 지정되어 있습니다(예: servertest.ini).
5. 파일에서 WorkshopItems= 및 Mods= 라인을 찾습니다. 2단계에서 생성했거나 3단계에서 형식화한 값을 붙여넣습니다.
6. 파일을 저장합니다.
7. 서버를 시작합니다. 시작 시 Steam Workshop 다운로드가 자동으로 시작됩니다.

5단계 — 모드를 점진적으로 추가하고 테스트하기

특히 활성 서버에서 또는 대규모 컬렉션을 다룰 때는 원하는 전체 모드 목록을 한 번에 추가하지 마세요. 대신:

1. 한 번에 3~5개 이하의 모드를 추가합니다.
2. 서버를 시작하고 Running 상태에 도달하는지, 그리고 접속하여 플레이할 수 있는지 확인합니다.
3. 다음 배치를 추가하기 전에 GPanel 콘솔에서 오류 메시지나 스택 트레이스가 있는지 확인합니다.
4. 모든 모드가 로드되고 안정될 때까지 반복합니다.

이 방법을 사용하면 문제가 발생했을 때 어떤 모드가 문제를 일으키는지 훨씬 쉽게 식별할 수 있습니다.

비-Workshop 모드 설치

Steam Workshop에 없는 모드(폴더 또는 ZIP 파일로 다운로드됨)가 있는 경우, SFTP를 통해 서버의 다음 경로에 업로드하세요:

모드 폴더(mod.info 파일을 포함해야 함)를 /.cache/mods/ 바로 안에 넣으세요. GPanel의 SFTP 탭에 표시된 SFTP 자격 증명을 사용하여 이 디렉터리에 접근할 수 있습니다. 업로드 후, 4단계에서 설명한 대로 모드의 mod.info 파일에 있는 Mod ID를 서버 구성의 Mods= 라인에 추가하세요. 비-Workshop 모드에는 Workshop ID가 필요하지 않습니다.

Authentic Z 호환성 참고 사항

Authentic Z는 가장 인기 있는 Project Zomboid 모드 팩 중 하나이지만, 여러 하위 모드로 구성되어 있습니다. 한 번에 하나의 하위 모드만 설치하세요. 멀티플레이어 서버에 권장되는 하위 모드는 다음과 같습니다:

같은 서버에서 여러 Authentic Z 하위 모드를 동시에 활성화하지 마세요. 이 컬렉션에서 둘 이상의 하위 모드를 실행하면 충돌이 발생하여 서버가 충돌하거나 전리품 테이블이 손상될 수 있습니다. 어떤 하위 모드가 활성화되어 있는지 확실하지 않으면 구성의 Mods= 라인을 확인하고 Authentic Z - Current(또는 선택한 단일 하위 모드)만 나열되어 있는지 확인하세요.

확인

새 모드로 서버를 시작한 후, 모드가 성공적으로 로드되었는지 확인하세요:

1. GPanel에서 Console 탭을 열고 시작 로그를 지켜보세요. 각 모드가 로드되는 것을 참조하는 라인을 찾으세요 — 설치된 각 모드에 대해 [ModLoader] Loading mod: ModID와 같은 메시지가 표시되어야 합니다.
2. 게임 내에서 서버에 접속하고 메인 메뉴에서 Mods 메뉴를 엽니다(Esc → Mods). 설치된 모드가 목록에 나타나야 합니다.
3. 콘솔 로그에서 STACK TRACE 문구를 검색하세요. 아무것도 나타나지 않으면 서버가 깨끗하게 시작된 것입니다. 하나가 보이면 트레이스 상단 근처에 언급된 모드를 확인하세요 — 그 모드가 문제의 원인일 가능성이 높습니다.
4. 게임 내에서 돌아다니며 모드가 추가한 콘텐츠(아이템, 건물, 좀비)가 예상대로 나타나는지 확인하세요.

문제 해결

모드가 로드되지 않음 / 서버는 시작되지만 모드가 비활성 상태인 것 같음

• Mods 라인이 빌드에 맞는 올바른 형식을 사용하는지 확인하세요 — B42는 백슬래시 접두사(\ModID), B41은 단순한 Mod ID. WorkshopItems 형식은 두 빌드 모두 동일합니다.
• Mods= 라인의 Mod ID가 모드의 Workshop 설명이나 mod.info 파일에 표시된 ID와 정확히 일치하는지 확인하세요. Mod ID는 대소문자를 구분합니다.
• WorkshopItems 및 Mods 필드가 모두 저장되었는지 확인하세요 — GPanel에서 다른 곳으로 이동했다가 다시 돌아와서 값이 유지되었는지 확인하세요.

Steam Workshop 다운로드 실패 / 시작 시 모드가 다운로드되지 않음

서버는 시작되지만 Workshop 모드가 다운로드되지 않는 것처럼 보이면 Steam 캐시 폴더가 손상되었을 수 있습니다. 이를 해결하려면:

1. GPanel에서 서버를 중지합니다.
2. SFTP를 통해 연결하고 /steamapps/workshop/로 이동합니다.
3. workshop/ 폴더 전체(또는 그 내용물)를 삭제합니다.
4. 서버를 다시 시작합니다. Steam이 모든 Workshop 항목을 처음부터 다시 다운로드합니다.

WorldDictionaryException / 월드 딕셔너리 손상

콘솔 로그에 WorldDictionaryException 오류가 표시되면 월드 딕셔너리가 손상된 것입니다 — 이는 새 아이템이나 타일을 도입하는 모드를 추가하거나 제거할 때 발생할 수 있습니다.

복구를 시도해야 하는 경우:

1. GPanel에서 서버를 중지합니다.
2. SFTP 또는 GPanel Backups를 통해 전체 세이브 폴더를 백업합니다.
3. SFTP를 통해 연결하고 /.cache/saves/multiplayer/<YourWorldName>/로 이동합니다.
4. WorldDictionary.bin을 삭제합니다.
5. 서버를 시작합니다. Project Zomboid가 시작 시 딕셔너리를 재생성합니다.
6. 게임 내에서 손상된 아이템이나 차량이 있는지 확인합니다. 월드가 심각하게 손상된 경우 2단계에서 생성한 백업에서 복원하세요.

콘솔 로그에 STACK TRACE와 함께 시작 시 서버 충돌

시작 직후의 스택 트레이스는 보통 모드 충돌이나 현재 빌드 버전과 호환되지 않는 모드를 나타냅니다. 진단하려면:

1. GPanel에서 Console 로그를 열고 STACK TRACE를 검색합니다.
2. 트레이스 위의 라인에서 언급된 모드 파일 이름이나 Mod ID를 읽습니다 — 이것이 보통 문제의 모드입니다.
3. 해당 모드를 WorkshopItems 및 Mods 라인 모두에서 제거하고, 저장한 다음 서버를 재시작합니다.
4. 제거 후 서버가 깨끗하게 시작되면, 모드의 Workshop 페이지에서 B42 호환 업데이트나 댓글에 알려진 충돌 메모가 있는지 확인하세요.

GPanel 콘솔에서 보여주는 것보다 더 자세한 내용을 보려면 SFTP를 통해 /.cache/Logs/<date>_DebugLog-server.txt에서 전체 debug.log 파일을 열 수도 있습니다.

특정 모드를 가진 플레이어가 접속할 때 서버 충돌

서버가 깨끗하게 실행되지만 플레이어가 접속할 때 충돌하면, 해당 플레이어가 서버와 충돌하는 클라이언트 측 모드를 가지고 있을 수 있습니다. 플레이어에게 게임 내 Mods 메뉴에서 모든 로컬 Project Zomboid 모드를 비활성화하고 다시 접속해 보라고 요청하세요. 충돌이 멈추면, 플레이어는 충돌하는 모드를 찾기 위해 모드를 하나씩 다시 활성화해야 합니다.

모드를 제거했지만 서버가 여전히 로드하려고 함

구성에서 모드의 ID를 제거했지만 서버가 시작 시 여전히 이를 참조하는 경우, Workshop 항목이 여전히 캐시되어 있을 수 있습니다. SFTP를 통해 /steamapps/workshop/content/108600/<workshopID>/에서 특정 Workshop 항목 폴더를 삭제한 다음 서버를 재시작하세요.