# Minecraft Item Model Mapping

> Minecraft Item Model Definition 物品模型定义格式：Root Format 根格式（hand_animation_on_swap 切换动画、oversized_in_gui 超出槽位渲染、swap_animation_scale 动画速度缩放、model 模型定义）、Item Model Definitions 模型定义类型（type 命名空间ID + 类型特定字段 + transformation 可选）：Condition 条件分派 property+on_true/on_false 递归、Range Dispatch 数值分派 scale+entries threshold+fallback、Select 选择分派 cases when value list+fallback、Model 烘焙模型 model路径+tints着色列表（custom_model_data/constant/grass/firework/dye/potion/map_color/team）、Bundle/Selected Item 渲染选中物品、Composite 复合模型列表从后到前渲染、Special 特殊模型渲染 banner/book/chest/copper_golem_statue/end_cube/head/shulker_box）、Transformation 变换（矩阵16浮点 分解形式 right_rotation quaternion/scale/left_rotation/translation）、Condition Properties 条件属性（broken/bundle/has_selected_item/damaged/using_item/custom_model_data/component/has_component/keybind_down）、Range Properties 数值属性（custom_model_data/compass compass摇摆 progress target spawn/lodestone/none/count 栈数量/decay 损坏值/time 时间 clock wobble daytime/random/moon_phase/use_cycle/use_duration）、Select Properties 枚举属性（con

- Skill: `zmjjkk123-hub/minecraft-item-model-mapping` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zmjjkk123-hub/minecraft-item-model-mapping`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zmjjkk123-hub/minecraft-item-model-mapping/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: ZMJJKK123-hub (https://skillmd.com/u/zmjjkk123-hub)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zmjjkk123-hub/minecraft-item-model-mapping

---


# Item Model Definition

Item model definitions (officially "item models" / "client-side item info") select which baked model an item stack renders, based on the stack's data. Java Edition only. Files are JSON in `assets/<namespace>/items/` (one per item ID; vanilla: `assets/minecraft/items/<item id>.json`). Invalid definitions fall back to the missing model.

## Root Format

- `hand_animation_on_swap` (default true) — play the swap animation when switching to this stack in the hotbar (never plays if stacks differ only by durability, per the `damage` component).
- `oversized_in_gui` (default false) — allow rendering beyond the slot bounds in GUIs.
- `swap_animation_scale` (default 1) — speed multiplier of the swap animation (larger models may need larger values).
- `model` (required) — the item model definition (see below).

## Item Model Definitions

Every definition has `type` (namespace ID) plus type-specific fields, and may carry a `transformation`:

- `condition` — boolean dispatch: `property` (predicate type) with `on_true` / `on_false` (recursive definitions). If the property value is missing/invalid, `on_false` is used.
- `range_dispatch` — numeric dispatch: compute a numeric property, multiply by `scale` (default 1), pick the first sorted `entries` item whose `threshold` is reached (entries are sorted at runtime); below all thresholds use `fallback` (absent → missing model).
- `select` — enum dispatch: `cases` (list of `{when: value or list, model}`; duplicate cases error with `Duplicate case conditions: ...`), `fallback` for unmatched values (absent → missing model).
- `model` — render a baked model: `model` (path → `assets/<ns>/models/<path>.json`), `tints` (list indexed by tint index of color providers):
  - `custom_model_data` — color from `custom_model_data` component `colors[index]` (`default` RGB, `index` default 0).
  - `constant` — fixed `value` (RGB int).
  - `grass` — biome grass color from `temperature` + `downfall` (0–1 each) using `grass.png`.
  - `firework` — average of the `firework_explosion` component's `colors`.
  - `dye` — the `dyed_color` component color.
  - `potion` — the `potion_contents` component color.
  - `map_color` — the `map_color` component color.
  - `team` — the holding entity's team color.
  - (the last five use `default` RGB when unavailable).
- `bundle/selected_item` — renders the currently selected item inside the bundle; requires the `bundle_contents` component, else nothing renders.
- `composite` — computes all `models` (list) and renders them back to front (e.g. bundle back layer + selected item + front layer).
- `special` — hardcoded special model rendering: `base` (base item model providing transforms/gui light/particle texture) + `model`:
  - `banner` — banner from base color + `banner_patterns`: `attachment` (`wall`/`ground`, default `ground`), `color`.
  - `book` — lectern-like book: `open_angle` (0 closed – 90 flat), `page1`, `page2` (0 left – 1 right).
  - `chest` — chest: `chest_type` (`single`/`left`/`right`), `openness` (default 0), `texture` (→ `assets/<ns>/textures/entity/chest/<path>.png`).
  - `copper_golem_statue` — `pose` (`standing`/`sitting`/`running`/`star`), `texture` (→ `assets/<ns>/<path>`).
  - `end_cube` — special-effect cube: `effect` (`portal` or `gateway`).
  - `head` — mob head: `kind` (`creeper`/`dragon`/`piglin`/`player`/`skeleton`/`wither_skeleton`/`zombie`), `animation` (default 0; dragon/piglin animation progress), `texture` (→ `assets/<ns>/textures/entity/<path>.png`).
  - `shulker_box` — `openness` (default 0), `texture` (→ `assets/<ns>/textures/entity/shulker/<path>.png`).

### Transformation

Applied after the baked model's own `display` transforms, origin at the stack's position:

- Matrix form: 16 floats, row-major; elements 13–15 have no effect; element 16 scales the first 12 (division).
- Decomposed form (all required, applied in order): `right_rotation` (quaternion `[x,y,z,w]` — non-unit scales the model — or `{angle (radians), axis}`), `scale` `[x,y,z]`, `left_rotation` (same formats), `translation` `[x,y,z]`.

## Condition Properties (boolean)

- `broken` — item is broken (damage ≥ max_damage). Example: elytra → `item/elytra_broken`.
- `bundle/has_selected_item` — the bundle has a selected item.
- `damaged` — the item has damage.
- `using_item` — a mob is currently using the item (bow pulling, brush brushing...).
- `custom_model_data` — reads `custom_model_data` component `flags[index]` (index default 0; missing component or out of range → false).
- `component` — `predicate` (data component predicate type) + `value` (predicate contents); true when the stack satisfies it.
- `has_component` — `component` (component type); `ignore_default` (default false) — treat default-valued components as absent.
- `keybind_down` — `keybind` (binding localization key) is currently pressed.

## Range Properties (numeric)

- `custom_model_data` — `floats[index]` (index default 0; missing/out of range → 0).
- `compass` — compass wobble progress (0–1). `target`: `spawn` (toward the world spawn in the Overworld), `lodestone` (toward the `lodestone_tracker` position; random wobble when no target, cross-dimension, or <1e-5 distance), `none` (random). `wobble` (default true) — extra wobble oscillation.
- `count` — stack count, clamped to max stack size; `normalize` (default true) — return count/maxStack instead.
- `damage` — damage value (0 if undamaged/unbreakable; clamped to max durability); `normalize` (default true) — return damage/max.
- `time` — smooth clock wobble progress (0–1) of the current dimension time: `source` = `daytime` (time of day), `random` (random), `moon_phase` (0–1 per moon phase); `wobble` (default true).
- `use_cycle` — remaining use time modulo `period` (default 1). Example: brush animates over a 10.0 period scaled 0.1.
- `use_duration` — use time or remaining use time (`remaining`, default false). Example: bow pulling states.
- (Also in the property table on the wiki: `cooldown`.)

## Select Properties (enum)

- `context_dimension` — the current dimension ID (e.g. compass: `minecraft:overworld` vs random fallback).
- `trim_material` — the trim material from the `trim` component (chainmail boots per-material models).
- `block_state` — the `block_state` component's block property value: `block_state_property` (e.g. `honey_level` on bee nests/hives; no component/property → null, unmatched).
- `component` — full component value match (persistent components only; non-persistent or mismatched values fail loading). Matching is exact (SNBT-normalized): `{a:data,b:true}` == `"{\"a\":\"data\",\"b\":true}"`; partial matches like `{"a":"data"}` do NOT match `{a:data,b:true}`.
- `custom_model_data` — `strings[index]` (missing/out of range → null).
- `local_time` — formatted local date/time string: `pattern` (date format, e.g. `MM-dd`), `locale` (default ""), `time_zone` (default system). Fetched at most once per second. Example: chest uses the Christmas texture on 12-24..12-26.
- (Other enum properties in the table: `main_hand`, etc. — see the Minecraft Wiki "Item model definition" page for the complete table.)