마스터 트랙 #2: 차원 모드 프로젝트 셋업

마스터 트랙 #2 — Magic Realm 차원

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

phase-6의 두 번째 마스터 트랙은 커스텀 차원(Custom Dimension) 트랙입니다. 완성 목표는 다음과 같습니다.

• 🌌 Magic Realm: 고유 바이옴 · 스카이라이트 · 야간 고정(fixed_time: 6000)
• 🔥 마법 포탈 블록: 충돌 없음 · 폭발 저항 최대 · 자연 낙하 없음
• 🪄 마법 점화 아이템: 우클릭 시 포탈 블록 배치 (내구도 64)
• 📐 포탈 프레임: 3×4 구조 자동 감지 → 차원 입장/퇴장

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

프로젝트 구조 확인

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

examplemod-master-projects/
└── dimension/
    ├── build.gradle              ← NeoForge ModDev 플러그인 설정
    ├── gradle.properties         ← mod_id=master_dimension, mc/neo 버전
    ├── settings.gradle
    ├── gradlew / gradlew.bat
    └── src/
        └── main/
            ├── java/com/example/master/dimension/
            │   ├── MasterDimensionMod.java   ← 메인 진입점 (이번 챕터)
            │   ├── block/
            │   │   └── MagicPortalBlock.java  ← 포탈 블록 (02-portal-block 챕터)
            │   └── item/
            │       └── MagicIgniter.java      ← 점화 아이템 (02-portal-block 챕터)
            ├── resources/
            │   ├── pack.mcmeta
            │   └── data/master_dimension/
            │       ├── dimension_type/magic_realm.json  ← 차원 타입 JSON
            │       ├── dimension/magic_realm.json       ← 차원 JSON
            │       └── worldgen/biome/magic_realm.json  ← 바이옴 JSON
            └── templates/META-INF/
                └── neoforge.mods.toml

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

gradle.properties 확인

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

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

MasterDimensionMod.java

이번 챕터에서 확인하는 메인 클래스입니다. 포탈 블록과 점화 아이템 레지스터를 선언하고, 다음 챕터들에서 차원 JSON을 완성합니다.

// examplemod-master-projects/dimension/src/main/java/com/example/master/dimension/MasterDimensionMod.java
package com.example.master.dimension;
 
import com.example.master.dimension.block.MagicPortalBlock;
import com.example.master.dimension.item.MagicIgniter;
import com.mojang.logging.LogUtils;
import net.minecraft.world.item.Item;
import net.minecraft.world.level.block.Block;
import net.minecraft.world.level.block.state.BlockBehaviour;
import net.neoforged.bus.api.IEventBus;
import net.neoforged.fml.ModContainer;
import net.neoforged.fml.common.Mod;
import net.neoforged.neoforge.registries.DeferredRegister;
import org.slf4j.Logger;
 
import java.util.function.Supplier;
 
@Mod(MasterDimensionMod.MOD_ID)
public class MasterDimensionMod {
    public static final String MOD_ID = "master_dimension";
    public static final Logger LOGGER = LogUtils.getLogger();
 
    // ─── 블록 레지스터 ─────────────────────────────────────────────────────
    public static final DeferredRegister.Blocks BLOCKS =
            DeferredRegister.createBlocks(MOD_ID);
 
    // ─── 아이템 레지스터 ───────────────────────────────────────────────────
    public static final DeferredRegister.Items ITEMS =
            DeferredRegister.createItems(MOD_ID);
 
    // ─── 포탈 블록 ─────────────────────────────────────────────────────────
    /**
     * 마법 포탈 내부 블록.
     * 충돌 없음 · 폭발 저항 최대 · 자연 낙하 없음.
     * 점화 → 03-portal-shape, 엔티티 이동 → 04-dimension-entry 에서 완성.
     */
    public static final Supplier<Block> MAGIC_PORTAL = BLOCKS.registerBlock("magic_portal",
            MagicPortalBlock::new);
 
    // ─── 점화 아이템 ───────────────────────────────────────────────────────
    /**
     * 마법 점화 아이템.
     * 스택 1 · 내구도 64. 우클릭 시 위쪽 공기 슬롯에 포탈 블록 배치.
     */
    public static final Supplier<Item> MAGIC_IGNITER = ITEMS.registerItem("magic_igniter",
            props -> new MagicIgniter(props
                    .stacksTo(1)
                    .durability(64)));
 
    public MasterDimensionMod(IEventBus modEventBus, ModContainer container) {
        LOGGER.info("Master Dimension Mod 로드");
 
        BLOCKS.register(modEventBus);
        ITEMS.register(modEventBus);
        // dimension JSON 등 추가는 후속 챕터에서
    }
}

gradlew tasks 검증

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

cd examplemod-master-projects/dimension
.\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 플러그인이 정상 설정된 것입니다.

Mods 메뉴 표시 확인

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

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

다음 챕터 예고

다음 챕터(01-dimension-register)에서는 Magic Realm 차원 JSON 파일 구조를 분석하고 dimension_type, dimension, worldgen/biome 세 파일의 역할을 이해합니다.