툴팁 커스터마이즈

아이템에 마우스를 올리면 나타나는 툴팁은 플레이어에게 아이템 정보를 전달하는 가장 직접적인 수단입니다. NeoForge 26에서는 appendHoverText를 오버라이드해 원하는 텍스트를 자유롭게 추가할 수 있습니다.

1. appendHoverText 오버라이드

Item 클래스의 appendHoverText 메서드를 오버라이드합니다. 이 메서드는 툴팁이 렌더링될 때 호출되며, tooltip 리스트에 Component를 추가하면 됩니다.

// examplemod-template-26.1.2/src/main/java/com/example/examplemod/item/MagicWandItem.java
public class MagicWandItem extends Item {
    public MagicWandItem(Properties props) { super(props); }
 
    @Override
    public void appendHoverText(ItemStack stack, TooltipContext context,
                                List<Component> tooltip, TooltipFlag flag) {
        int charge = stack.getOrDefault(ExampleMod.CHARGE.get(), 0);
        tooltip.add(Component.translatable("tooltip.examplemod.charge", charge)
            .withStyle(ChatFormatting.GOLD));
 
        if (flag.isAdvanced()) {
            tooltip.add(Component.literal("[F3+H 디버그 정보]")
                .withStyle(ChatFormatting.DARK_GRAY));
        }
    }
}

메서드 파라미터 역할:

2. lang 키 추가

번역 키를 lang 파일에 추가합니다.

resources/assets/examplemod/lang/ko_kr.json:

{
  "tooltip.examplemod.charge": "충전량: %s"
}

resources/assets/examplemod/lang/en_us.json:

{
  "tooltip.examplemod.charge": "Charge: %s"
}

%s는 Component.translatable의 두 번째 인자(charge)로 치환됩니다. 정수 외에도 문자열·Component 모두 전달할 수 있습니다.

3. ChatFormatting 색상표

withStyle(ChatFormatting.XXX)로 텍스트 색상을 지정합니다. 자주 쓰는 색상:

4. F3+H 어드밴스드 툴팁

게임에서 F3+H를 누르면 어드밴스드 툴팁 모드가 활성화됩니다. flag.isAdvanced()가 true를 반환하는 상태입니다. 이 조건 아래에만 표시할 디버그 정보를 추가할 수 있습니다.

if (flag.isAdvanced()) {
    tooltip.add(Component.literal("[F3+H 디버그 정보]")
        .withStyle(ChatFormatting.DARK_GRAY));
    // 내부 NBT 값, 레지스트리 키 등 개발자용 정보
}

일반 플레이어에게는 보이지 않으므로 내부 상태 디버깅에 적합합니다.

5. TooltipContext 활용

context 파라미터로 현재 레벨과 플레이어 정보에 접근할 수 있습니다.

@Override
public void appendHoverText(ItemStack stack, TooltipContext context,
                            List<Component> tooltip, TooltipFlag flag) {
    // 레벨 정보 접근 (null 가능 — 인벤토리 화면 등)
    Level level = context.level();
    if (level != null) {
        tooltip.add(Component.literal("현재 차원: " + level.dimension().location())
            .withStyle(ChatFormatting.GRAY));
    }
}

context.level()은 인벤토리 화면이나 레시피 북에서 null일 수 있습니다. 반드시 null 체크를 합니다.

6. 안티패턴: 무한 텍스트로 화면 가림

⚠️ 무한 텍스트로 화면 가림

// ❌ 1000줄 추가 시 인벤토리 화면 가려짐 + 성능 저하
for (int i = 0; i < 1000; i++) {
    tooltip.add(Component.literal("Line " + i));
}

권장: 5~10줄 이내 + flag.isAdvanced() 조건부 추가. 툴팁은 매 프레임 렌더링되므로 무거운 연산도 금지입니다.

7. 인게임 확인

1. 게임 실행 후 크리에이티브 모드 진입
2. E 키로 인벤토리 열기
3. MagicWandItem에 마우스 올리기 → 충전량 툴팁 확인
4. F3+H 누른 뒤 다시 마우스 올리기 → 어드밴스드 정보 추가 확인

요약

• appendHoverText를 오버라이드해 tooltip.add(Component)로 줄을 추가합니다.
• Component.translatable로 다국어 지원, withStyle(ChatFormatting.XXX)로 색상을 입힙니다.
• flag.isAdvanced()로 F3+H 어드밴스드 모드에서만 보이는 디버그 정보를 추가할 수 있습니다.
• context.level()은 null 가능 — 반드시 null 체크합니다.
• 툴팁은 5~10줄 이내로 유지하고, 무거운 연산은 넣지 않습니다.

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