# Minecraft Model > Minecraft Model 模型格式：Model Categories 模型类别（Baked model 烘焙模型 几何固定、Dynamic model 动态模型 几何可变；Block model 方块模型、Item model 物品模型、Entity model 实体模型）、Baked Models 烘焙模型文件（assets//models/、JSON parent/ambientocclusion/textures/elements/display/gui_light）、Model Inheritance 模型继承（子模型缺少字段使用父值、display模式继承、textures合并解析、循环继承检测和中断、缺失父模型重定向）、Texture Variables 纹理变量（命名变量代替直接路径、#前缀引用其他变量、缺失→缺失纹理）、Elements 元素（矩形长方体 from/to 端点、rotation 旋转 origin/rescale/axis/angle、shade 着色、light_emission 自发光 0-15、faces 面 texture/uv/rotation/tintindex/cullface）、Display Transforms 显示变换（thirdperson_lefthand/righthand、firstperson_lefthand/righthand、head、gui、ground、fixed、on_shelf；scale/rotation/translation 应用顺序 scale→rotation→translation）、Invalid Model 无效模型 builtin/missing 缺失纹理）、Blockstate Dispatch 方块状态分派（assets//blockstates/、variants 直接映射 prop=value 键、multipart 组合 when条件 AND/OR 属性组）、Candidate Models 候选模型（model/uvlock/x/y/z/weight 选择权重）、Face Culling 面剔除（cullface 方向 occlusion shape 覆盖判断）、Block Particle Texture Variable 方块粒子纹理变量（particl - Skill: `zmjjkk123-hub/minecraft-model` (Agent Skill) - Install (CLI): `npx skillmds@latest add zmjjkk123-hub/minecraft-model` - Raw SKILL.md: https://api.skillmd.com/api/skills/zmjjkk123-hub/minecraft-model/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: ZMJJKK123-hub (https://skillmd.com/u/zmjjkk123-hub) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/zmjjkk123-hub/minecraft-model --- # Model (Java Edition) Models define the geometry of objects in the game world. This page covers Java Edition; Bedrock models are part of Add-Ons. ## Model Categories By rendering behavior: - **Baked model** — geometry is fixed once created. Controls most blocks and items; geometry and texture bindings can be modified via resource packs. - **Dynamic model** — geometry can change with environment/state. Controls some block entities and all entities; geometry is hardcoded in game logic (not resource-pack-editable), but textures can be replaced. By purpose: - **Block model** — renders blocks, some block entities, and parts of block entities. - **Item model** — renders items in inventories and in mob hands. - **Entity model** — renders all entities and some block entities. Relationship: all entity models are dynamic (possibly with baked parts — only textures modifiable); item models are a special case of block models, and most block models are baked. ## Baked Models Baked model files live under `assets//models/` with this basic JSON structure: - `parent` — namespace ID of the parent model (see Inheritance). - `ambientocclusion` (default `true`) — whether to use ambient occlusion ("smooth lighting"). - `textures` — texture variables (see Texture Variables). Block models must use textures from the `blocks` atlas; item models may use `blocks` or `items` atlas, but a single item model cannot mix atlases. - `` — direct texture variable, or with options: `sprite` (required, same atlas rules), `force_translucent` (default `false` — force translucent rendering for all elements using this texture). - `elements` — model elements (see Elements). - `display` — render transforms per display mode (default: no transform for all modes). - `gui_light` (default `side`) — lighting direction in GUI rendering (see Display Transforms). ### Model Inheritance - A child model missing `ambientocclusion`, `elements`, or `gui_light` uses the parent's value. - A child model missing a specific `display` mode uses the parent's transform for that mode. - `textures` of child and parent are merged and resolved together. - A model with no parent is a **root model**; missing data uses defaults or stays empty. - Cyclic inheritance is detected and broken: the last model in the chain is re-parented to the invalid model, with the warning `Found 'parent' loop while loading model '' in chain: ...`. - A missing parent also re-parents to the invalid model, with `No parent '' while loading model ''`. ### Texture Variables Instead of direct texture paths, models define named texture variables in `textures` to reduce texture loading. A child variable with the same name overrides the parent's. - A variable maps to a namespace path, e.g. `"top": "block/cake_top"` → file `assets//textures/.png`, packed into the atlas; missing textures become the missing texture. - A variable can reference another variable with a `#` prefix, e.g. `"particle": "#texture"`. If the referenced variable is not found in the child or any parent, the variable maps to the missing texture. - Cyclic references are invalid (warning `Unable to resolve texture due to reference chain ...`). ### Elements Elements must be rectangular cuboids; each face can have independent texture mapping. Units are "pixels" (1/16 of a block). Block center is `[8, 8, 8]`, grid range `[0, 0, 0]`–`[16, 16, 16]`; elements may be defined within `[-16, -16, -16]`–`[32, 32, 32]` and render outside the block grid (up to the 3×3×3 grid around their block unless rotated). - `from` / `to` (required) — start/end corners `[x, y, z]`. Each component of `from` must be ≤ the corresponding component of `to`: out-of-order corners change texture mapping and face normal direction, causing wrongly culled faces. - `rotation` — element rotation: - `origin` (required) — rotation center (can be anywhere, allowing elements to render outside the 3×3×3 grid). - `rescale` (default `false`) — rescale after rotation to compensate visual shrinking. - Single-axis format: `angle` (degrees) + `axis` (`x`, `y`, or `z`); multi-axis format: `x`/`y`/`z` angles applied in x→y→z order. Rotation follows the right-hand rule. - `shade` (default `true`) — render shading. Standard face shading by final world orientation: north/south faces 80%, east/west 60% brightness; with fixed ambient light (e.g. the End), up/down become 90%; otherwise down 50%, up unchanged. Unshaded elements: all directions 90% with fixed ambient, else full brightness. - `light_emission` (0–15) — emissive light level; combined per-channel with sky/block light by taking the max (error if outside 0–15: `Expected light_emission to be an Integer between (inclusive) 0 and 15`). - `faces` (required) — faces of the element: `up`, `down`, `north`, `south`, `west`, `east` (by unrotated orientation). Undefined faces are not rendered. Each face: - `texture` (required) — texture variable name with `#` prefix. - `uv` — `[u1, v1, u2, v2]` texture mapping (units: 1/16 of the texture; top-left `[0, 0]`, bottom-right `[16, 16]`). Out-of-range coordinates render wrong atlas regions. Swapping a component pair mirrors the texture. - `rotation` (default 0) — rotate the texture mapping: 0, 90, 180, or 270 (vertex permutation; non-square mappings distort at 90/270). - `tintindex` (default -1) — hardcoded tint index for recoloring; -1 disables tinting. Item models may reference item model tints by index. - `cullface` — occlusion direction for face culling (see Face Culling). ### Display Transforms Display modes: - `thirdperson_lefthand` / `thirdperson_righthand` — item held in mob hands. - `firstperson_lefthand` / `firstperson_righthand` — item in player hands in first person. - `head` — item on a mob head, Snow Golem pumpkin, spyglass in use. - `gui` — item in GUIs. - `ground` — item entities, item projectiles, Eyes of Ender, firework rockets, carried items, Vault contents, ominous item spawner items. - `fixed` — item frames, campfires, suspicious blocks. - `on_shelf` — item on a chiseled bookshelf. If `thirdperson_righthand` is defined but `thirdperson_lefthand` is not, the left-hand transform copies the right-hand one (same for firstperson). Each display mode transform: - `scale` (default `[1, 1, 1]`) — per-axis scale, clamped to -4..4. - `rotation` (default `[0, 0, 0]`) — per-axis rotation in degrees. - `translation` (default `[0, 0, 0]`) — per-axis translation in pixels (1/16 block), clamped to -80..80. Applied in order: scale → rotation → translation, then a world transform from the mode's base position. `gui_light`: `side` = 3D model lighting, `front` = flat item lighting. ### Invalid Model If a model is missing or fails to load, it is replaced by the invalid model `builtin/missing`: a cube whose 6 faces use the missing texture (hardcoded definition available; `textures: { "particle": "missingno", "missingno": "missingno" }`, full-cube element with `cullface` on every face). ## Block Models ### Blockstate Dispatch Blockstate mapping files live under `assets//blockstates/.json`; their namespace ID identifies the bound block. Every block needs a mapping (even without properties); missing mappings render the invalid model. Two modes — `variants` (direct) or `multipart` (combination); at least one required (warning `Neither 'variants' nor 'multipart' found`). If both are given, `variants` wins; unmatched states fall through to `multipart`. #### Variants (direct state mapping) `variants` maps blockstate keys to candidate models: - Property groups joined with `,`: `prop=value`. Both must be valid for the block, or the whole key is invalid (warnings `Unknown blockstate property: ...` / `Unknown value: ... for blockstate property: ...`). - A block without properties uses the empty string `""` as its key. - Keys need not cover all properties; matching is partial. Mapping is checked in file order; a state already mapped produces an error (`Overlapping definition on state: ...`) and stops processing of the variants section. If no key matches, the game tries the next resource pack's blockstate file. Example keys (redstone wire): `"power=0,east=none,west=none,north=none,south=none"`, `"east=none"`, `"power=0,west=up"`, `"power=15"`, `""`. #### Multipart (model combination) `multipart` is a list of parts: `{ "when": , "apply": }`. `when` conditions, one of: - `AND` — all sub-conditions must pass (must be an array). - `OR` — any sub-condition passes (must be an array). - Plain property groups — each `"prop": "value|value2|..."` pair must pass; `!` prefix negates the list; invalid values warn; an empty list warns. - No elements in the selector warns `No elements found in selector`. - Absent `when` — the part applies to all states. Example: `{ "AND": [ { "OR": [ { "power": "0|1|2|3", "north": "!none" }, { "power": "!12|13|14|15", "west": "side" } ] }, { "east": "side" } ] }`. A state matching no part has **no model** — nothing renders (unlike the invalid model, which still renders the missing cube), and later resource packs are not consulted. #### Candidate Models Each matched variant/part selects from candidate models — either one object or a weighted list: - `model` (required) — model file namespace ID → `assets//models/.json` (usually under `block/`). - `uvlock` (default `false`) — keep texture rotation locked. - `x`, `y`, `z` (default 0) — rotation around the respective axis, must be multiples of 90. - `weight` (default 1, >0) — selection weight (list form only). Probability = weight / total weight; selection is deterministic per block position. Rotation happens clockwise around Y then X at the block center `[8, 8, 8]`, keeping texture mappings fixed (vertices rotate). With `uvlock`, texture bindings are re-computed (rotated in texture space around `[8, 8]`) so the displayed texture does not rotate with the model. #### Item Frame Mapping Item frames use two fake blocks, `item_frame` and `glow_item_frame`, with a fake boolean property `map` (`false` = no map, `true` = map), so their frame model is overridable via `assets/minecraft/blockstates/item_frame.json`. ### Face Culling Faces without `cullface` are never culled (inner faces such as stairs' step faces; interior faces of composters and cauldrons that prevent see-through). A face with `cullface` (one of `up`/`down`/`north`/`south`/`west`/`east`) is not rendered when the occlusion shape of the neighbor in that direction fully covers the block's own shape in that direction. Culling depends only on `cullface` and the occlusion shapes — not on the face's actual position. ### Block Particle Texture Variable The special `particle` texture variable (usable normally too; missing → missing texture) is used for: `block`, `block_marker`, and `dust_pillar` particles; the screen overlay of view-blocking blocks; the Nether portal overlay and dimension-loading screen (nether portal block, north/south state); and still water/lava. ### Block Tinting Blocks with hardcoded tint (tintindex -1 disables; other indices share the same mode): - Grass, tall grass, large fern, fern, potted fern, bush, sugar cane, vines, grass block, oak/dark oak/jungle/acacia/mangrove/birch/spruce leaves, dead bush — biome foliage color. - Pink petal block, wildflowers (index 0 also disabled) — biome foliage color. - Water, bubble column, water cauldron — biome water color. - Redstone wire — colored by `power` n: n=0 → `#4C0000`; else RGB `(⌊10.2n+102⌋, ⌊clamp(357n²−573/75450, 0, 255)⌋, ⌊clamp(102n²−267/75150, 0, 255)⌋)`. - Melon stem, pumpkin stem — by `age` n: `(32n, 255−8n, 4n)`; attached stems fixed `#E0C71C`. - Lily pad — fixed `#208030`. ## Item Models Item models are baked models like block models, but item stacks carry more data, so item model mappings live in `assets//items/.json` under the `model` key. Every item needs a mapping; otherwise the item renders the invalid model. ### Defining Item Models - **Inheriting a block model** — e.g. `{ "parent": "block/grass_block" }`; the block model's transforms carry over, and the game computes the 2D projection for GUI rendering. Child models may override parent data (e.g. `elements`). Vanilla block items pass the block model itself (not a wrapper) when no item model is defined. - **Built-in generation** — the root model `builtin/generated` generates a flat item model from texture layers (equivalent baked form: `textures: { "particle": "#layer0" }`, `gui_light: "front"`). Layers `layer0`–`layer4` (at most 5); `layer0` is required. Layers are read in order — a gap stops further layers (`layer0`, `layer1`, `layer4` uses only the first two). Each layer has a tint index matching its number. Most vanilla item models inherit `item/generated`, which inherits `builtin/generated` and adds the needed display transforms. ### Item Particle Texture Variable The `particle` variable works as for blocks (inherited from a block parent if any) and is used by particles `item`, `item_slime` (slime ball), `item_cobweb` (cobweb), `item_snowball` (snowball). ## Dynamic Models Geometry is not resource-pack-modifiable. Structure: cube elements (belonging to a model part, texture binding origin, cuboid range relative to part origin, scale factor, mirror flag, rendered faces) grouped into **model parts**, organized as a tree; parent part transforms propagate to children (e.g. enchantment table book rotates while its pages flip). Entirely dynamic-model block entities: Conduit (animation), Banner (patterns), Chest/Trapped Chest/Ender Chest/Shulker Box (open animation), Decorated Pot, Sign (text), Moving Piston, Mob Head, End Gateway/End Portal (special shaders). Mixed (baked part + dynamic animations): Bell, Beacon (beam), Suspicious Gravel/Sand (brushed item), Campfire/Soul Campfire (cooking item), Enchanting Table/Lectern (book), Spawner/Trial Spawner (inner entity), Vault (item). Fluid blocks use dynamic models entirely; fluid height is computed from surroundings. ## History Before 24w45a, item tinting was hardcoded by item ID (examples: short/tall grass, ferns, vines, grass block `#7CBD6B`; oak/dark oak/jungle/acacia leaves `#48B518`; mangrove `#92C648`; birch `#80A755`; spruce `#619961`; lily pad `#71C35C`; leather armor dye (index ≤0 or <−1); wolf armor index 1; firework star index 1; potions/splash/lingering/tipped arrows; spawn eggs (0 = base, others = highlight); map tint). See the Minecraft Wiki "Model" page for the full historical table.