문제 해결
모드 개발
| 증상 | 원인과 조치 |
|---|---|
플러그인 dev.polymodloader.mod나 dev.polymodloader:… 산출물을 찾을 수 없음 | Gradle이 웹사이트의 Maven 저장소 https://www.polymc.net/maven/에 연결하지 못했거나, build.gradle.kts에 적은 버전이 그곳에 공개되어 있지 않습니다. 인터넷 연결과 버전을 확인하세요. 필요한 파일이 모두 Gradle 캐시에 있으면 --offline으로 오프라인에서도 빌드할 수 있습니다. -PpolyLocalSdk를 붙이면 Maven Local을 먼저 봅니다. 모드 템플릿 받기를 참고하세요. |
Poly 모드 로더 launch stopped in phase … | 로그의 오류 코드(POLY-…)를 오류 코드 표에서 찾아보세요. 엔트리포인트에서 예외가 나면 POLY-ENTRYPOINT-003입니다. |
POLY-CONTENT-002 | 엔트리포인트가 끝난 뒤(이벤트 안 등)에 콘텐츠를 선언했습니다. 선언을 엔트리포인트로 옮기세요. |
POLY-METADATA-… | poly.mod.json이 올바르지 않습니다. 어느 필드가 문제인지는 build가 알려 줍니다. |
POLY-DEPENDENCY-007 | poly.mod.json의 minecraft 목록에 실행 중인 게임 버전과 맞는 항목이 없습니다. 목록을 고치거나(버전 적기) 목록에 맞는 버전으로 실행하세요. |
Minecraft … is not supported by this Poly 모드 로더 build; supported: [...] | polyMinecraft(gradle.properties 또는 -PpolyMinecraft)에 사용 중인 Poly 모드 로더가 지원하지 않는 버전을 적었습니다. 메시지에 나온 지원 목록에서 고르세요. |
runServer가 The Minecraft dedicated server requires accepting the Minecraft EULA로 실패 | run/server/eula.txt에 eula=true가 없습니다. Poly 모드 로더는 사용자를 대신해 동의하지 않습니다. EULA를 직접 읽어 보고 동의한다면 그 파일을 직접 만드세요. |
| 텍스처가 보라·검정 체크무늬 | 모델이나 텍스처 경로의 모드 ID 또는 폴더 이름이 틀렸습니다. build의 checkPolyResources가 없는 모델·텍스처와 빠뜨린 네임스페이스를 파일별로 알려 줍니다(모드 제작 도구). |
POLY-RESOURCE-004~009 (빌드 중) | 리소스 파일 이름, JSON, 참조, 번역 또는 polyResources 선언에 문제가 있습니다. 메시지에 고쳐야 할 경로가 나옵니다. |
| 블록을 부숴도 아무것도 떨어지지 않음 | data/<mod>/loot_table/blocks/<block>.json이 없습니다. |
No data fixer registered for <모드 몹> | 무시해도 됩니다. 데이터 변환 정의가 없는 모드 엔티티에 대해 게임이 시작할 때 남기는 기록입니다. |
| Realms·온라인 서버 인증 오류 로그 | 개발용 실행은 오프라인 계정을 쓰므로 정상입니다. |
실행 환경 복구
| 증상 | 확인할 곳 | 조치 |
|---|---|---|
Poly 모드 로더 launch stopped in phase … | 콘솔과 run/<side>/logs/latest.log의 오류 코드 | 오류 코드 표를 보고 원인이 된 모드를 고치거나 제거합니다. |
| 모드가 로드되지 않음 | run/<side>/.poly/startup-report.json의 blockedFiles·foreignMods | 기능별 POLY-COMPAT-* 사유를 확인합니다. |
게임 클래스를 로드할 때 Fabric 모드가 실패함(POLY-COMPAT-133) | 로그 메시지에 클래스, Mixin, 그 모드가 나옴 | 그 모드를 빼거나 새 버전으로 바꿔 봅니다. |
| 변환 관련 이상 | .poly/transformation-report.json, -Dpoly.transformDumpDir=<dir> | 캐시가 의심되면 -Dpoly.transformCacheDir=none으로 실행해 결과를 비교합니다. 손상된 캐시 항목은 자동으로 버립니다. |
| 다운로드 해시 불일치 | ~/.gradle/caches/poly-minecraft | 문제가 된 파일을 지우고 다시 실행합니다. |
| 월드 손상이 의심됨 | <월드>/poly/mods.properties, 게임의 backups/ | 모드가 빠지거나 버전이 바뀐 월드는 Poly 모드 로더가 불러오기 전에 백업합니다. 자세한 내용은 운영을 참고하세요. 그래도 중요한 월드는 실행하기 전에 직접 백업해 두세요. |
시작 단계 오류 (POLY-BOOTSTRAP)
Poly 모드 로더가 실행 설정, 게임 jar, 버전 어댑터, 게임 계층을 준비하는 중에 발생한 오류입니다. 코드 목록은 오류 코드에서 볼 수 있습니다.
| 코드 | 로그에 나오는 원인 | 조치 |
|---|---|---|
POLY-BOOTSTRAP-001 | 게임 jar에 version.json이 없거나 jar를 읽을 수 없음 | poly.gameJar가 Minecraft 게임 jar를 가리키는지 확인합니다. |
POLY-BOOTSTRAP-002 | no version adapter for Minecraft …: 게임 jar의 버전을 담당하는 버전 어댑터가 없음. 메시지에 이 Poly 모드 로더가 지원하는 버전이 나옴 | 지원하는 버전의 게임으로 실행합니다. 모드 프로젝트에서는 polyMinecraft로 버전을 고릅니다. |
POLY-BOOTSTRAP-003 | invalid launch configuration: …: 필수 시스템 속성(poly.launchTarget, poly.gameJar)이 없거나, poly.launchTarget 값이 틀렸거나, poly.gameJar 파일이 없음. 실행기가 종료 코드 2로 끝남 | 아래 실행기 시스템 속성을 확인합니다. Gradle 실행 작업은 이 값을 자동으로 넣어 줍니다. |
POLY-BOOTSTRAP-004 | 게임 계층 클래스가 dev.polymodloader.game.layer 패키지 밖에 있거나, Poly 모드 로더 클래스 경로에 없거나, jar에 들어 있지 않음 | 버전 어댑터가 게임 계층 jar를 실행 의존성으로 가져옵니다. 클래스 경로를 직접 구성했다면 그 버전의 게임 계층 jar(poly-game-v26_2)가 포함돼 있는지 확인합니다. |
POLY-BOOTSTRAP-005 | 게임 계층을 만들거나 시작하는 중에 예외가 발생함 | 로그에 이어지는 원인 예외를 확인합니다. |
실행기 시스템 속성
Poly 모드 로더 실행기(dev.polymodloader.bootstrap.PolyLauncherMain)는 설정을 Java 시스템 속성(-D…)으로 받습니다. Gradle 실행 작업(runClient, gameTests 등)은 아래 값을 자동으로 넣으므로, 실행기를 직접 띄울 때만 신경 쓰면 됩니다.
| 속성 | 뜻 | 기본값 | Gradle 실행 작업이 넣는 값 |
|---|---|---|---|
poly.launchTarget | client, dedicated_server, game_test_server 중 하나 | 없음(필수) | 작업마다 다름 |
poly.gameJar | Minecraft 게임 jar | 없음(필수) | 다운로드해 검증한 jar |
poly.modsDir | 모드 폴더 | mods | <실행 디렉터리>/mods |
poly.devModJars | 더 로드할 모드 jar. 경로 구분자(Windows ;, 그 밖의 운영체제 :)로 나눔 | 없음 | 모드 프로젝트의 jar |
poly.reportDir | Poly 모드 로더 보고서 디렉터리 | .poly | 기본값 |
poly.transformCacheDir | 변환 캐시 디렉터리. none이면 캐시를 끔 | <poly.reportDir>/transform-cache | build/poly/transform-cache |
poly.transformCacheMaxMegabytes | 변환 캐시 크기 상한(MiB). 넘으면 가장 오래 쓰지 않은 항목부터 지움 | 256 | 기본값 |
poly.transformDumpDir | 변환 전후 클래스 파일을 저장할 디렉터리 | 없음(저장하지 않음) | 넣지 않음 |
상대 경로는 JVM 작업 디렉터리를 기준으로 합니다. Gradle 실행 작업은 실행 디렉터리(run/client 등)를 작업 디렉터리로 사용합니다. 실행기는 나머지 프로그램 인수를 바꾸지 않고 그대로 Minecraft에 넘깁니다.
진단 보고서
Poly 모드 로더는 실행할 때마다 게임 디렉터리의 .poly/에 보고서를 기록합니다.
| 파일 | 내용 |
|---|---|
.poly/startup-report.json | 로드한 모드, 차단한 파일, 활성 시스템, 변환 계획 |
.poly/transformation-report.json | 실제로 변환한 클래스, 변환 전후 해시, 캐시 사용 여부 |
Poly 모드 로더는 시작할 때 단계마다 [Poly 모드 로더] Phase … 로그를 남기며, 단계는 다음 순서로 진행됩니다. BOOTSTRAP(게임 jar 확인) → DISCOVERY(모드 찾기·판정) → METADATA_VALIDATION → DEPENDENCY_RESOLUTION(의존성·링크 검사) → CONFLICT_RESOLUTION(시스템 교체) → TRANSFORMATION_PLANNING → SYSTEM_REGISTRATION → LIFECYCLE_INITIALIZATION(Poly 모드 엔트리포인트) → GAME_LAUNCH. Fabric 모드는 Fabric Loader와 같은 때에 실행합니다. preLaunch는 게임이 시작되기 전에, main·client·server는 그보다 늦게 게임 자체의 시작 과정 안에서 실행합니다. 시작이 멈추면 launch stopped in phase …에 나온 단계 이름으로 어디서 멈췄는지 알 수 있습니다.
버그 제보
이 페이지로 해결되지 않으면 웹사이트에서 버그를 제보해 주세요. 오류 코드(POLY-…)와 logs/latest.log나 크래시 리포트 링크를 함께 적어 주시고, 위의 두 보고서도 도움이 됩니다. 관리자가 모든 제보를 읽습니다.