Poly 모드 로더 설치 (플레이어)
설치 프로그램은 공식 Minecraft Launcher에 Poly 모드 로더 <Minecraft 버전> 프로필(예: Poly 모드 로더 26.2)을 추가합니다. 이 프로필로 플레이하면 게임이 Poly 모드 로더를 거쳐 시작됩니다.
Poly 모드 로더 1.4.0은 정식 버전입니다. 새 모드를 넣기 전에 아끼는 월드는 백업해 두세요. 지원하는 Minecraft 버전은 26.1, 26.1.1, 26.1.2, 26.2, 26.3입니다.
준비
- Minecraft Launcher에서 쓸 버전(예: 26.2)의 바닐라 Minecraft를 한 번 실행했다가 종료합니다. 이때 게임 파일과 런처용 Java가 다운로드됩니다.
- Minecraft Launcher를 닫습니다. 런처가 켜진 채로 설치하면, 런처가 종료되면서 새 프로필을 지워 버릴 수 있습니다.
다운로드
다운로드 페이지에 모든 Poly 모드 로더 빌드와 빌드별 변경 요약이 있습니다. 파일은 GitHub 릴리스에서 받습니다.
| 파일 | 사용 환경 |
|---|---|
PolyModLoader-<버전>.jar | Windows, macOS, Linux (Java 17 이상 필요) |
설치
PolyModLoader-<버전>.jar를 더블클릭하거나 터미널/명령 프롬프트에서 실행합니다.
java -jar PolyModLoader-<버전>.jar
설치 창에서 Minecraft 버전을 고르고 런처 폴더를 확인한 뒤 설치를 누릅니다.
창은 시스템 언어로 열립니다. 오른쪽 위 메뉴에서 English와 한국어를 바꿀 수 있으며, 입력한 값은 그대로 남습니다.
런처 폴더의 기본값은 Windows %APPDATA%\.minecraft, macOS ~/Library/Application Support/minecraft, Linux ~/.minecraft입니다.
메모리. 게임이 쓸 메모리를 고릅니다.
- 최대 메모리 (-Xmx): PC 메모리에 맞춰 값을 미리 골라 둡니다(8GB면 4G, 16GB 이상이면 6G). 런처 기본값을 고르면 런처 설정(2G)을 그대로 씁니다.
- 시작 메모리 (-Xms): 보통은 지정 안 함으로 둡니다.
이 값은 런처 프로필의 JVM 인수에 들어가므로, 나중에 런처에서 바꿀 수 있습니다. 거기에 따로 적어 둔 다른 JVM 인수는 그대로 남습니다.
설치가 끝나면 성공했는지 알림이 뜹니다. 알림을 누르면 mods 폴더가 열립니다. 설치 프로그램은 저절로 닫힙니다. 열어 두려면 완료되면 설치 프로그램 닫기를 끄세요. 읽어야 할 경고가 있을 때도 닫히지 않습니다.
설치 프로그램은 다음 작업을 합니다.
- Poly 모드 로더 파일을 런처 폴더의
libraries/에 넣습니다. versions/polymodloader-<버전>-<Minecraft 버전>/버전을 만듭니다. 바닐라 게임 파일은 그대로 쓰고, 시작할 때만 Poly 모드 로더를 거칩니다.launcher_profiles.json에 Poly 모드 로더 <Minecraft 버전> 프로필을 추가합니다. 다른 프로필은 건드리지 않으며, 수정하기 전의 파일은launcher_profiles.json.polymodloader-backup으로 남겨 둡니다.mods/폴더를 만듭니다.
다시 설치하면 프로필을 고치거나 새 Poly 모드 로더 버전으로 바꿉니다. 다른 Minecraft 버전으로 설치하면 프로필이 하나 더 생깁니다.
플레이
- Minecraft Launcher를 엽니다.
- 플레이 버튼 옆 목록에서 Poly 모드 로더 <Minecraft 버전> 프로필을 골라 플레이합니다.
- 모드는 런처 폴더의
mods/에 넣습니다.
mods/에 넣은 jar | 처리 방식 |
|---|---|
| Fabric 모드 | 26.1, 26.1.1, 26.1.2, 26.2, 26.3에서 Mixin과 access widener를 포함해 로드합니다. 실행할 수 없는 모드는 빼고 이유를 logs/latest.log에 남깁니다. 호환성을 보세요 |
| NeoForge 모드 | 26.1, 26.1.1, 26.1.2, 26.2, 26.3에서 로드합니다. Poly 모드 로더가 NeoForge를 직접 실행하며, NeoForge 모드를 넣고 처음 시작할 때 NeoForge 파일을 자동으로 받습니다. NeoForge가 거부할 모드는 빼고 이유를 로그에 남깁니다(POLY-COMPAT-217). 호환성을 보세요 |
| Forge 모드 | 26.1, 26.1.1, 26.1.2, 26.2, 26.3에서 로드합니다. Poly 모드 로더가 Forge를 직접 실행하며, Forge 모드를 넣고 처음 시작할 때 Forge 파일을 자동으로 받습니다. Forge가 거부할 모드는 빼고 이유를 로그에 남깁니다(POLY-COMPAT-209). 호환성을 보세요 |
| Quilt 모드 | 26.1, 26.1.1, 26.1.2, 26.2, 26.3에서 Mixin과 access widener를 포함해 로드합니다. fabric.mod.json도 함께 든 모드는 Fabric 모드로 실행합니다(POLY-COMPAT-310). Quilt Standard Libraries(QSL)가 필요한 모드는 QSL의 26.x 판이 없어서 빠집니다(POLY-COMPAT-114와 308). 호환성을 보세요 |
| 로더 섞어 쓰기 | Fabric과 Quilt 모드는 함께 실행됩니다. 또한 Fabric·Quilt 모드를 Forge 모드 또는 NeoForge 모드와 한 mods/ 폴더에 같이 넣을 수 있습니다. 이때 mixin이 그 로더의 패치와 맞지 않는 Fabric·Quilt 모드는 게임 시작 전에 제외되고(POLY-COMPAT-224, 26.2에서 Forge 옆은 Fabric 모드 3개(2026-10-28 측정), NeoForge 옆은 Fabric API 모듈 10개(2026-10-27 측정)) 타이틀 화면에 빠진 수가 표시됩니다. Forge 모드와 NeoForge 모드는 아직 한 mods/ 폴더에 같이 넣을 수 없습니다(POLY-COMPAT-221). Minecraft 26.3에서도 1.2.5부터 로더를 섞어 쓸 수 있습니다(1.2.4에서는 게임이 시작에서 멈췄습니다). Fabric 모드와 Forge 모드 함께 쓰기를 보세요 |
Poly 모드(poly.mod.json이 있는 jar) | 로드합니다 |
타이틀 화면 왼쪽 아래, 게임 버전 위에 로더별로 로드한 모드 수가 게임 언어로 나옵니다(예: Poly 모드: 2개, Fabric 모드: 14개). 모드가 없는 로더는 줄이 없습니다. Forge나 NeoForge 모드가 있으면 그 로더가 표시하는 줄 위에 나옵니다. Poly 모드 로더가 아직 그 로더 옆에서 실행하지 못해 빠진 Fabric·Quilt 모드가 있으면 Poly Mod Loader가 아직 실행하지 못해 빠진 모드: N개 줄이 하나 더 나옵니다. 그 모드의 버그가 아니라 Poly 모드 로더의 한계이니, 모드 제작자가 아니라 Poly 모드 로더 GitHub Issues에 제보해 주세요.
접속하는 서버에도 있는 모드라면 서버와 클라이언트에 같은 버전을 넣어야 합니다.
명령줄로 설치
.jar는 창 없이 명령줄로도 사용할 수 있습니다.
java -jar PolyModLoader-<버전>.jar install # 기본 런처 폴더에 설치
java -jar PolyModLoader-<버전>.jar install --minecraft <Minecraft 버전> # Minecraft 버전 지정(기본값: 가장 새 버전)
java -jar PolyModLoader-<버전>.jar install --dir <런처 폴더> # 다른 폴더(런처 설치 위치를 바꾼 경우)
java -jar PolyModLoader-<버전>.jar install --no-profile # 버전만 설치하고 프로필은 만들지 않음
java -jar PolyModLoader-<버전>.jar install --max-memory 6G --min-memory 1G # 게임 메모리(-Xmx, -Xms)
java -jar PolyModLoader-<버전>.jar uninstall # 제거
java -jar PolyModLoader-<버전>.jar --help
제거
설치 프로그램에서 제거를 누르거나 uninstall을 실행하면 Poly 모드 로더 버전, 프로필, 파일이 삭제됩니다. mods/ 폴더와 월드는 그대로 남습니다.
문제가 생기면
| 증상 | 조치 |
|---|---|
| 런처에 Poly 모드 로더 프로필이 없음 | 런처를 닫고 다시 설치합니다. 런처 폴더를 바꿨다면 설치 프로그램에서 그 폴더를 지정합니다 |
타이틀 화면에 Poly Mod Loader가 아직 실행하지 못해 빠진 모드: N개가 표시됨(POLY-COMPAT-224) | mods/에 넣은 Fabric·Quilt 모드의 mixin이 아직 Forge나 NeoForge의 패치와 맞지 않거나, 제외된 Fabric API 모듈이 필요한 모드입니다. logs/latest.log에서 POLY-COMPAT-224와 POLY-COMPAT-114를 찾으면 어떤 모드가 왜 빠졌는지 볼 수 있습니다. Fabric 모드와 Forge 모드 함께 쓰기를 참고하세요 |
Forge 모드와 NeoForge 모드를 함께 넣었더니 NeoForge 모드가 빠짐(POLY-COMPAT-221) | Forge와 NeoForge는 아직 한 게임에서 함께 실행되지 않습니다. mods/에는 둘 중 한쪽만 넣어 주세요 |
| 게임이 시작하자마자 꺼짐 | 런처 폴더의 logs/latest.log에서 POLY-로 시작하는 오류 코드를 찾아 오류 코드에서 뜻을 확인합니다. 모드가 원인이면 mods/에서 빼고 다시 실행합니다 |
POLY-BOOTSTRAP-006 | 설치 프로그램으로 다시 설치합니다 |
로그에 POLY-COMPAT-133 | Fabric 모드의 Mixin이 게임 클래스에 적용되지 못했습니다. 메시지에 모드 이름이 나옵니다. 그 모드를 빼거나 새 버전을 찾아보세요 |
Poly 모드 로더는 시작할 때 런처 폴더의 .poly/startup-report.json에 보고서를 씁니다. 문제를 알릴 때 이 파일을 함께 보내 주세요.
전용 서버
같은 설치 프로그램으로 서버도 설치합니다. 서버에는 Java 25 이상이 필요합니다.
- 설치 프로그램을 열고 서버를 고른 뒤 서버 폴더를 정합니다.
- Minecraft 버전과 서버 메모리를 고르고 설치를 누릅니다.
설치 프로그램이 그 버전의 Mojang 서버를 받아 확인하고, 옆에 Poly 모드 로더 파일을 둔 뒤 다음 파일을 만듭니다.
run.bat(Windows)과run.sh: 고른 메모리로 서버를 시작합니다.polymodloader-server.jar: 어느 호스팅에서나 시작할 수 있습니다.java -Xmx4G -jar polymodloader-server.jar nogui
처음 시작하면 Minecraft EULA 확인에서 멈춥니다. EULA를 읽고 eula.txt에 eula=true로 적은 뒤 다시 시작하세요. 설치 프로그램이 대신 동의하지 않습니다.
모드는 서버 폴더의 mods/에 넣습니다. 같은 폴더에 다시 설치하면 Poly 모드 로더만 새 버전으로 바뀌고 월드, 설정, 모드는 그대로 남습니다.
화면이 없는 서버에서는 명령줄을 씁니다.
java -jar PolyModLoader-<버전>.jar install-server # 지금 폴더에 설치
java -jar PolyModLoader-<버전>.jar install-server --dir <서버 폴더> --minecraft <Minecraft 버전> --max-memory 4G