아이템 태그 시스템

태그는 여러 아이템을 하나의 그룹으로 묶는 데이터팩 기반 메커니즘입니다. 레시피에서 "나무 판자 아무거나"를 허용하거나, 코드에서 "보석 계열 아이템인지" 검사할 때 태그를 씁니다. 하드코딩 없이 JSON 파일 하나로 그룹을 정의하고, 다른 모드가 그 그룹에 자신의 아이템을 추가할 수도 있습니다.

1. 태그 JSON 위치와 형식

태그 파일은 src/main/resources/data/<modId>/tags/items/ 아래에 둡니다.

examplemod-template-26.1.2/src/main/resources/
└── data/
    └── examplemod/
        └── tags/
            └── items/
                └── gems.json

파일 내용:

// examplemod-template-26.1.2/src/main/resources/data/examplemod/tags/items/gems.json
{
  "replace": false,
  "values": [
    "examplemod:ruby",
    "examplemod:sapphire",
    "examplemod:emerald_shard"
  ]
}

필드 설명:

values 항목에 # 접두사를 붙이면 다른 태그 전체를 포함할 수 있습니다.

{
  "replace": false,
  "values": [
    "examplemod:ruby",
    "#minecraft:planks"
  ]
}

#minecraft:planks는 바닐라 나무 판자 태그 전체를 이 태그에 포함시킵니다.

2. 바닐라 태그에 모드 아이템 추가

바닐라 태그를 확장하려면 경로 구조를 그대로 따라가면 됩니다. minecraft:planks 태그에 모드 아이템을 추가하는 예시:

data/examplemod/tags/items/minecraft/planks.json

// examplemod-template-26.1.2/src/main/resources/data/examplemod/tags/items/minecraft/planks.json
{
  "replace": false,
  "values": [
    "examplemod:ruby_planks"
  ]
}

파일 경로의 minecraft/planks 부분이 태그 ID minecraft:planks에 대응합니다. replace: false이므로 기존 바닐라 판자들은 그대로 유지되고 examplemod:ruby_planks만 추가됩니다.

3. TagKey 선언

코드에서 태그를 참조하려면 TagKey<Item>을 선언합니다.

// examplemod-template-26.1.2/src/main/java/com/example/examplemod/ExampleMod.java
import net.minecraft.tags.ItemTags;
import net.minecraft.tags.TagKey;
import net.minecraft.resources.Identifier;
 
public class ExampleMod {
    public static final TagKey<Item> GEMS =
            ItemTags.create(Identifier.fromNamespaceAndPath(MODID, "gems"));
}

ItemTags.create()는 TagKey<Item>을 반환합니다. NeoForge 26.1.2에서는 Identifier.fromNamespaceAndPath()를 써야 합니다. 구버전의 ResourceLocation 클래스는 삭제되어 net.minecraft.resources.Identifier로 대체되었고, 두 인자를 받는 생성자 new ResourceLocation(namespace, path)도 더 이상 존재하지 않습니다.

4. 코드에서 태그 검사

ItemStack.is(TagKey<Item>) 메서드로 아이템이 특정 태그에 속하는지 확인합니다.

// 아이템 사용 이벤트 등에서
ItemStack stack = player.getMainHandItem();
 
if (stack.is(ExampleMod.GEMS)) {
    // 보석 계열 아이템 처리
    player.sendSystemMessage(Component.literal("보석을 들고 있습니다!"));
}

Item.builtInRegistryHolder().is(TagKey<Item>) 방식도 있지만, ItemStack.is()가 더 간결합니다.

5. 인게임 명령어로 태그 확인

게임 내에서 태그를 직접 테스트할 수 있습니다.

/give @p #minecraft:planks

# 접두사를 붙이면 해당 태그 안의 아이템 중 하나를 무작위로 지급합니다.

/give @p #examplemod:gems

모드 태그도 같은 방식으로 테스트합니다. 태그가 올바르게 로드되지 않으면 명령어 자동완성에 나타나지 않습니다.

6. 태그 종류

아이템 태그 외에도 다양한 레지스트리에 태그를 정의할 수 있습니다.

7. 안티패턴: 잘못된 태그 이름

⚠️ 잘못된 태그 이름

// ❌ 콜론 빠짐 → 데이터팩 로드 에러
"values": ["examplemod ruby"]
 
// ❌ 대문자 → 거부됨
"values": ["examplemod:RUBY"]
 
// ✅ namespace:path 형식, lowercase
"values": ["examplemod:ruby"]

데이터팩 로드 실패 시 콘솔에 "Invalid identifier" 에러가 출력됩니다. 모든 태그 값은 namespace:path 형식이어야 하고, 소문자와 숫자, _, -, /만 허용됩니다.

8. 인게임 확인

1. 게임 실행 후 크리에이티브 모드 진입
2. 채팅창(T)에서 /give @p #examplemod:gems 입력
3. 태그에 등록된 아이템 중 하나가 지급되는지 확인
4. ExampleMod.GEMS 태그를 검사하는 코드가 있다면 해당 아이템을 들고 동작 확인

요약

• 태그 JSON은 data/<modId>/tags/items/<tag_name>.json에 위치합니다.
• replace: false로 기존 태그를 유지하면서 항목을 추가합니다.
• 바닐라 태그 확장은 경로 구조를 그대로 따라가면 됩니다.
• 코드에서는 ItemTags.create(Identifier.fromNamespaceAndPath(...))로 TagKey<Item>을 선언합니다.
• ItemStack.is(TagKey)로 태그 소속 여부를 검사합니다.
• 태그 이름은 namespace:path 형식, 소문자만 허용됩니다.

다음 챕터에서는 아이템에 내구도와 수리 메커니즘을 추가하는 방법을 학습합니다.