보석 아이템 디자인 — Ruby & Sapphire
DeferredRegister로 Ruby, Sapphire 보석 아이템을 등록하고 DataComponentType으로 순도(purity) 컴포넌트를 설계합니다. 마스터 트랙 도구 제작의 첫 단계입니다.
보석 아이템 디자인 — Ruby & Sapphire
이 챕터에서는 마스터 트랙 도구 모드의 핵심 재료인 루비(Ruby)와 사파이어(Sapphire) 보석 아이템을 등록합니다. 단순 아이템 등록을 넘어, NeoForge 26.1의 DataComponentType으로 보석의 순도(purity) 값을 저장하는 커스텀 컴포넌트를 설계합니다.
1. ITEMS DeferredRegister 선언
phase-2에서 배운 DeferredRegister.createItems() 패턴을 그대로 사용합니다. 마스터 트랙에서는 Rarity를 설정하여 희귀 아이템임을 표시합니다.
// examplemod-master-projects/tools/src/main/java/com/example/master/tools/MasterToolsMod.java
public static final DeferredRegister.Items ITEMS =
DeferredRegister.createItems(MOD_ID);
/** 루비 — 순도(purity) DataComponent를 가지는 보석 아이템 */
public static final Supplier<Item> RUBY = ITEMS.registerItem("ruby",
props -> new Item(props
.stacksTo(64)
.rarity(Rarity.RARE)));
public static final Supplier<Item> SAPPHIRE = ITEMS.registerItem("sapphire",
props -> new Item(props
.stacksTo(64)
.rarity(Rarity.RARE)));rarity(Rarity.RARE) — 아이템 이름이 파란색으로 표시됩니다.
COMMON(하양) →UNCOMMON(노랑) →RARE(파랑) →EPIC(보라) 순으로 희귀도가 높아집니다.
2. DataComponentType — 순도(purity) 컴포넌트
NeoForge 26.1의 DataComponentType은 ItemStack에 임의의 데이터를 첨부하는 현대적인 방식입니다. NBT를 직접 다루던 구식 방법 대신 Codec으로 자동 직렬화·역직렬화됩니다.
// examplemod-master-projects/tools/src/main/java/com/example/master/tools/MasterToolsMod.java
public static final DeferredRegister.DataComponents COMPONENTS =
DeferredRegister.createDataComponents(MOD_ID);
/**
* 보석 순도 (0 ~ 100).
* 순도가 높을수록 다음 챕터에서 도구 내구도 보너스가 증가합니다.
*/
public static final Supplier<DataComponentType<Integer>> PURITY =
COMPONENTS.registerComponentType(
"purity",
builder -> builder
.persistent(Codec.INT)
.networkSynchronized(ByteBufCodecs.INT));빌더 옵션 설명:
| 옵션 | 역할 |
|---|---|
persistent(Codec.INT) | NBT/JSON으로 영구 저장 — 아이템을 저장해도 값 유지 |
networkSynchronized(ByteBufCodecs.INT) | 서버 → 클라이언트 패킷으로 동기화 |
3. 생성자에서 이벤트 버스 등록
ITEMS와 COMPONENTS 모두 mod 이벤트 버스에 등록해야 합니다.
public MasterToolsMod(IEventBus modEventBus, ModContainer container) {
ITEMS.register(modEventBus);
COMPONENTS.register(modEventBus);
}ITEMS와 COMPONENTS 중 하나라도 등록 누락 시 해당 아이템/컴포넌트가 인게임에서 인식되지 않습니다.
4. 리소스 파일 (텍스처·모델·언어)
⚠️ 텍스처 누락 → 보라/검정
보석 아이템 등록 후 텍스처 PNG가 없으면 인게임에서 보라/검정 체크 패턴으로 표시됩니다. 16×16 PNG를 반드시 추가하세요.
4-1. 모델 JSON
아이템 모델은 item/generated 부모를 상속하는 가장 간단한 형태입니다.
// assets/master_tools/models/item/ruby.json
{
"parent": "minecraft:item/generated",
"textures": {
"layer0": "master_tools:item/ruby"
}
}sapphire.json도 동일 구조이며, "layer0" 값만 "master_tools:item/sapphire"로 변경합니다.
4-2. 언어 파일
// assets/master_tools/lang/en_us.json
{
"item.master_tools.ruby": "Ruby",
"item.master_tools.sapphire": "Sapphire"
}// assets/master_tools/lang/ko_kr.json
{
"item.master_tools.ruby": "루비",
"item.master_tools.sapphire": "사파이어"
}5. purity 컴포넌트 활용 (다음 챕터 미리보기)
다음 챕터에서 도구 내구도와 연결할 purity 컴포넌트를 ItemStack에 적용하는 예시입니다.
// 순도 75% 루비 생성 예시
ItemStack rubyStack = new ItemStack(MasterToolsMod.RUBY.get());
rubyStack.set(MasterToolsMod.PURITY.get(), 75);
// 순도 읽기
int purity = rubyStack.getOrDefault(MasterToolsMod.PURITY.get(), 0);rubyStack.set(컴포넌트, 값) — DataComponentType에 값을 저장합니다.
rubyStack.getOrDefault(컴포넌트, 기본값) — 컴포넌트 값이 없으면 기본값을 반환합니다.
정리
| 항목 | 등록 방식 | 특징 |
|---|---|---|
| Ruby 아이템 | DeferredRegister.createItems() | Rarity.RARE, 64개 스택 |
| Sapphire 아이템 | 동일 패턴 | Rarity.RARE, 64개 스택 |
| purity 컴포넌트 | DeferredRegister.createDataComponents() | Codec.INT 영구 저장, 네트워크 동기화 |
다음 챕터에서는 이 보석 아이템을 재료로 사용하는 커스텀 도구(Custom Tool) 를 만들고, purity 값에 따라 내구도가 달라지는 동적 속성을 구현합니다.