Custom items are one of the fastest ways to make a server feel like its own game. A player who joins and finds a rune-etched blade, a lantern that actually lights a room, and a menu no vanilla client has seen understands instantly that this world was built on purpose. ItemsAdder is the most common route to that result, and the plugin most likely to leave an owner staring at missing textures at midnight.

This guide is a build-along. It goes from a fresh install on Paper to a working custom sword and a placeable lamp, and it treats the resource pack as the hard part instead of an afterthought. Everything below was checked against the current official ItemsAdder wiki for the 4.x layout, because the 3.x tutorials still floating around describe a folder structure that no longer exists. Work through it in order and you skip most of the failures new owners hit.

What ItemsAdder Adds to a Server

ItemsAdder is a content framework with two halves that must stay in sync. The server half is YAML: files under the plugin’s contents folder register new items, blocks, furniture, recipes, and GUI elements. The client half is a generated resource pack supplying the models, textures, and fonts those definitions point at.

That split explains most confusing bugs. A custom sword exists on the server the moment its YAML loads: /iaget hands it out and recipes work. Whether it looks like a sword depends on whether the client has the pack. The server never streams a model; it names a model ID, and the pack decides what that ID looks like.

With a working pack, clients can see:

• Fully 3D item models in hand, in the inventory, and on the ground
• Custom block and furniture models placed in the world
• GUI overlays, HUDs, and font glyphs for menus and chat

This is the same mechanic that makes hand-built packs work, so the concepts carry over to our guide on resource pack basics and distribution. ItemsAdder just automates the packing, hashing, and delivery.

Install and the Resource-Pack Pipeline

Version pairing is the first trap. ItemsAdder 4 targets 1.20.6 and newer; 3.x is for 1.20.4 and older. Run a current Paper build, drop ProtocolLib and ItemsAdder into plugins, start once, and let the first boot write its folders. On 4.0.9 and later you no longer need LoneLibs.

Next, pick hosting before you build anything. Since 4.0.17 the simplest option serves the zip from the game port with no extra forwarding:

hosting:
  simple_self_host:
    enabled: true
    server_address: auto

On panel hosts with extra ports, the classic self-host block still works by pointing server-ip at your address and pack-port at that port. Networks applying one pack from a lobby should use no-host. Serve the file over HTTPS either way: a plain HTTP pack link is the most common cause of “download failed” join errors.

Run /iazip after any texture, model, or config change; it reloads configs and rebuilds the zip. /iasha1 prints the pack hash if you serve it yourself or set resource-pack-sha1 in server.properties. Retest with a client that has never joined, and delete the cached copy in server-resource-packs first.

Feature	Where it lives	Common failure
Item definition	contents/<namespace>/configs/*.yml	info.namespace typo, so the pack never sees the item
Texture	contents/<namespace>/textures/item/*.png	Uppercase letters or spaces in the filename
Model	contents/<namespace>/models/...	Texture path inside the JSON missing the namespace prefix
Block behaviour	behaviours.block.placed_model	Missing block behaviour, so the item places as plain paper
Pack delivery	config.yml hosting section	Self-host enabled but the pack port is closed

Build Your First Custom Item

Stay organized from the first file. Older ItemsAdder 3 builds used data/items_packs; current 4.x uses plugins/ItemsAdder/contents, and each subfolder there is a namespace. The easiest structure lets the plugin infer the namespace, so you only need three folders:

contents/my_items/
  configs/swords.yml
  models/item/ruby_blade.json
  textures/item/ruby_blade.png

One or two namespaces is the right number for a normal server. Ten is how packs become unmaintainable, because every item ID, texture path, and permission carries the prefix. Keep every name lowercase with underscores.

Here is a complete item, minus the recipe and attribute keys, which live in the same entry:

info:
  namespace: my_items
items:
  ruby_blade:
    display_name: "&cRuby Blade"
    permission: my_items.ruby_blade
    lore:
    - "&7Forged in the deep caverns"
    resource:
      material: DIAMOND_SWORD
      generate: false
      model_path: item/ruby_blade

The model_path is the part people get wrong. It resolves relative to the namespace’s models folder, so item/ruby_blade means contents/my_items/models/item/ruby_blade.json. The texture path inside that JSON resolves against the pack root, so it must be written my_items:item/ruby_blade, not item/ruby_blade. Drop the namespace and the model renders as a missing texture even though the file is right there.

Set generate: true and list textures instead if you want a flat item with no Blockbench work. Use /iareload while iterating on YAML, and a full /iazip whenever a model or texture changed.

Custom Blocks, Furniture, and Models

Blocks reuse the item format plus a behaviour. Current 4.x uses a graphics block with a texture path; 4.0.17 and older use resource with generate. The behaviour is what makes an item placeable:

  red_block:
    name: Red Block
    graphics:
      texture: block/red_block.png
    behaviours:
      block:
        drop_when_mined: false
        placed_model:
          type: REAL_NOTE

drop_when_mined: false matters. Leave it on and players farm two blocks from one placement, the classic duplication report on support forums. Define the real drop in loots with a chance and amount range.

Furniture is a sibling behaviour and covers most decorative content. Verified keys are light_level, solid, placeable_on with floor, ceiling, and walls, plus hitbox with height, length, and width. The default hitbox is 1x1x1, so set it only when your model is bigger. Add opposite_direction: true if the model faces the wrong way.

The Blockbench pipeline is short but unforgiving. Create a Java Block/Item model, keep textures on a 16×16 or 32×32 grid, and paint UVs into a single atlas. Set display transforms for third person, first person, GUI, and ground before exporting, because a model that looks perfect in Blockbench often clips through the hand without them. Furniture should sit with its base at Y=0. Export as a block/item model straight into your namespace’s models folder.

Performance, Geyser, and Rollout

Pack size decides whether new players stay. Every model is JSON the client parses, every texture is memory and VRAM, and a first join is a download with a progress bar. Rules that hold up on populated servers:

• Keep textures at 16×16 unless the model genuinely needs more; a 64×64 texture for a pebble is wasted bandwidth.
• Reuse a shared atlas across items in a set instead of one texture per variant.
• Audit the pack monthly and delete unused models; dead content still ships to every player.

Bedrock is the other hard limit. Geyser translates Java items and inventories, but a Java custom model does not appear on Bedrock unless you map it to a Bedrock item with a Bedrock-side pack. Keep gameplay-critical items readable through names and lore, or budget a second pack. Geyser’s custom items docs cover mappings; our resource pack optimization guide covers size.

Rollout should be boring. Test on staging with a clean client, version the zip, bump a visible pack version so caches invalidate, and keep the previous zip on disk so a bad batch reverts in one command. Watch join errors for a day after each update and ask two players on weak connections about download time before you announce anything.

Pros and Cons

• Pros: one config format for items, blocks, furniture, GUIs, and emotes; automatic zip generation and hashing; self-host delivery with no extra services; recipes, loot, and permissions integrated; a large addon ecosystem.
• Cons: the pack is a hard dependency, so a failed download breaks every custom visual; version drift between 3.x and 4.x makes old tutorials useless; the free and paid tiers differ, so check licensing at your scale; Bedrock needs separate work.

A hand-built pack gives full control and zero plugin overhead, but you own packing, hashing, hosting, and every model path. Other model plugins are lighter but usually stop at items. ItemsAdder wins when you want blocks, furniture, and UI in one system; a hand-built pack wins for a handful of static textures.

Common Mistakes

• Editing textures and running only /iareload. Config reloads do not rebuild the zip. Anything visual needs /iazip, and players need a fresh client cache.
• Uppercase or spaced filenames. Docs are explicit about lowercase, and one capital letter produces an invisible item rather than an error.
• Forgetting the namespace prefix inside model JSON. The model loads, the texture does not, and the item shows as a black-and-purple cube.
• Testing only on your own client. Your cache has the old pack. Use a clean profile, or you will ship a broken update and blame the plugin.

If you are modelling wearable or held props, the display transform mistakes are the same ones covered in our Blockbench hat workflow. And if your custom gear feeds a progression system, wire it up the way we describe in custom enchantments and progression rather than inventing a second economy.

Frequently Asked Questions

Wrapping Up

ItemsAdder is not hard because the YAML is complicated. It is hard because two halves have to agree: the definition the server reads and the pack the client downloads. Get hosting right first, keep one namespace, respect the model path rules, and rebuild the zip whenever a pixel changes. Then custom content becomes a routine part of your update process instead of a weekend debugging session.

Start with one sword and one lamp on a staging server this week. Once both render on a clean client, the whole pipeline works and every item after that is just more artwork. Keep the ItemsAdder wiki, the Blockbench docs, and Paper’s server.properties reference open while you build.