본문으로 건너뛰기
버전: Minecraft 26.2

모드 제작 도구

모드를 만들 때 반복되는 일 세 가지는 Gradle이 대신 처리합니다.

도구하는 일명령
initPolyMod압축을 푼 모드 템플릿을 새 모드로 바꿉니다. 모드 ID·패키지·클래스 이름을 모두 바꿉니다압축을 푼 템플릿에서 initPolyMod -PmodId=…
polyResources블록과 아이템마다 손으로 쓰던 JSON(모델, 블록 상태, 아이템 정의, 전리품, 이름, 도구 태그)을 빌드할 때 만들어 줍니다build.gradle.kts에 한 줄
checkPolyResources대문자 파일 이름, 깨진 JSON, 없는 모델·텍스처, 빠뜨린 네임스페이스를 게임을 켜기 전에 찾아냅니다build·check에 포함

새 모드 만들기: initPolyMod​

압축을 푼 모드 템플릿 폴더에서 실행합니다(모드 템플릿 받기). 필수 값은 모드 ID뿐입니다.

.\gradlew.bat initPolyMod -PmodId=ruby_mod "-PmodName=Ruby Mod" "-PmodPackage=io.github.you.ruby"
.\gradlew.bat build
속성기본값예
modId (필수)—ruby_mod (소문자로 시작, 소문자·숫자·_ 2~64자)
modName모드 ID의 각 단어를 대문자로 시작Ruby Mod
modPackagecom.example.<밑줄 뺀 모드 ID>io.github.you.ruby

그 자리에서 다음 항목을 바꿉니다. poly.mod.json(ID·이름·엔트리포인트), 엔트리포인트 클래스(RubyMod)와 패키지 폴더, 리소스 폴더(assets/my_mod/ → assets/ruby_mod/), settings.gradle.kts의 프로젝트 이름, build.gradle.kts의 group과 확인할 로그 줄, IntelliJ 실행 구성입니다. 폴더 이름 자체는 바꾸지 않으므로 필요하면 직접 바꿉니다. 손대지 않은 템플릿에서만 실행되며, 이름을 바꾼 파일이 이미 있는 파일을 덮어쓰게 되면 아무것도 바꾸지 않습니다.

Poly 모드 로더 소스(지금은 비공개)에 접근할 수 있는 기여자는 소스 폴더에서 같은 속성으로 newPolyMod를 실행할 수도 있습니다. 템플릿을 소스 옆의 새 폴더(또는 -PmodDir=<폴더>)에 복사하면서 같은 방식으로 이름을 바꿉니다.

리소스 파일 자동 생성: polyResources​

코드에 등록한 블록과 아이템의 이름을 build.gradle.kts에 적으면, 빌드할 때 바닐라와 같은 형식의 리소스 파일을 만들어 줍니다.

build.gradle.kts
polyResources {
    item("ruby")                                  // textures/item/ruby.png를 쓰는 평면 아이템
    block("ruby_block") { minedWith = "pickaxe" } // textures/block/ruby_block.png를 쓰는 정육면체 블록
    block("ruby_lamp") {
        displayName = "Ruby Lamp"
        texture = "minecraft:block/redstone_lamp_on"
        dropsSelf = false
    }
}
선언만들어지는 파일
item("ruby")assets/<모드>/items/ruby.json, assets/<모드>/models/item/ruby.json, lang/en_us.json의 item.<모드>.ruby
block("ruby_block")blockstates/ruby_block.json, models/block/ruby_block.json(cube_all), items/ruby_block.json, data/<모드>/loot_table/blocks/ruby_block.json(자기 자신을 떨어뜨림), lang/en_us.json의 block.<모드>.ruby_block
minedWith = "pickaxe"data/minecraft/tags/block/mineable/pickaxe.json에 블록 추가("replace": false)
설정뜻기본값
texture텍스처 ID. 네임스페이스를 생략하면 이 모드의 텍스처로 봅니다(block/red → <모드>:block/red)<모드>:item/<이름>, <모드>:block/<이름>
displayName영어 이름이름의 각 단어를 대문자로 시작(ruby_block → Ruby Block)
minedWith (블록)pickaxe, axe, shovel, hoe없음
dropsSelf (블록)부쉈을 때 블록 자신이 떨어지는지 여부true

규칙:

  • 직접 쓴 파일이 우선합니다. src/main/resources에 같은 경로의 파일이 있으면 그 파일은 만들지 않습니다. 계단처럼 모양이 다른 블록은 해당 파일만 직접 쓰면 됩니다.
  • lang/en_us.json과 도구 태그는 합쳐서 만듭니다. 직접 쓴 항목은 값까지 그대로 두고 빠진 이름만 더합니다. 한국어 같은 다른 언어 파일은 직접 써야 합니다.
  • 텍스처 PNG는 만들지 않습니다. 직접 그려서 textures/ 아래에 두세요.
  • 만든 파일은 build/generated/poly-resources/main에 저장되어 jar에 들어가며, 소스 폴더에는 쓰지 않습니다.

게임을 켜기 전에 실수 찾기: checkPolyResources​

build(check)는 jar에 들어갈 리소스 전체(직접 쓴 것과 자동으로 만든 것)를 검사하고, 문제를 모두 모아 보여 준 뒤 실패합니다. 결과는 build/reports/poly/resource-problems.txt에도 남습니다.

2 problems in the mod's resources (src/main/resources and polyResources):
  POLY-RESOURCE-004 assets/ruby_mod/textures/item/Ruby.png: Minecraft only loads resource paths made of lowercase a-z, 0-9, _ . - and /, and skips this file; rename it to assets/ruby_mod/textures/item/ruby.png
  POLY-RESOURCE-007 assets/ruby_mod/models/item/ruby.json: texture "item/ruby" has no namespace, so the game looks for minecraft:item/ruby; write "ruby_mod:item/ruby" for this mod's file
코드찾는 것
POLY-RESOURCE-004게임이 건너뛰는 파일 경로(대문자, 공백 등)
POLY-RESOURCE-005문법이 틀린 JSON(끝의 쉼표, 빠진 따옴표). 줄과 칸 번호를 알려 줍니다
POLY-RESOURCE-006아이템 정의, 블록 상태, 부모 모델이 가리키는 모델 파일이 없음
POLY-RESOURCE-007모델이 가리키는 텍스처 PNG가 없음
POLY-RESOURCE-008번역 파일의 값이 문자열이 아님
POLY-RESOURCE-009polyResources 선언 오류(잘못된 이름·텍스처·도구, 같은 이름을 두 번 선언)

검사 범위는 다음과 같습니다. 모드가 assets/<네임스페이스> 폴더를 가진 네임스페이스 안의 참조만 확인하며, minecraft:와 다른 모드의 파일은 이 프로젝트에 없으므로 확인하지 않습니다. 네임스페이스 없이 쓴 참조(item/ruby)는 minecraft:를 뜻하므로, 같은 경로의 파일이 모드 쪽에 있으면 "네임스페이스를 빠뜨렸다"고 알려 줍니다. 레시피나 전리품 안의 아이템 ID처럼 코드 등록 결과에 달린 참조는 게임 안에서만 확인할 수 있습니다.

다음 단계​

첫 블록 만들기에서 코드 선언과 리소스를 함께 살펴봅니다.

Buy me a coffee