마스터 트랙 #3: 기계 모드 프로젝트 셋업

마스터 트랙 #3 — Crusher 기계

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

phase-6의 세 번째 마스터 트랙은 기계 블록(Machine Block) 트랙입니다. 완성 목표는 다음과 같습니다.

• ⚙️ Crusher 기계 블록: FACING BlockState + EntityBlock 구현
• 📦 CrusherBlockEntity: 아이템 슬롯 · 처리 진행 상태 · 에너지 추적
• 🖥️ GUI (CrusherMenu + CrusherScreen): 서버-클라이언트 동기화
• 📋 레시피 시스템: CrushingRecipe JSON 정의
• 🌐 네트워킹: 커스텀 패킷 + Capability(ItemHandler) 연동

프로젝트 소스는 examplemod-master-projects/machine/ 에 위치합니다.

프로젝트 구조 확인

마스터 트랙 프로젝트는 학습 코스 템플릿과 완전히 분리된 독립 Gradle 프로젝트입니다.

examplemod-master-projects/
└── machine/
    ├── build.gradle              ← NeoForge ModDev 플러그인 설정
    ├── gradle.properties         ← mod_id=master_machine, mc/neo 버전
    ├── settings.gradle
    ├── gradlew / gradlew.bat
    └── src/
        └── main/
            ├── java/com/example/master/machine/
            │   ├── MasterMachineMod.java          ← 메인 진입점 (이번 챕터)
            │   ├── block/
            │   │   ├── CrusherBlock.java          ← 기계 블록 (01-crusher-block 챕터)
            │   │   └── CrusherBlockEntity.java    ← BlockEntity (02-block-entity 챕터)
            │   ├── menu/
            │   │   └── CrusherMenu.java           ← GUI 메뉴 (03-gui 챕터)
            │   ├── screen/
            │   │   └── CrusherScreen.java         ← 클라이언트 화면 (03-gui 챕터)
            │   ├── recipe/
            │   │   └── CrushingRecipe.java        ← 레시피 타입 (04-recipe 챕터)
            │   └── network/
            │       └── CrusherSyncPacket.java     ← 동기화 패킷 (05-networking 챕터)
            ├── resources/
            │   ├── pack.mcmeta
            │   └── data/master_machine/
            │       └── recipes/                   ← 레시피 JSON 파일들
            └── templates/META-INF/
                └── neoforge.mods.toml

examplemod-template-26.1.2/ 와는 별개의 Gradle 프로젝트입니다. 두 프로젝트를 같은 mods/ 디렉토리에 넣을 때 mod_id 가 겹치면 충돌이 발생하므로 주의하세요.

gradle.properties 확인

# examplemod-master-projects/machine/gradle.properties
minecraft_version=26.1.2
minecraft_version_range=[26.1.2]
neo_version=26.1.2.64-beta
 
mod_id=master_machine
mod_name=Master Machine
mod_license=All Rights Reserved
mod_version=1.0.0
mod_group_id=com.example.master.machine

mod_id=master_machine 가 이 모드의 고유 식별자입니다. neoforge.mods.toml 의 modId 와 동일해야 합니다.

MasterMachineMod.java

이번 챕터에서 작성하는 메인 클래스입니다. 다음 챕터들에서 블록·아이템·BlockEntity 타입·메뉴·레시피 타입 레지스터를 순차적으로 추가합니다.

// examplemod-master-projects/machine/src/main/java/com/example/master/machine/MasterMachineMod.java
package com.example.master.machine;
 
import com.mojang.logging.LogUtils;
import net.neoforged.bus.api.IEventBus;
import net.neoforged.fml.ModContainer;
import net.neoforged.fml.common.Mod;
import org.slf4j.Logger;
 
@Mod(MasterMachineMod.MOD_ID)
public class MasterMachineMod {
    public static final String MOD_ID = "master_machine";
    public static final Logger LOGGER = LogUtils.getLogger();
 
    public MasterMachineMod(IEventBus modEventBus, ModContainer container) {
        LOGGER.info("Master Machine Mod 로드");
        // 다음 챕터들에서 BLOCKS, ITEMS, BLOCK_ENTITY_TYPES, MENU_TYPES, RECIPE_TYPES 추가
    }
}

gradlew tasks 검증

터미널에서 machine 프로젝트로 이동해 태스크 목록을 확인합니다.

cd examplemod-master-projects/machine
.\gradlew tasks

기대 출력 (일부):

Mod development tasks
---------------------
createLaunchScripts - Creates batch files/shell scripts to launch the game
downloadAssets - Downloads the Minecraft assets
runClient - Runs the client Minecraft run configuration.
runData - Runs the data Minecraft run configuration.
runServer - Runs the server Minecraft run configuration.

runClient 태스크가 보이면 NeoForge ModDev 플러그인이 정상 설정된 것입니다.

⚠️ settings.gradle 누락 settings.gradle 없거나 rootProject.name 미설정: → gradlew tasks 즉시 에러 ("settings file does not exist") ✅ T5 스켈레톤에 이미 설정됨 — 변경 금지

Mods 메뉴 표시 확인

runClient 로 게임을 실행한 뒤 Mods 메뉴에서 Master Machine 이 표시되는지 확인합니다.

⚠️ neoforge.mods.toml displayName 누락 displayName 미지정 시 Mods 메뉴에 raw modId(master_machine)로 표시됩니다. ✅ neoforge.mods.toml 에 이미 displayName = "${mod_name}" 이 명시되어 있으며, gradle.properties 의 mod_name=Master Machine 값이 자동으로 치환됩니다.

다음 챕터 예고

다음 챕터(01-crusher-block)에서는 FACING BlockState + EntityBlock을 구현하는 CrusherBlock.java 를 작성하고, DeferredRegister 로 블록과 아이템을 등록합니다.