공식 템플릿 다운로드와 IntelliJ 임포트

JDK 25와 IntelliJ IDEA를 설치했다면 이제 실제 모드 프로젝트를 마련할 차례입니다. NeoForge는 빈 프로젝트를 손으로 구성하게 하지 않고, 공식 Mod Generator(모드 제너레이터)로 빌드 스크립트·런 설정·예제 코드가 모두 갖춰진 스타터 템플릿을 만들어 내려받게 합니다. 이 챕터에서는 공식 사이트에서 examplemod 템플릿을 생성·다운로드해 압축을 풀고, IntelliJ에서 연 뒤 JDK 25를 Project SDK·Gradle JVM에 연결하고 Gradle Sync까지 완료하는 전 과정을 다룹니다.

JDK 연결 설정(Project SDK·Gradle JVM)을 이 챕터에서 다루는 이유가 있습니다. IntelliJ의 Gradle 설정은 프로젝트별 설정이라, 프로젝트가 열려 있지 않으면 설정 패널이 비어 있어 손댈 수 없습니다. 그래서 템플릿을 연 직후인 지금이 JDK를 연결할 정확한 시점입니다.

NeoForge 공식 템플릿(MDK)이란

NeoForge로 모드를 만들 때는 MDK(Mod Development Kit) 라 부르는 공식 스타터 템플릿에서 시작합니다. MDK에는 다음이 미리 들어 있습니다.

• Gradle 빌드 스크립트(build.gradle·settings.gradle·gradle.properties)와 Gradle Wrapper
• NeoForge·Minecraft 의존성 선언과 runClient·runServer 등 개발용 런 설정
• 최소한의 예제 코드 3개(ExampleMod·ExampleModClient·Config)

직접 ZIP 링크를 수소문할 필요는 없습니다. NeoForge는 Mod Generator 라는 웹 도구를 제공해, 모드 이름·ID·패키지·Minecraft 버전·Gradle 플러그인을 입력하면 그 설정에 맞춘 MDK를 즉석에서 만들어 줍니다.

1단계: Mod Generator에서 템플릿 생성·다운로드

브라우저에서 NeoForge 공식 Mod Generator로 이동합니다.

https://neoforged.net/mod-generator/

입력란을 이 코스 기준으로 채웁니다.

값을 모두 채웠으면 Download Mod Project 버튼을 클릭합니다. 잠시 후 .zip 파일이 내려받아집니다.

원본 보기

버전 목록에 26.1.2가 없다면 Mod Generator의 Minecraft 버전 드롭다운은 그 시점에 NeoForge가 정식 지원하는 버전만 보여 줍니다. 이 코스가 기준으로 삼는 26.1.2가 보이지 않으면 가장 가까운 26.1.x 버전을 선택해도 됩니다. (gradle.properties의 neo_version은 이후 챕터에서 직접 확인합니다.)

2단계: 압축 해제와 폴더 정리

내려받은 ZIP을 작업용 폴더에 풉니다. 이 코스의 이후 챕터들은 프로젝트 폴더 이름을 examplemod-template-26.1.2로 가정하므로, 압축을 푼 폴더 이름을 동일하게 맞춰 두면 터미널 명령어의 경로가 그대로 들어맞습니다.

examplemod-template-26.1.2/        ← 이 폴더를 IntelliJ로 엽니다
├── build.gradle
├── settings.gradle
├── gradle.properties
├── gradlew / gradlew.bat          # Gradle Wrapper (재현 가능한 빌드)
├── gradle/wrapper/
└── src/
    └── main/
        ├── java/
        │   └── com/example/examplemod/
        │       ├── ExampleMod.java
        │       ├── ExampleModClient.java
        │       └── Config.java
        ├── resources/             # 모드 리소스(아이콘·pack.mcmeta 등)
        └── templates/
            └── META-INF/
                └── neoforge.mods.toml   # 모드 메타데이터 (06장에서 다룸)

이 구조가 앞으로 phase-0부터 phase-5까지 모든 실습의 기반이 됩니다. 파일을 직접 수정하거나 새 파일을 추가하는 것은 각 챕터의 실습 단계에서 진행합니다.

3단계: IntelliJ에서 프로젝트 열기

IntelliJ IDEA를 실행하면 Welcome 화면이 나타납니다. 여기서 Open 버튼을 클릭합니다.

원본 보기

파일 탐색기 다이얼로그가 열리면 2단계에서 압축을 푼 examplemod-template-26.1.2 폴더로 이동합니다. 폴더 안으로 들어가지 말고 폴더 자체를 선택한 상태에서 OK를 클릭합니다.

이미 다른 프로젝트가 열려 있다면 File > Open... 메뉴를 사용합니다. 경로는 동일합니다.

4단계: Trust Project 확인

처음 여는 프로젝트라면 IntelliJ가 신뢰 여부를 묻는 다이얼로그를 표시합니다.

원본 보기

Trust Project를 클릭합니다. 이 단계를 건너뛰면 Gradle 스크립트 실행이 차단되어 Sync가 시작되지 않습니다.

Trust Project vs Trust Projects in...: 단일 프로젝트만 신뢰하려면 Trust Project를, 해당 디렉토리 하위 모든 프로젝트를 신뢰하려면 Trust Projects in...을 선택합니다. 개인 개발 환경에서는 어느 쪽이든 무방합니다.

5단계: Project SDK 설정 (JDK 25)

Trust Project를 누르면 IntelliJ가 곧바로 Gradle Sync를 시도합니다. 그런데 IntelliJ에 JDK 25가 등록되어 있지 않으면 Sync가 toolchain 오류로 실패합니다. 그러니 의존성 다운로드가 본격화되기 전에 JDK부터 연결합니다.

IntelliJ는 JDK를 직접 찾지 않습니다. 프로젝트가 어떤 JDK를 사용할지 명시적으로 지정해야 합니다.

1. 메뉴에서 File > Project Structure (Ctrl+Alt+Shift+S) 열기
2. 왼쪽 패널에서 SDKs 선택
3. 목록에 JDK 25가 이미 보이면 그대로 사용합니다. 없다면 + 버튼 > Add JDK... 선택
4. JDK 25 설치 경로 지정:

   C:\Program Files\Eclipse Adoptium\jdk-25.0.x.x-hotspot
   

5. 왼쪽 Project 탭에서 SDK가 JDK 25로 선택돼 있는지 확인 후 OK 클릭

경로를 모르겠다면 PowerShell에서 $env:JAVA_HOME을 실행하면 확인할 수 있습니다. 01장에서 설정한 경로입니다.

원본 보기

6단계: Gradle JVM 설정

Project SDK를 지정했어도 Gradle이 사용하는 JVM은 별도 설정입니다. 프로젝트가 열려 있는 지금은 설정 패널이 정상적으로 채워집니다.

1. Settings (Ctrl+Alt+S) 열기
2. Build, Execution, Deployment > Build Tools > Gradle 이동
3. Gradle JVM 드롭다운에서 Project SDK (JDK 25) 또는 방금 등록한 JDK 25 선택
4. Apply > OK 클릭

이 설정이 빠지면 Gradle이 시스템 기본 JVM을 사용해 버전 불일치 문제가 생길 수 있습니다.

7단계: Gradle Sync 진행

JDK 연결이 끝나면 Gradle Sync를 실행합니다. Trust Project 직후 이미 자동으로 시작됐다면, Gradle 패널에서 🔄 Reload All Gradle Projects를 눌러 새 JDK 설정으로 다시 동기화합니다. 화면 우하단에 진행 표시줄이 나타납니다.

원본 보기

첫 실행 시 보통 5~15분이 소요됩니다. Gradle이 다음 항목들을 다운로드·디컴파일하기 때문입니다.

• NeoForge 26.1.2.64-beta 라이브러리
• Minecraft 26.1.2 에셋 및 소스
• 빌드 도구 의존성 (ModDevGradle, Mixin 등)

인터넷 속도와 하드웨어 성능에 따라 더 걸릴 수 있으며, 처음 한 번은 최대 1시간까지 걸리기도 합니다. 진행 표시줄이 사라질 때까지 기다립니다.

8단계: 의존성 다운로드 확인

Sync가 완료되면 IntelliJ 하단의 Build 탭 또는 Gradle 패널에서 결과를 확인할 수 있습니다. 오류 없이 완료되면 다음 단계로 넘어갑니다.

Gradle 패널은 View > Tool Windows > Gradle로 열 수 있습니다. 패널에 프로젝트 태스크 목록이 보이면 Sync가 성공한 것입니다.

9단계: 프로젝트 트리 확인

Sync가 끝나면 왼쪽 Project 패널에 프로젝트 구조가 펼쳐집니다.

src/main/java/com/example/examplemod/ 경로 아래에 다음 세 파일이 보여야 합니다.

• ExampleMod.java
• ExampleModClient.java
• Config.java

이 세 파일이 보이면 프로젝트 임포트가 정상적으로 완료된 것입니다.

기본 파일 3개 소개

ExampleMod.java

모드의 진입점입니다. @Mod 어노테이션으로 모드 ID를 선언하고, 초기화 이벤트를 등록합니다. 모든 모드는 이 파일에서 시작합니다.

@Mod(ExampleMod.MODID)
public class ExampleMod {
    public static final String MODID = "examplemod";
    // ...
}

ExampleModClient.java

클라이언트 전용 초기화 코드를 담습니다. 렌더링, GUI, 파티클 등 서버에서 실행할 필요 없는 코드는 여기에 분리합니다.

Config.java

Forge Config API를 사용한 설정 파일 예제입니다. 서버/클라이언트/공통 설정을 각각 어떻게 정의하는지 보여줍니다.

트러블슈팅

⚠️ No matching toolchain found: {languageVersion=25} 오류

JDK 25를 시스템에 설치했더라도 IntelliJ의 Project SDK·Gradle JVM이 JDK 25로 연결되지 않으면 이 오류로 Sync가 실패합니다. 이 템플릿의 build.gradle이 java.toolchain.languageVersion = JavaLanguageVersion.of(25)로 Java 25 툴체인을 요구하기 때문입니다.

해결: 위 5단계(Project SDK)·**6단계(Gradle JVM)**가 모두 JDK 25를 가리키는지 다시 확인하세요.

🐞 Gradle JVM 설정 화면이 비어 있음 (IntelliJ 2025.1+ 표시 버그)

프로젝트가 열려 있고 Gradle 툴 윈도(코끼리 아이콘)에 Tasks·Dependencies까지 보이는데도 Settings > Build, Execution, Deployment > Build Tools > Gradle 페이지가 Select configuration element in the tree to edit its settings만 표시한다면, IntelliJ 2025.1 이상의 알려진 UI 버그(JetBrains 이슈 IDEA-381808)입니다. Gradle 자체는 정상 동작하며 설정 화면만 렌더되지 않는 표시 문제이므로 대개 그대로 진행해도 됩니다.

이 템플릿은 settings.gradle의 foojay-resolver-convention 덕분에 Gradle을 띄우는 JVM과 무관하게 컴파일용 Java 25 toolchain을 자동 확보합니다. Gradle 툴 윈도에 태스크가 보이면 이미 Sync가 끝난 것이며, 다음으로 실제 JVM 버전을 확인할 수 있습니다.

.\gradlew.bat --version

출력의 JVM: 줄이 25.x이면 그대로 다음 챕터의 runClient로 진행해도 됩니다. Gradle JVM을 굳이 JDK 25로 고정하려면 아래 우회책을 씁니다.

• 코끼리(Gradle) 툴 윈도 상단 툴바의 ⚙ (Gradle Settings) 아이콘으로 같은 페이지를 다시 열어 봅니다. 가끔 정상 렌더됩니다.
• 그래도 비어 있으면 .idea/gradle.xml 직접 편집: IntelliJ 프로젝트 창을 먼저 닫고(열린 채 편집하면 IDE가 덮어씀), 프로젝트 루트의 .idea/gradle.xml에서 <GradleProjectSettings> 안에 <option name="gradleJvm" value="#JAVA_HOME" />를 추가하거나 값을 바꾼 뒤, 프로젝트를 다시 열고 🔄 Reload All Gradle Projects를 누릅니다. #JAVA_HOME은 01장에서 JDK 25로 지정한 환경변수를 그대로 씁니다. (특정 SDK 이름을 쓰려면 Project Structure > SDKs에 등록된 이름, 예: temurin-25를 넣습니다.)
• 근본 해결은 Help > Check for Updates로 패치를 적용하거나, 한 단계 낮은 IntelliJ 버전(예: 2024.3)으로 내리는 것입니다.

💡 Gradle Sync 실패 시 (일반)

1. File > Invalidate Caches... 클릭
2. Invalidate and Restart 선택
3. IntelliJ 재시작 후 Gradle 패널에서 🔄 Refresh 클릭

원본 보기

이 방법으로도 해결되지 않으면 터미널에서 직접 실행해 오류 메시지를 확인합니다.

cd examplemod-template-26.1.2
./gradlew --refresh-dependencies

검증 체크리스트

• Mod Generator에서 Example Mod / examplemod / ModDevGradle 설정으로 템플릿 다운로드
• ZIP 압축을 풀고 폴더명을 examplemod-template-26.1.2로 정리
• IntelliJ에서 examplemod-template-26.1.2 폴더가 열림
• Trust Project 완료
• File > Project Structure > SDKs에 JDK 25가 등록됨
• Settings > Build Tools > Gradle > Gradle JVM이 JDK 25로 설정됨
• Gradle Sync 오류 없이 완료
• Project 패널에 ExampleMod.java, ExampleModClient.java, Config.java 보임
• Gradle 패널에 프로젝트 태스크 목록 표시됨

템플릿을 내려받아 열고, JDK가 연결되고, 세 파일이 모두 보이며 Gradle 패널에 태스크가 나타나면 다음 챕터로 넘어갈 준비가 된 것입니다.