모드 개발자가 자주 묻는 질문
플레이어용 질문은 플레이어가 자주 묻는 질문에 있습니다.
호환성과 버전
Forge·Fabric·NeoForge·Quilt 모드를 쓸 수 있나요?
네 가지 모두 대부분 됩니다. Fabric·Quilt 모드는 Forge 모드나 NeoForge 모드와 한 게임에 섞어 쓸 수 있지만, mixin이 그 로더의 패치와 맞지 않는 모드는 빠집니다(Fabric 모드와 Forge 모드 함께 쓰기). Forge 모드와 NeoForge 모드는 아직 한 게임에서 실행되지 않습니다. Minecraft 26.3에서도 1.2.5부터 로더를 섞어 쓸 수 있습니다(인기 모드 묶음, 헤드리스, 2026-10-28). 1.2.4에서는 이런 게임이 시작에서 멈췄습니다.
| 모드 | 상태 |
|---|---|
| Forge 모드 | Verified Plexus 모드 로더가 Forge와 FML을 그대로 실행합니다. 26.1과 26.2에서 인기 Forge 모드를 함께 넣고 클라이언트에서 저장된 월드를 플레이하고 저장한 뒤 나올 수 있고(26.2는 40개), 실제 전용 서버도 시작됩니다. 빠지는 모드는 Forge도 실행하지 않는 경우뿐입니다. Fabric·Quilt 모드와 함께일 때는 Partial입니다. 26.2에서 빠지는 Fabric API 모듈은 없지만 Architectury, Balm, Lithium과 이것들이 필요한 모드가 빠지며(POLY-COMPAT-224), 외래 모드 88개가 로드되고 78개가 빠집니다(2026-10-28, 1.2.5). 모드마다 기능을 확인하지는 않았습니다 |
| 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 모드 | Verified Plexus 모드 로더가 NeoForge와 그 로더 FML을 그대로 실행합니다. NeoForge 파일은 처음 시작할 때 받습니다. 26.1, 26.1.2, 26.2에서 인기 NeoForge 모드를 함께 넣고 클라이언트에서 저장된 월드를 플레이하고 저장한 뒤 나올 수 있고(26.2는 54개), 실제 전용 서버도 시작됩니다. 빠지는 모드는 NeoForge도 실행하지 못하는 경우뿐입니다. Fabric·Quilt 모드와 함께일 때는 Partial입니다. mixin이 NeoForge 패치와 맞지 않는 Fabric·Quilt 모드는 로드하지 않으며(POLY-COMPAT-224), 26.2에서는 Fabric API 모듈 10개와 그 모듈이 필요한 Fabric 모드가 여기에 해당합니다. 나머지로 외래 모드 40개와 NeoForge 모드 40개가 26.2 게임 테스트 서버에서 월드를 만들고 저장합니다(2026-10-27, 1.2.4). Forge 모드와는 함께 실행되지 않으며, 이때는 Forge가 실행되고 NeoForge 모드가 빠집니다(POLY-COMPAT-221). 모드마다 기능을 확인하지는 않았습니다 |
| Quilt 모드 | Verified 26.1, 26.1.2, 26.2에서 버전마다 Modrinth의 Quilt 전용 빌드 전체로 클라이언트, 게임 테스트 서버, 전용 서버에서 확인했고, 실제 Quilt Loader의 결과와도 비교했습니다. 빠지는 모드는 Quilt Loader에서도 로드되지 않거나 실행되지 않는 경우뿐입니다. quilt.mod.json을 Quilt Loader의 의미로 읽고 Quilt Loader API를 제공합니다. Quilt Standard Libraries(QSL)는 26.x 판이 없어서, QSL이 필요한 모드는 빠집니다(POLY-COMPAT-114와 308). fabric.mod.json도 든 Quilt 모드는 Fabric 모드로 실행합니다(310). Forge·NeoForge 모드와 함께일 때는 Fabric 모드와 같은 한계가 있습니다. 모드마다 기능을 확인하지는 않았습니다 |
막힌 모드는 로드하지 않습니다. 이유는 로그와 .poly/startup-report.json에 남고, 나머지 모드는 그대로 로드됩니다. 호환성을 보세요. Fabric 모드와 Forge 모드를 한 게임에서 쓰려면 Fabric 모드와 Forge 모드 함께 쓰기를 보세요.
Minecraft 버전마다 모드를 다시 빌드해야 하나요?
Native API만 쓰는 모드라면 그럴 필요가 없습니다. poly.mod.json의 minecraft에 "26.*"나 ">=26.2 <27"처럼 적어 두면, Plexus 모드 로더가 새 버전을 지원하는 시점에 다시 빌드하지 않아도 그 버전에서 실행됩니다. 다만 그 버전의 게임 계층이 모드가 쓰는 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=<버전>을 붙입니다. 쓰는 Plexus 모드 로더가 지원하는 버전만 고를 수 있습니다. Plexus 모드 로더 1.4.0는 26.1, 26.1.1, 26.1.2, 26.2, 26.3를 지원합니다. 자세한 내용은 테스트 실행을 참고하세요.
매핑은 왜 없나요?
필요 없기 때문입니다. Mojang은 Minecraft 26.1부터 Java Edition을 난독화하지 않고 원래 이름 그대로 배포합니다. Plexus 모드 로더의 변환 규칙도 대상 클래스와 메서드를 Mojang 원래 이름과 JVM descriptor로 직접 적습니다. 26.x에서는 Fabric·NeoForge 모드도 같은 이름을 사용합니다.
Native API만 쓰는 모드는 Minecraft 이름을 아예 쓰지 않습니다. Native API에는 Minecraft 타입이 없고, 게임 버전마다 Plexus 모드 로더의 게임 계층이 이를 구현합니다.
설치와 배포
설치 프로그램이나 공개 Maven 저장소가 있나요?
네, 둘 다 있습니다.
- 플레이어는 다운로드 페이지의 설치 프로그램으로 Plexus 모드 로더를 설치합니다. 설치 프로그램이 Minecraft 런처에 Plexus 모드 로더 프로필을 추가합니다. 자세한 내용은 설치 안내를 참고하세요.
- 모드 개발자에게는 Plexus 모드 로더 소스가 필요 없습니다. 웹사이트의 Maven 저장소
https://www.plexusmc.net/maven/에 모드 템플릿,dev.polymodloader.mod플러그인, Plexus 모드 로더 자체가 소스 코드 없이 올라 있습니다. 자세한 내용은 모드 템플릿 받기를 참고하세요.
아직 없는 기능은 아직 없는 기능에서 확인할 수 있습니다.
만든 모드 jar는 어디에 넣나요?
build/libs/에 생긴 jar를 Plexus 모드 로더 실행 환경의 run/client/mods/(서버는 run/server/mods/)에 넣습니다. 서버와 클라이언트가 같은 콘텐츠를 사용하는 모드는 양쪽에 같은 버전의 jar를 넣어야 합니다. 자세한 내용은 빌드·실행·배포를 참고하세요.
Plexus 모드 로더가 Minecraft EULA에 동의하나요?
아니요. Plexus 모드 로더는 사용자를 대신해 동의하지 않습니다.
runServer는run/server/eula.txt에eula=true가 없으면 게임을 시작하기 전에 안내 메시지와 함께 실패합니다. EULA를 직접 읽어 보고 동의한다면 그 파일을 직접 만드세요.serverBootSmokeTest는 매번 빈 디렉터리에서 서버를 시작하므로 서버가 EULA 확인 단계에서 멈추고, 작업은 거기까지의 로그만 확인합니다.worldCreateSaveTest와gameTests는 Mojang 게임 테스트 서버를 사용하므로 EULA 파일이 필요 없습니다.
자세한 내용은 테스트 실행을 참고하세요.
온라인 서버나 Realms에서 인증 오류가 납니다.
정상 동작입니다. 개발용 실행은 오프라인 계정(PolyDev)을 사용하므로 싱글 플레이는 되지만 온라인 서버와 Realms에서는 인증 오류가 납니다. 자세한 내용은 요구 사항을 참고하세요.
API와 오류
API가 버전 사이에 바뀌나요?
바뀔 수 있습니다. Plexus 모드 로더 1.4.0의 공개 API는 모두 PREVIEW 등급이며, 0.1 계열에는 호환성을 보장하는 STABLE API가 없습니다. 바뀐 내용은 변경 기록에서, 등급의 뜻은 API 안정성에서 확인할 수 있습니다.
오류 코드는 어디서 나오나요?
Plexus 모드 로더는 문제가 생기면 POLY-영역-번호 형식의 코드로 알려 줍니다.
poly.mod.json문제(POLY-METADATA-*)는build의validatePolyModJson작업이 먼저 알려 줍니다. 실행할 때도 같은 검사기로 한 번 더 검사합니다.- 실행 중 발생한 문제는 콘솔과
run/<side>/logs/latest.log에 나옵니다. 시작이 멈추면Plexus 모드 로더 launch stopped in phase …뒤에 코드가 표시됩니다. - 로드하지 않은 모드의 사유는
.poly/startup-report.json에도 남습니다.
코드의 뜻과 조치 방법은 오류 코드에서, 증상별 조치는 문제 해결에서 볼 수 있습니다. 이미 있는 코드의 뜻은 바꾸지 않으며, 새로운 문제에는 새 번호를 붙입니다.