NeoForge 26.1.2의 도구 아이템 등록을 학습합니다. PickaxeItem·SwordItem은 삭제되어 ToolMaterial.applyToolProperties/applySwordProperties로 대체되고, AxeItem·ShovelItem은 ToolMaterial을 받습니다.

도구 아이템 — Tier 시스템과 4종 도구 등록

일반 Item과 달리 도구 아이템은 채굴 레벨, 내구도, 공격력 같은 속성을 Tier 하나로 묶어서 관리합니다. 바닐라 Tier 6종을 먼저 이해하고, 루비 도구 4종을 직접 등록해 봅니다.

1. ToolMaterial이란?

26.1.2 변경: 기존의 Tier 인터페이스와 Tiers enum은 삭제되었습니다. 도구 재질은 이제 net.minecraft.world.item.ToolMaterial record 로 표현하며, 바닐라는 WOOD·STONE·COPPER·IRON·GOLD·DIAMOND·NETHERITE 상수를 제공합니다.

ToolMaterial은 도구의 재질 등급을 나타내는 record로, 내구도·채굴 속도·공격력·인챈트 가중치·수리 재료, 그리고 "이 재질로 캐도 드롭되지 않는 블록 태그"를 묶어서 담습니다.

ToolMaterial	드롭 불가 블록 태그	내구도	채굴 속도	공격 보너스	인챈트 가중치	수리 재료
`WOOD`	`INCORRECT_FOR_WOODEN_TOOL`	59	2.0	0.0	15	나무 판자
`STONE`	`INCORRECT_FOR_STONE_TOOL`	131	4.0	1.0	5	조약돌
`IRON`	`INCORRECT_FOR_IRON_TOOL`	250	6.0	2.0	14	철 주괴
`GOLD`	`INCORRECT_FOR_GOLD_TOOL`	32	12.0	0.0	22	금 주괴
`DIAMOND`	`INCORRECT_FOR_DIAMOND_TOOL`	1561	8.0	3.0	10	다이아몬드
`NETHERITE`	`INCORRECT_FOR_NETHERITE_TOOL`	2031	9.0	4.0	15	네더라이트 주괴

각 값의 의미:

드롭 불가 블록 태그(incorrectBlocksForDrops): 이 재질로 캐면 블록은 깨지지만 드롭이 나오지 않는 블록 태그. 채굴 등급은 더 이상 정수 레벨이 아니라 이 태그로 결정됩니다(다이아 등급이면 INCORRECT_FOR_DIAMOND_TOOL).
내구도(durability): 도구가 파괴되기 전 사용 횟수.
채굴 속도(speed): 블록을 캐는 속도 배율.
공격 보너스(attackDamageBonus): 기본 공격력에 더해지는 추가 피해.
인챈트 가중치(enchantmentValue): 인챈트 테이블에서 좋은 인챈트가 붙을 확률.
수리 재료(repairItems): 모루에서 도구를 수리할 때 쓰는 아이템 태그.

26.1.2에서는 곡괭이·검 전용 클래스(PickaxeItem/SwordItem)가 삭제되었습니다. 곡괭이와 검은 평범한 Item에 ToolMaterial.applyToolProperties(...) / applySwordProperties(...)로 도구 속성을 입혀 등록합니다. 도끼·삽은 여전히 AxeItem·ShovelItem 클래스가 존재하며 생성자에 ToolMaterial을 받습니다. 또한 아이템은 register(...)가 아니라 registerItem(name, props -> ...)로 등록해야 합니다(람다가 받은 props에 id가 설정됨).

// examplemod-template-26.1.2/src/main/java/com/example/examplemod/ExampleMod.java
 
// 곡괭이·검: 전용 클래스 대신 Item + ToolMaterial.apply*Properties
public static final DeferredItem<Item> RUBY_PICKAXE = ITEMS.registerItem("ruby_pickaxe",
    props -> new Item(ToolMaterial.DIAMOND.applyToolProperties(
        props, BlockTags.MINEABLE_WITH_PICKAXE, 1.0f, -2.8f, 0.0f)));
 
public static final DeferredItem<Item> RUBY_SWORD = ITEMS.registerItem("ruby_sword",
    props -> new Item(ToolMaterial.DIAMOND.applySwordProperties(props, 3.0f, -2.4f)));
 
// 도끼·삽: AxeItem / ShovelItem 은 존속 — 생성자에 ToolMaterial + 공격력 + 공격 속도 + Properties
public static final DeferredItem<Item> RUBY_AXE = ITEMS.registerItem("ruby_axe",
    props -> new AxeItem(ToolMaterial.DIAMOND, 5.0f, -3.1f, props));
 
public static final DeferredItem<Item> RUBY_SHOVEL = ITEMS.registerItem("ruby_shovel",
    props -> new ShovelItem(ToolMaterial.DIAMOND, 1.5f, -3.0f, props));

네 도구 모두 ToolMaterial.DIAMOND를 써서 다이아 광석·흑요석을 캘 수 있는 등급으로 만듭니다. applyToolProperties의 인자는 차례로 채굴 동작을 부여할 블록 태그(MINEABLE_WITH_PICKAXE), 공격력 추가치, 공격 속도, 공격 범위 보너스입니다. applySwordProperties는 공격력과 공격 속도만 받습니다.

3. 도구별 특징

도구	생성 방식	주 용도	공격 속도	특이사항
곡괭이	`Item` + `applyToolProperties(MINEABLE_WITH_PICKAXE, …)`	돌·광석 채굴	느림	드롭 불가 태그가 가장 중요
검	`Item` + `applySwordProperties(…)`	전투	빠름	공격 보너스 가장 높음
도끼	`AxeItem(ToolMaterial, atk, spd, props)`	나무 채굴 + 전투	매우 느림	방패 막기 해제 가능
삽	`ShovelItem(ToolMaterial, atk, spd, props)`	흙·모래 채굴	느림	잔디 경로 만들기 가능

4. ToolMaterial 선택 기준

루비 도구에 어떤 ToolMaterial을 쓸지 결정할 때 기준은 두 가지입니다.

드롭 등급: 어떤 블록을 캐야 하는가? (재질이 곧 캘 수 있는 블록 등급을 정합니다)

WOOD     → 돌, 석탄 광석
STONE    → 철 광석, 구리 광석
IRON     → 금 광석, 다이아 광석, 에메랄드 광석
DIAMOND  → 흑요석, 고대 잔해
NETHERITE → 특수 블록 (모드 추가 블록)

내구도와 속도: 플레이어 경험 설계. 루비가 다이아보다 약간 약하게 하고 싶다면 ToolMaterial.IRON을 쓰고, 동급으로 만들고 싶다면 ToolMaterial.DIAMOND를 씁니다.

5. 안티패턴: 잘못된 ToolMaterial 사용

⚠️ 잘못된 ToolMaterial 사용

WOOD 재질 곡괭이로 다이아 블록 채굴:
public static final DeferredItem<Item> RUBY_PICKAXE = ITEMS.registerItem("ruby_pickaxe",
    props -> new Item(ToolMaterial.WOOD.applyToolProperties(
        props, BlockTags.MINEABLE_WITH_PICKAXE, 1.0f, -2.8f, 0.0f)));
→ 블록은 깨지지만 드롭 0개 (재질 등급 부족) → 정확한 ToolMaterial 매칭 필요 (다이아 블록 = STONE 이상, 흑요석 = DIAMOND 이상)

재질 등급이 부족하면 블록 파괴 애니메이션은 나오지만 아이템이 드롭되지 않습니다. 인게임에서 확인하기 전까지 눈치채기 어려운 버그입니다.

6. 커스텀 ToolMaterial 미리보기

바닐라 상수로 부족하다면 ToolMaterial record 를 직접 생성해서 완전히 새로운 재질을 만들 수 있습니다. 생성자 인자는 차례로 드롭 불가 블록 태그·내구도·채굴 속도·공격력 추가치·인챈트 가중치·수리 재료 태그입니다.

// 마스터 트랙에서 다룰 내용 — 미리보기만
// ToolMaterial(incorrectBlocksForDrops, durability, speed, attackDamageBonus, enchantmentValue, repairItems)
public static final TagKey<Item> REPAIR_TAG =
        ItemTags.create(Identifier.fromNamespaceAndPath("master_tools", "repairs_ruby_tools"));
 
public static final ToolMaterial RUBY = new ToolMaterial(
        BlockTags.INCORRECT_FOR_DIAMOND_TOOL, // 다이아 등급 — 흑요석 등은 드롭 불가
        1024,   // 내구도 (Iron 250 < Ruby < Diamond 1561)
        8.0f,   // 채굴 속도 (Diamond 동급)
        3.5f,   // 공격력 추가치 (Diamond 3.0보다 높음)
        18,     // 인챈트 가중치
        REPAIR_TAG); // 수리 재료 태그

커스텀 ToolMaterial 구현은 마스터 트랙 phase-6에서 자세히 다룹니다. 지금은 바닐라 ToolMaterial 상수를 활용하는 것으로 충분합니다.

7. 인게임 검증

4종 도구를 등록한 뒤 게임을 실행해서 동작을 확인합니다.

/give @p examplemod:ruby_pickaxe
/give @p examplemod:ruby_sword
/give @p examplemod:ruby_axe
/give @p examplemod:ruby_shovel

확인 항목:

크리에이티브 인벤토리 모드 탭에 4종 도구가 보이는가?
곡괭이로 다이아 광석을 캤을 때 드롭이 나오는가?
검으로 몹을 공격했을 때 피해가 들어가는가?
삽으로 잔디 블록을 우클릭하면 경로 블록으로 바뀌는가?

요약

ToolMaterial은 도구의 드롭 불가 블록 태그·내구도·속도·공격력·인챈트 가중치·수리 재료를 묶은 record. (26.1.2에서 Tier/Tiers는 삭제됨)
바닐라 ToolMaterial 상수: WOOD · STONE · COPPER · IRON · GOLD · DIAMOND · NETHERITE.
곡괭이·검은 전용 클래스 대신 Item + ToolMaterial.applyToolProperties / applySwordProperties. 도끼·삽은 AxeItem·ShovelItem(생성자에 ToolMaterial+공격력+공격 속도+Properties) 존속.
재질 등급이 부족하면 블록은 깨지지만 드롭이 없다. ToolMaterial 선택 시 반드시 확인.
커스텀 ToolMaterial(record 직접 생성)은 마스터 트랙에서 다룬다.

다음 챕터에서는 음식 아이템(FoodProperties)을 만들어 먹을 수 있는 아이템을 등록합니다.

도구 아이템 — Tier 시스템과 4종 도구 등록

1. ToolMaterial이란?

26.1.2 변경: 기존의 Tier 인터페이스와 Tiers enum은 삭제되었습니다. 도구 재질은 이제 net.minecraft.world.item.ToolMaterial record 로 표현하며, 바닐라는 WOOD·STONE·COPPER·IRON·GOLD·DIAMOND·NETHERITE 상수를 제공합니다.

ToolMaterial	드롭 불가 블록 태그	내구도	채굴 속도	공격 보너스	인챈트 가중치	수리 재료
`WOOD`	`INCORRECT_FOR_WOODEN_TOOL`	59	2.0	0.0	15	나무 판자
`STONE`	`INCORRECT_FOR_STONE_TOOL`	131	4.0	1.0	5	조약돌
`IRON`	`INCORRECT_FOR_IRON_TOOL`	250	6.0	2.0	14	철 주괴
`GOLD`	`INCORRECT_FOR_GOLD_TOOL`	32	12.0	0.0	22	금 주괴
`DIAMOND`	`INCORRECT_FOR_DIAMOND_TOOL`	1561	8.0	3.0	10	다이아몬드
`NETHERITE`	`INCORRECT_FOR_NETHERITE_TOOL`	2031	9.0	4.0	15	네더라이트 주괴

각 값의 의미:

드롭 불가 블록 태그(incorrectBlocksForDrops): 이 재질로 캐면 블록은 깨지지만 드롭이 나오지 않는 블록 태그. 채굴 등급은 더 이상 정수 레벨이 아니라 이 태그로 결정됩니다(다이아 등급이면 INCORRECT_FOR_DIAMOND_TOOL).
내구도(durability): 도구가 파괴되기 전 사용 횟수.
채굴 속도(speed): 블록을 캐는 속도 배율.
공격 보너스(attackDamageBonus): 기본 공격력에 더해지는 추가 피해.
인챈트 가중치(enchantmentValue): 인챈트 테이블에서 좋은 인챈트가 붙을 확률.
수리 재료(repairItems): 모루에서 도구를 수리할 때 쓰는 아이템 태그.

2. 4종 도구 등록

// examplemod-template-26.1.2/src/main/java/com/example/examplemod/ExampleMod.java
 
// 곡괭이·검: 전용 클래스 대신 Item + ToolMaterial.apply*Properties
public static final DeferredItem<Item> RUBY_PICKAXE = ITEMS.registerItem("ruby_pickaxe",
    props -> new Item(ToolMaterial.DIAMOND.applyToolProperties(
        props, BlockTags.MINEABLE_WITH_PICKAXE, 1.0f, -2.8f, 0.0f)));
 
public static final DeferredItem<Item> RUBY_SWORD = ITEMS.registerItem("ruby_sword",
    props -> new Item(ToolMaterial.DIAMOND.applySwordProperties(props, 3.0f, -2.4f)));
 
// 도끼·삽: AxeItem / ShovelItem 은 존속 — 생성자에 ToolMaterial + 공격력 + 공격 속도 + Properties
public static final DeferredItem<Item> RUBY_AXE = ITEMS.registerItem("ruby_axe",
    props -> new AxeItem(ToolMaterial.DIAMOND, 5.0f, -3.1f, props));
 
public static final DeferredItem<Item> RUBY_SHOVEL = ITEMS.registerItem("ruby_shovel",
    props -> new ShovelItem(ToolMaterial.DIAMOND, 1.5f, -3.0f, props));

3. 도구별 특징

도구	생성 방식	주 용도	공격 속도	특이사항
곡괭이	`Item` + `applyToolProperties(MINEABLE_WITH_PICKAXE, …)`	돌·광석 채굴	느림	드롭 불가 태그가 가장 중요
검	`Item` + `applySwordProperties(…)`	전투	빠름	공격 보너스 가장 높음
도끼	`AxeItem(ToolMaterial, atk, spd, props)`	나무 채굴 + 전투	매우 느림	방패 막기 해제 가능
삽	`ShovelItem(ToolMaterial, atk, spd, props)`	흙·모래 채굴	느림	잔디 경로 만들기 가능

4. ToolMaterial 선택 기준

루비 도구에 어떤 ToolMaterial을 쓸지 결정할 때 기준은 두 가지입니다.

드롭 등급: 어떤 블록을 캐야 하는가? (재질이 곧 캘 수 있는 블록 등급을 정합니다)

WOOD     → 돌, 석탄 광석
STONE    → 철 광석, 구리 광석
IRON     → 금 광석, 다이아 광석, 에메랄드 광석
DIAMOND  → 흑요석, 고대 잔해
NETHERITE → 특수 블록 (모드 추가 블록)

5. 안티패턴: 잘못된 ToolMaterial 사용

⚠️ 잘못된 ToolMaterial 사용

WOOD 재질 곡괭이로 다이아 블록 채굴:
public static final DeferredItem<Item> RUBY_PICKAXE = ITEMS.registerItem("ruby_pickaxe",
    props -> new Item(ToolMaterial.WOOD.applyToolProperties(
        props, BlockTags.MINEABLE_WITH_PICKAXE, 1.0f, -2.8f, 0.0f)));
→ 블록은 깨지지만 드롭 0개 (재질 등급 부족) → 정확한 ToolMaterial 매칭 필요 (다이아 블록 = STONE 이상, 흑요석 = DIAMOND 이상)

재질 등급이 부족하면 블록 파괴 애니메이션은 나오지만 아이템이 드롭되지 않습니다. 인게임에서 확인하기 전까지 눈치채기 어려운 버그입니다.

6. 커스텀 ToolMaterial 미리보기

// 마스터 트랙에서 다룰 내용 — 미리보기만
// ToolMaterial(incorrectBlocksForDrops, durability, speed, attackDamageBonus, enchantmentValue, repairItems)
public static final TagKey<Item> REPAIR_TAG =
        ItemTags.create(Identifier.fromNamespaceAndPath("master_tools", "repairs_ruby_tools"));
 
public static final ToolMaterial RUBY = new ToolMaterial(
        BlockTags.INCORRECT_FOR_DIAMOND_TOOL, // 다이아 등급 — 흑요석 등은 드롭 불가
        1024,   // 내구도 (Iron 250 < Ruby < Diamond 1561)
        8.0f,   // 채굴 속도 (Diamond 동급)
        3.5f,   // 공격력 추가치 (Diamond 3.0보다 높음)
        18,     // 인챈트 가중치
        REPAIR_TAG); // 수리 재료 태그

커스텀 ToolMaterial 구현은 마스터 트랙 phase-6에서 자세히 다룹니다. 지금은 바닐라 ToolMaterial 상수를 활용하는 것으로 충분합니다.

7. 인게임 검증

4종 도구를 등록한 뒤 게임을 실행해서 동작을 확인합니다.

/give @p examplemod:ruby_pickaxe
/give @p examplemod:ruby_sword
/give @p examplemod:ruby_axe
/give @p examplemod:ruby_shovel

확인 항목:

크리에이티브 인벤토리 모드 탭에 4종 도구가 보이는가?
곡괭이로 다이아 광석을 캤을 때 드롭이 나오는가?
검으로 몹을 공격했을 때 피해가 들어가는가?
삽으로 잔디 블록을 우클릭하면 경로 블록으로 바뀌는가?

요약

ToolMaterial은 도구의 드롭 불가 블록 태그·내구도·속도·공격력·인챈트 가중치·수리 재료를 묶은 record. (26.1.2에서 Tier/Tiers는 삭제됨)
바닐라 ToolMaterial 상수: WOOD · STONE · COPPER · IRON · GOLD · DIAMOND · NETHERITE.
곡괭이·검은 전용 클래스 대신 Item + ToolMaterial.applyToolProperties / applySwordProperties. 도끼·삽은 AxeItem·ShovelItem(생성자에 ToolMaterial+공격력+공격 속도+Properties) 존속.
재질 등급이 부족하면 블록은 깨지지만 드롭이 없다. ToolMaterial 선택 시 반드시 확인.
커스텀 ToolMaterial(record 직접 생성)은 마스터 트랙에서 다룬다.

다음 챕터에서는 음식 아이템(FoodProperties)을 만들어 먹을 수 있는 아이템을 등록합니다.

도구 아이템 — Tier 시스템과 4종 도구 등록

도구 아이템 — Tier 시스템과 4종 도구 등록

1. ToolMaterial이란?

2. 4종 도구 등록

3. 도구별 특징

4. ToolMaterial 선택 기준

5. 안티패턴: 잘못된 ToolMaterial 사용

6. 커스텀 ToolMaterial 미리보기

7. 인게임 검증

요약

On this page

도구 아이템 — Tier 시스템과 4종 도구 등록

도구 아이템 — Tier 시스템과 4종 도구 등록

1. ToolMaterial이란?

2. 4종 도구 등록

3. 도구별 특징

4. ToolMaterial 선택 기준

5. 안티패턴: 잘못된 ToolMaterial 사용

6. 커스텀 ToolMaterial 미리보기

7. 인게임 검증

요약

On this page