자주 묻는 질문

호환성과 버전

Forge·Fabric·NeoForge·Quilt 모드를 쓸 수 있나요?

Fabric·Forge 모드는 대부분 됩니다. NeoForge·Quilt 모드는 아직 안 됩니다.

모드	상태
Forge 모드	Verified Poly 모드 로더가 Forge와 FML을 그대로 실행합니다. 26.1과 26.2에서 인기 Forge 모드를 함께 넣고 클라이언트에서 저장된 월드를 플레이하고 저장한 뒤 나올 수 있고(26.2는 40개), 실제 전용 서버도 시작됩니다. 빠지는 모드는 Forge도 실행하지 않는 경우뿐입니다. 모드마다 기능을 확인하지는 않았습니다
Fabric 모드(Mixin·MixinExtras·중첩 jar·class tweaker를 쓰는 모드 포함)	Verified 26.1과 26.2에서 인기 Fabric 모드를 함께 넣고 클라이언트에서 저장된 월드를 플레이하고 저장한 뒤 나올 수 있고(26.2는 실제 모드 138개와 테스트 모드 2개), 실제 전용 서버도 시작됩니다(26.2는 100개). 모드마다 기능을 확인하지는 않았습니다
Fabric Loader 내부 클래스(net.fabricmc.loader.impl)를 쓰는 Fabric 모드	Partial 실제 모드가 쓰는 부분(FabricLauncherBase.getLauncher(), FabricLoaderImpl.getGameProvider())은 제공합니다. 나머지가 필요한 모드는 진단과 함께 빠집니다(POLY-COMPAT-111)
NeoForge 모드	Blocked 기본적으로 진단(POLY-COMPAT-200..205)과 함께 빠집니다. 기본값이 꺼진 실험 기능(-Dpoly.neoforge=on)으로 NeoForge 자체를 실행할 수 있으며, 아직 26.2 서버에서만 확인했습니다
Quilt 모드	지원 예정 아직 quilt.mod.json을 읽지 않으며, fabric.mod.json도 든 Quilt 모드는 Fabric 모드로 판정합니다

막힌 모드는 로드하지 않습니다. 이유는 로그와 .poly/startup-report.json에 남고, 나머지 모드는 그대로 로드됩니다. 호환성을 보세요. Fabric 모드와 Forge 모드를 한 게임에서 쓰려면 Fabric 모드와 Forge 모드 함께 쓰기를 보세요.

Minecraft 버전마다 모드를 다시 빌드해야 하나요?

Native API만 쓰는 모드라면 그럴 필요가 없습니다. poly.mod.json의 minecraft에 "26.*"나 ">=26.2 <27"처럼 적어 두면, Poly 모드 로더가 새 버전을 지원하는 시점에 다시 빌드하지 않아도 그 버전에서 실행됩니다. 다만 그 버전의 게임 계층이 모드가 쓰는 API를 모두 구현하고 있어야 합니다.

변환 규칙(transforms)처럼 특정 버전의 게임 코드에 의존하는 모드는 정확한 버전을 적어야 하며, 이런 모드는 적어 둔 버전에서만 로드됩니다. 버전이 맞지 않으면 POLY-DEPENDENCY-007과 함께 실행이 멈춥니다.

poly.mod.json의 "minecraft"에는 무엇을 적나요?

모드 템플릿은 "26.*"를 사용합니다. Native API만 쓴다면 와일드카드나 범위를 적고, 특정 버전의 게임 코드에 의존한다면 "26.2"처럼 정확한 버전을 적습니다. 형식이 올바르지 않으면 POLY-METADATA-009가 발생합니다. 형식별 설명은 poly.mod.json에서 볼 수 있습니다.

모드를 다른 Minecraft 버전으로 실행하려면 어떻게 하나요?

모드 프로젝트의 gradle.properties에 polyMinecraft=<버전>을 적거나, 명령에 -PpolyMinecraft=<버전>을 붙입니다. 쓰는 Poly 모드 로더가 지원하는 버전만 고를 수 있습니다. Poly 모드 로더 0.2.0-beta.1는 26.1, 26.1.1, 26.1.2, 26.2를 지원합니다. 자세한 내용은 테스트 실행을 참고하세요.

매핑은 왜 없나요?

필요 없기 때문입니다. Mojang은 Minecraft 26.1부터 Java Edition을 난독화하지 않고 원래 이름 그대로 배포합니다. Poly 모드 로더의 변환 규칙도 대상 클래스와 메서드를 Mojang 원래 이름과 JVM descriptor로 직접 적습니다. 26.x에서는 Fabric·NeoForge 모드도 같은 이름을 사용합니다.

Native API만 쓰는 모드는 Minecraft 이름을 아예 쓰지 않습니다. Native API에는 Minecraft 타입이 없고, 게임 버전마다 Poly 모드 로더의 게임 계층이 이를 구현합니다.

설치와 배포

설치 프로그램이나 공개 Maven 저장소가 있나요?

네, 둘 다 있습니다.

• 플레이어는 다운로드 페이지의 설치 프로그램으로 Poly 모드 로더를 설치합니다. 설치 프로그램이 Minecraft 런처에 Poly 모드 로더 프로필을 추가합니다. 자세한 내용은 설치 안내를 참고하세요.
• 모드 개발자에게는 Poly 모드 로더 소스가 필요 없습니다. 웹사이트의 Maven 저장소 https://www.polymc.net/maven/에 모드 템플릿, dev.polymodloader.mod 플러그인, Poly 모드 로더 자체가 소스 코드 없이 올라 있습니다. 자세한 내용은 모드 템플릿 받기를 참고하세요.

아직 없는 기능은 아직 없는 기능에서 확인할 수 있습니다.

만든 모드 jar는 어디에 넣나요?

build/libs/에 생긴 jar를 Poly 모드 로더 실행 환경의 run/client/mods/(서버는 run/server/mods/)에 넣습니다. 서버와 클라이언트가 같은 콘텐츠를 사용하는 모드는 양쪽에 같은 버전의 jar를 넣어야 합니다. 자세한 내용은 빌드·실행·배포를 참고하세요.

Poly 모드 로더가 Minecraft EULA에 동의하나요?

아니요. Poly 모드 로더는 사용자를 대신해 동의하지 않습니다.

• runServer는 run/server/eula.txt에 eula=true가 없으면 게임을 시작하기 전에 안내 메시지와 함께 실패합니다. EULA를 직접 읽어 보고 동의한다면 그 파일을 직접 만드세요.
• serverBootSmokeTest는 매번 빈 디렉터리에서 서버를 시작하므로 서버가 EULA 확인 단계에서 멈추고, 작업은 거기까지의 로그만 확인합니다.
• worldCreateSaveTest와 gameTests는 Mojang 게임 테스트 서버를 사용하므로 EULA 파일이 필요 없습니다.

자세한 내용은 테스트 실행을 참고하세요.

온라인 서버나 Realms에서 인증 오류가 납니다.

정상 동작입니다. 개발용 실행은 오프라인 계정(PolyDev)을 사용하므로 싱글 플레이는 되지만 온라인 서버와 Realms에서는 인증 오류가 납니다. 자세한 내용은 요구 사항을 참고하세요.

API와 오류

API가 버전 사이에 바뀌나요?

바뀔 수 있습니다. Poly 모드 로더 0.2.0-beta.1의 공개 API는 모두 PREVIEW 등급이며, 0.1 계열에는 호환성을 보장하는 STABLE API가 없습니다. 바뀐 내용은 변경 기록에서, 등급의 뜻은 API 안정성에서 확인할 수 있습니다.

오류 코드는 어디서 나오나요?

Poly 모드 로더는 문제가 생기면 POLY-영역-번호 형식의 코드로 알려 줍니다.

• poly.mod.json 문제(POLY-METADATA-*)는 build의 validatePolyModJson 작업이 먼저 알려 줍니다. 실행할 때도 같은 검사기로 한 번 더 검사합니다.
• 실행 중 발생한 문제는 콘솔과 run/<side>/logs/latest.log에 나옵니다. 시작이 멈추면 Poly 모드 로더 launch stopped in phase … 뒤에 코드가 표시됩니다.
• 로드하지 않은 모드의 사유는 .poly/startup-report.json에도 남습니다.

코드의 뜻과 조치 방법은 오류 코드에서, 증상별 조치는 문제 해결에서 볼 수 있습니다. 이미 있는 코드의 뜻은 바꾸지 않으며, 새로운 문제에는 새 번호를 붙입니다.