runClient 첫 실행과 렌더 백엔드 확인
IntelliJ Gradle 패널 또는 CLI에서 neoforge runClient를 실행하여 Minecraft 26.1.2를 처음 구동하고, F3 디버그 화면에서 렌더 백엔드(OpenGL 3.3.0 또는 환경에 따라 Vulkan)를 확인합니다.
runClient 첫 실행과 렌더 백엔드 확인
IntelliJ에서 Gradle Sync가 완료되었다면 이제 실제로 Minecraft를 실행해 볼 차례입니다. runClient Gradle 태스크는 NeoForge가 제공하는 개발용 클라이언트 런처로, 여러분이 작성한 모드 코드를 적재한 상태로 게임을 시작합니다. 이 챕터에서는 첫 실행 방법과 F3 디버그 화면에서 렌더 백엔드 확인까지 전 과정을 다룹니다.
1단계: Gradle 패널에서 runClient 실행 (GUI)
IntelliJ 우측 사이드바에서 Gradle 패널을 엽니다 (단축키: Ctrl+Alt+Shift+G 또는 우측 수직 탭 클릭).
패널 트리에서 다음 경로를 펼칩니다.
examplemod → Tasks → neoforge(mod development) → runClient
runClient를 더블클릭하면 하단 Run 탭이 열리고 Gradle이 클라이언트를 빌드한 뒤 Minecraft를 실행합니다.
혹은, 상단에 실행 버튼옆에 있는 드롭다운을 통해서 Client를 선택후 실행 버튼을 눌러서 실행할 수 있습니다.
팁: 태스크를 오른쪽 클릭 → Run 또는 Debug를 선택할 수도 있습니다. Debug 모드에서는 IntelliJ 디버거가 게임 프로세스에 연결됩니다.
2단계: CLI로 runClient 실행 (대안)
IntelliJ GUI 대신 PowerShell / 터미널에서 직접 실행할 수도 있습니다.
Intellij의 터미널을 통해서도 실행 가능합니다.
# 학습 코스 레포 루트에서
cd examplemod-template-26.1.2
.\gradlew.bat runClient실행하면 Gradle이 빌드 정보를 출력한 뒤 Minecraft 클라이언트를 시작합니다. 아래는 실행 직후 콘솔 화면입니다.
Windows에서 경로 주의: PowerShell에서는
.\gradlew.bat(백슬래시 +.bat)을 사용해야 합니다. Git Bash라면./gradlew runClient를 사용합니다.
3단계: 첫 실행 — 에셋 다운로드 대기
첫 실행은 5~15분 소요됩니다
NeoForge/Minecraft 에셋(텍스처·사운드·라이브러리)이 다운로드되지 않았다면 Gradle이 자동으로 받습니다. 데이터 양이 수 GB에 달할 수 있으므로 인터넷 속도에 따라 시간이 더 걸릴 수 있습니다.
다운로드 중에는 콘솔에 다음과 같은 로그가 출력됩니다:
> Task :downloadAssets
Downloading assets...
진행 표시줄이 100%가 될 때까지 기다립니다. 중간에 콘솔을 닫거나 Ctrl+C를 누르면 다운로드가 중단됩니다.
4단계: Minecraft 타이틀 화면 확인
에셋 다운로드가 완료되면 Minecraft 창이 열립니다. 잠시 후 타이틀 화면이 나타나면 정상입니다.
타이틀 화면에서 다음을 확인합니다.
| 확인 항목 | 예상 값 |
|---|---|
| 버전 표시 | 1.21.4-NeoForge-21.4.X 또는 Minecraft 26.1.2 |
| 모드 카운트 | 화면 하단 X mods loaded (ExampleMod 포함) |
| 렌더링 오류 | 없음 (검은 화면·GL error 없음) |
모드 카운트:
1 mod loaded는 ExampleMod만 로드된 것입니다. NeoForge 자체와 Minecraft 기반 모드는 별도로 카운트됩니다.
5단계: F3 디버그 화면에서 렌더 백엔드 확인
게임 안에서 F3 키를 누르면 디버그 오버레이가 나타납니다.
화면 우측 상단 정보 블록에서 OpenGL 버전 정보를 찾습니다.
본 코스 검증 환경 (NVIDIA GeForce RTX 3070, 드라이버 595.79)에서 실제 표시되는 값:
OpenGL 3.3.0 NVIDIA 595.79
NeoForge 26.x의 렌더 백엔드는 OpenGL 기반이며, Vulkan은 GPU/드라이버/JVM 설정에 따라 선택적으로 활성화할 수 있습니다. F3에 실제로 표시되는 OpenGL 버전은 GPU·드라이버·실행 환경에 따라 달라지므로, 아래 검증 환경 값은 참고용입니다.
F3의 OpenGL 표시값은 환경마다 다릅니다
F3 우측 상단의 OpenGL 줄은 GPU·드라이버·실행 환경에 따라 다르게 표시됩니다. 아래는 참고 값입니다.
- NVIDIA GeForce RTX 3070 (드라이버 595.79) →
OpenGL 3.3.0 NVIDIA 595.79← 이 코스 검증 환경 - GPU·드라이버·JVM 설정에 따라 Vulkan 렌더러가 활성화될 수도 있습니다.
어느 백엔드를 사용하든 NeoForge 추상화 API(PoseStack, MultiBufferSource)를 사용하면 동일하게 동작합니다. 직접 GL 호출(GL11.*)은 백엔드 교체 시 미정의 동작을 유발하므로 사용하지 마세요.
6단계: 게임 종료 (필수)
실습이 끝나면 반드시 게임을 정상 종료합니다.
GUI로 종료
- ESC 키를 눌러 메뉴 열기
- Quit Game 클릭
CLI로 강제 종료 (비상용)
게임이 응답하지 않거나 창이 없어진 경우:
# Java 프로세스 강제 종료
taskkill /IM javaw.exe /F왜 종료가 중요한가? Gradle 데몬과 게임 프로세스가 함께 실행 중인 상태에서 Gradle 빌드를 재실행하면 포트 충돌이나 파일 잠금 문제가 발생할 수 있습니다. 개발 중에는 게임을 실행한 뒤 반드시 종료하는 습관을 들이세요.
정리
이 챕터에서 달성한 것:
- ✅
runClient태스크를 GUI(IntelliJ Gradle 패널) 또는 CLI로 실행 - ✅ 첫 실행 시 에셋 자동 다운로드 과정 이해
- ✅ Minecraft 타이틀 화면 정상 진입 확인
- ✅ F3 디버그 오버레이로 렌더 백엔드 확인 (검증 환경 OpenGL 3.3.0)
- ✅ 게임 정상 종료
다음 챕터에서는 프로젝트 구조를 분석하고 ExampleMod의 진입점 코드를 살펴봅니다.
공식 템플릿 다운로드와 IntelliJ 임포트
NeoForge 공식 Mod Generator에서 examplemod 스타터 템플릿을 내려받아 압축을 풀고, IntelliJ IDEA에서 연 뒤 JDK 25 SDK·Gradle JVM을 연결하고 Gradle Sync를 완료하는 방법을 안내합니다.
템플릿 디렉토리 구조와 핵심 파일
examplemod-template-26.1.2의 디렉토리 구조를 파악하고 build.gradle, settings.gradle, ExampleMod.java, neoforge.mods.toml 등 핵심 파일의 역할을 이해합니다.