Items and armour

How custom items, 3D models, item behaviour, player heads, armour and equipment are converted, what Bedrock players see, and the limits.

On this page

Custom items are the heart of most content plugins. This page explains what NusaPack converts for items, armour and equipment, what Bedrock players see, and what to do when an item needs your help.

What Bedrock players see

  • Every custom item with its own texture or 3D model, in the hand, on the ground and in the inventory.
  • An inventory icon for 3D items.
  • The item's behaviour: they can eat custom food, mine with custom tools at the right speed, and wear custom armour, as on Java.
  • Player heads with their custom skin.
  • Dyed and layered armour in its own colours.

Java players see no difference: NusaPack never changes your source packs or the items on the server.

Item models and icons

NusaPack converts both flat (2D) items and 3D item models. For 3D items it also creates an inventory icon. The icon size follows the icon_size setting:

icon_sizeIcon size
auto (default)Follows the source texture: 16 px becomes 64, 32 px becomes 128, larger becomes 256
32, 64, 128 or 256The same size for every icon

Items worn on the head with a 3D model, such as hats and helmets, sit on the Bedrock player's head using the model's head display settings. The worn model is hidden in first person, as on Java.

Packs often point at vanilla shapes without shipping them, such as block/cross, block/slab, block/stairs, block/cube_column or block/leaves. NusaPack provides that geometry itself. If your pack ships its own version of such a model, yours is used.

Item behaviour

Behaviour is read from the live items on the server, not guessed from the pack:

PropertyOn Bedrock
Food and other consumablesPlayers can eat or use them
ToolMines at the Java mining speed
Use cooldownThe same cooldown
DurabilityThe same durability
Stack sizeThe same maximum stack
Enchantability and glintEnchantable as on Java; the glint shows when set
Equippable slotCan be worn in the right slot

Geyser builds item behaviour once, when it starts. Changing an item's behaviour therefore needs one server restart after the conversion.

Player heads

Player heads with a custom skin show that skin on Bedrock. Changing a head's skin needs one restart after the conversion.

Armour and equipment

Dyed and layered armour shows its own colour. Re-dyeing it in game does not change its Bedrock look.

For Nexo equipment, each Java equipment layer is matched to the Bedrock model of the same kind:

Java layerOn Bedrock
humanoid, humanoid_leggingsNormal armour pieces, replacing the vanilla armour layer
wingsElytra-style wings, with the normal gliding, sneaking, sleeping and swimming poses
horse_bodyHorse armour, only on the horses it is made for
llama_bodyLlama armour, also when the item's base material is PAPER
wolf_bodyWolf armour; the Java texture is padded to fit, never stretched

Each equipment family uses one fixed texture layer. Equipment from a pack in plugins/Nexo/pack/external_packs/ only converts when Nexo imports external packs, as described in Supported content.

Special cases

  • Invisible items. An item whose Java model is minecraft:empty stays invisible on Bedrock, with a transparent icon.
  • Fishing rods. A custom fishing rod that looks different while cast (the cast predicate or the fishing_rod/cast condition) gets that look on Bedrock too: Geyser switches to it while the bobber is out. A new fishing rod needs one restart, like every new custom item.
  • Animated textures. They move on Bedrock as well. To keep them still for a smaller pack, use texture_motion in Settings, or list single textures in still-textures.yml as shown in Sources and advanced files.

Items waiting for a base material

Sometimes NusaPack cannot decide which Java base material an item should be treated as. Those items wait for your choice:

/npb report items
/npb report items resolve <item-id> <material>

The item ID has the form namespace:item/path, and the material is a Minecraft material name, for example:

/npb report items resolve mypack:item/ruby_sword diamond_sword

Your choice is saved; run /npb convert again afterwards. In the /npb panel, the Waiting items button shows the same list.

When changes show up

ChangeWhat Bedrock players need
A new texture or model for an existing itemA rejoin
A new or removed itemOne server restart
Different behaviour (food, tool, durability, stack size)One server restart
A different player-head skinOne server restart

The last line of /npb convert always tells you which one applies.

Known limits

  • Re-dyeing armour in game does not change its Bedrock look.
  • Armour layers that change while playing, such as dynamic dye or player textures, are reported as problems instead of being converted. So are missing equipment textures and texture sizes Bedrock cannot use.
  • An item whose model points to a model or texture that does not exist is reported as a problem. With conversion_mode: strict this blocks the conversion until you fix it or switch to partial.
  • Items whose model changes with the item's state or colour are not verified to match Java in every variant.

Next steps

Nusa product documentation · NusaPackPaper 1.21.x · Java 21

Loading the index…