모드 마무리 + 빌드 JAR

이 챕터의 목표

⚠️ datagen 의존 챕터 이 챕터의 일부 코드는 runData Gradle 태스크로 JSON 리소스를 생성해야 동작합니다. 현재 예제 모드 프로젝트에 datagen 인프라가 포함되지 않아 별도 PR(#datagen-infrastructure)로 검증 예정입니다.

지금까지 만든 Master Tools 모드를 배포 가능한 JAR 파일로 빌드합니다. 빌드 전에 README.md로 프로젝트를 문서화하고, gradlew build로 산출물을 생성하며, JAR의 무결성을 지키는 방법을 배웁니다.

1단계 — README.md 작성

모드 프로젝트에 README.md가 있으면 기여자·학습자 모두가 빠르게 온보딩할 수 있습니다.

examplemod-master-projects/tools/README.md

# Master Tools — NeoForge 26 마스터 트랙 #1
 
Ruby/Sapphire 보석 아이템과 4종 도구를 담은 NeoForge 26 모드.
 
## 기능
- Ruby, Sapphire 두 가지 보석 아이템 (DataComponent purity 포함)
- Ruby Tier 커스텀 (내구도 1024, 채굴 속도 8.0, 공격력 +3.5)
- Ruby Pickaxe / Sword / Axe / Shovel 4종 도구
- 자체 크리에이티브 탭 + Vanilla INGREDIENTS 탭 추가
- 조합 레시피 (보석 → 도구) + 제련 레시피 (광물 → 보석)
 
## 빌드 방법
\`\`\`powershell
cd examplemod-master-projects\tools
.\gradlew.bat build
\`\`\`
 
빌드 산출물: `build/libs/master_tools-1.0.0.jar`

README에 포함해야 할 최소 항목

• 모드 기능 요약
• 빌드 방법 (명령어 포함)
• 사용 방법 (설치 경로)
• 요구사항 (Minecraft/NeoForge 버전)

2단계 — 모드 메타데이터 확인

빌드 전에 gradle.properties의 모드 정보를 최종 확인합니다.

examplemod-master-projects/tools/gradle.properties

# Minecraft / NeoForge 버전
minecraft_version=26.1.2
neo_version=26.1.2.64-beta
 
# 모드 ID + 이름 + 버전
mod_id=master_tools
mod_name=Master Tools
mod_license=MIT
mod_version=1.0.0
mod_group_id=com.example.master.tools

버전 규칙: major.minor.patch 형식 권장. 콘텐츠 추가는 minor 증가, 버그 수정은 patch 증가. NeoForge 버전 업그레이드 시 major 증가 검토.

3단계 — JAR 빌드

cd "C:\Users\duarl\Documents\OpenCode\NeoForge-26-Docs\examplemod-master-projects\tools"
.\gradlew.bat build

빌드가 완료되면 다음 명령으로 산출물을 확인합니다.

# 빌드 산출물 확인
Get-ChildItem build\libs\
 
# 예상 출력:
# master_tools-1.0.0.jar      (배포 JAR)
# master_tools-1.0.0-sources.jar  (소스 JAR, 선택)

⏱️ 빌드 소요 시간

• 첫 빌드: 5~15분 (Minecraft 서버 + NeoForge 의존성 다운로드 포함)
• 이후 빌드: 1~3분 (Gradle 빌드 캐시 활성화 시)

빌드 중 콘솔에 BUILD SUCCESSFUL 메시지가 나타나면 정상입니다.

4단계 — 빌드 결과 검증

BUILD SUCCESSFUL 확인

> Task :compileJava
> Task :processResources
> Task :generateModMetadata
> Task :classes
> Task :jar

BUILD SUCCESSFUL in 2m 34s
8 actionable tasks: 8 executed

JAR 파일 크기 확인

빌드 결과 JAR의 크기가 너무 작으면(수 KB 이하) 리소스가 포함되지 않았을 가능성이 있습니다.

(Get-Item "build\libs\master_tools-1.0.0.jar").Length / 1KB
# 예상: 수십 KB ~ 수백 KB

인게임 검증

1. build/libs/master_tools-1.0.0.jar 를 Minecraft mods/ 폴더에 복사
2. NeoForge 26.1.2.64-beta 설치된 Minecraft 26.1.2 실행
3. 타이틀 화면 → Mods 버튼 클릭
4. "Master Tools" 항목 확인 → modId: master_tools | version: 1.0.0 표시

⚠️ 안티패턴: JAR 직접 수정

⚠️ JAR 직접 수정 → ZIP 무결성 손상

# ❌ 절대 금지
# build/libs/ 안의 JAR을 직접 수정하거나
# 압축 해제 → 파일 편집 → 재압축하면:

• ZIP 포맷 무결성이 깨짐 → Java ZipException: invalid entry compressed size
• NeoForge가 JAR을 검증할 때 실패 → 모드 로드 불가
• FMLLoader: Failed to load mod [master_tools] 에러 발생

항상 소스 코드를 수정하고 gradlew build로 재생성하세요.

배포 전 최종 체크리스트

빌드한 JAR을 배포하거나 제출 전에 아래 항목을 확인합니다.

Gradle 주요 태스크 정리

gradlew clean build — 캐시 문제 발생 시 사용. 처음부터 다시 빌드합니다.

마스터 트랙 1 완성!

이 챕터를 마치면 Master Tools 모드 마스터 트랙 1이 완성됩니다.

완성된 모드의 기능:

• ✅ Ruby / Sapphire 보석 아이템 (DataComponent purity 포함)
• ✅ Ruby Tier 커스텀 (내구도 1024, 채굴 속도 8.0, 공격력 +3.5)
• ✅ Ruby Pickaxe / Sword / Axe / Shovel 4종 도구
• ✅ 크리에이티브 탭 + Vanilla INGREDIENTS 탭 등록
• ✅ 조합 레시피 + 제련 레시피
• ✅ 배포 가능한 JAR 빌드

다음 마스터 트랙에서는 **커스텀 차원(Custom Dimension)**을 구현하며 더 심화된 NeoForge API를 탐구합니다.