가이드 / 건축 및 리소스

커스텀 모델 데이터: 아무것도 교체하지 않고 하나의 아이템에 여러 모델 적용하기

아이템 모델 시스템이 기존의 CustomModelData 조건자를 대체했습니다. 폴더 구조, 값을 모델에 매핑하는 JSON, 그리고 텍스처가 보라색 큐브로 표시되는 이유를 알아봅니다.

2026-07-11

커스텀 아이템 모델을 사용하면 서버에서 "마법 지팡이"를 지급할 수 있는데, 이는 실제로는 다른 모델을 가진 당근 낚싯대입니다. 메커니즘이 변경되었지만, 대부분의 튜토리얼은 여전히 예전 방식을 설명하고 있습니다.

무엇이 바뀌었나

예전 방식 — 기본 아이템의 모델 파일 안에 있는 predicate 블록으로, custom_model_data을 숫자로 키로 사용합니다:

{ "predicate": { "custom_model_data": 1 }, "model": "item/wand" }

현재 방식 — 모델을 선택하는 items/ 정의입니다:

assets/minecraft/items/carrot_on_a_stick.json

{
  "model": {
    "type": "minecraft:range_dispatch",
    "property": "minecraft:custom_model_data",
    "fallback": { "type": "minecraft:model", "model": "minecraft:item/carrot_on_a_stick" },
    "entries": [
      { "threshold": 1, "model": { "type": "minecraft:model", "model": "minecraft:item/wand" } }
    ]
  }
}

fallback은 일반 당근 낚싯대가 여전히 어떻게 보이는지를 나타냅니다. 이것이 없으면 월드의 모든 수정되지 않은 당근 낚싯대가 보라색과 검은색의 누락된 모델 큐브로 렌더링됩니다.

폴더 구조

pack.mcmeta
assets/minecraft/
├── items/carrot_on_a_stick.json      the dispatch
├── models/item/wand.json             the model
└── textures/item/wand.png            the texture

가장 단순한 형태의 models/item/wand.json:

{ "parent": "minecraft:item/generated", "textures": { "layer0": "minecraft:item/wand" } }

텍스처 경로에 textures/ 접두사도 없고 .png도 없다는 점에 주목하세요 — 이것이 보라색과 검은색 큐브가 생기는 가장 흔한 원인입니다.

아이템 지급하기

/give @p carrot_on_a_stick[custom_model_data={floats:[1]}]

이 컴포넌트는 이제 단순한 정수가 아니라 타입이 지정된 리스트를 가진 객체를 받습니다. custom_model_data=1은 예전 문법이며, 이제 명령어는 이를 잘못된 형식으로 거부합니다.

왜 보라색 큐브로 표시되는가

가능성이 높은 순서대로:

1. 텍스처 경로 오류 — textures/ 또는 .png이 포함되어 있거나, 파일이 경로가 가리키는 위치에 없습니다.
2. 파일 이름 대소문자 — 운영체제가 대소문자를 구분하지 않더라도 게임은 구분합니다.
3. 오래된 pack.mcmeta — 26.x는 min_format과 max_format을 요구합니다; 단순한 pack_format에 현재 형식 번호를 넣으면 팩이 호환되지 않는 것으로 표시됩니다.
4. 잘못된 압축 — pack.mcmeta은 zip의 루트에 있어야 하며, zip 안의 폴더 안에 있으면 안 됩니다.

다른 선택자

숫자에 대한 range_dispatch은 하나의 옵션일 뿐입니다. minecraft:display_context(손에 들었을 때와 액자에 넣었을 때 다른 모델), minecraft:using_item, 또는 minecraft:selected로도 분기할 수 있습니다 — 이것이 활이 당겨진 상태를 표시하는 방식입니다.

커스텀 모델 & 아이템 컴포넌트 도구에서 디스패치 JSON, 모델 파일, 지급 명령어를 함께 작성하세요.

사용자 지정 모델·아이템 컴포넌트 도구 →