Guides / Building & Resources

커스텀 모델 데이터: 아이템 교체 없이 여러 모델 부여하기

아이템-모델 시스템이 기존의 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_format이 너무 낮음 — 팩은 로드되지만 items/ 폴더가 무시됩니다. 팩 형식을 현재 버전에 맞추세요.
4. 압축 오류 — pack.mcmeta은 zip 파일 내의 폴더 안에 있는 것이 아니라 zip 파일의 루트에 있어야 합니다.

다른 선택자

숫자에 대한 range_dispatch는 한 가지 옵션일 뿐입니다. 또한 minecraft:display_context (손에 들고 있을 때와 액자 안에 있을 때 다른 모델), minecraft:using_item 또는 minecraft:selected를 기준으로 분배할 수 있습니다. 활이 당겨진 상태를 표시하는 방식이 바로 이것입니다.

커스텀 모델 및 아이템 컴포넌트 도구에서 분배 JSON, 모델 파일 및 지급 명령을 함께 만드세요.

커스텀 모델 & 아이템 컴포넌트 도구 →