Custom Items

Custom Items

GoCraft's cross-edition custom item system: define an item once in YAML, and GoCraft auto-generates a Java resource pack and a Bedrock behavior/resource pack at startup. No manual pack authoring required.

Folder layout

packs/
  mypacks/
    items.yml          ← item definitions
    textures/
      ruby.png         ← 16×16 PNG textures
      ruby_sword.png
  .registry.yml        ← auto-generated; do not edit

Each sub-directory under packs/ is one pack. The location is configurable via custom_items.packs_dir in server.yml.

items.yml format

namespace: mypacks   # unique lowercase identifier, no spaces

items:
  ruby:
    display_name: "<red>Ruby"
    material: paper          # vanilla Java base item (lowercase)
    texture: ruby.png        # filename inside textures/

  ruby_sword:
    display_name: "<gradient:#ff0000:#aa0000>Ruby Sword"
    material: diamond_sword
    texture: ruby_sword.png
    parent: item/handheld    # model parent (default: item/generated)
    hand_equipped: true      # Bedrock: larger item in hand (tool/weapon feel)
    max_stack_size: 1        # default 64

Fields

Field	Required	Description
display_name	Yes	MiniMessage-formatted name. Supports <red>, <gradient:#start:#end>, <bold>, etc.
material	Yes	Vanilla Java base item (e.g. paper, iron_ingot, diamond_sword). Items sharing a material share one model-override file.
texture	Yes	PNG filename inside the pack's textures/ directory.
parent	No	Java model parent. item/generated (flat, default) or item/handheld (tool grip).
hand_equipped	No	Bedrock only — shows the item larger in the hand. Default false.
max_stack_size	No	Maximum stack size. Default 64.

On Bedrock, MiniMessage tags are stripped automatically (Bedrock uses a different text format) — only the plain text is shown there.

server.yml configuration

custom_items:
  enabled: true
  packs_dir: packs          # directory containing pack sub-folders
  java:
    serve_port: 8080        # port the embedded HTTP server binds on
    public_host: ""         # your server's public IP or domain

Pterodactyl note: Open serve_port (default 8080) as an additional TCP port on your egg, and set public_host to your server's public IP/domain. Java clients download the pack from http://<public_host>:8080/<hash>.zip automatically. If resource_pack.java.url is set manually, the custom-items system overrides it with the auto-generated URL.

How it works

Java clients

1. At startup GoCraft reads all packs and assigns a stable CustomModelData (CMD) integer per item (starting at 30100, matching the CustomiZer convention).
2. A resource-pack ZIP is generated in memory:
   • assets/minecraft/models/item/<material>.json — CMD overrides pointing to custom models
   • assets/<namespace>/models/item/<id>.json — the item model (flat or handheld)
   • assets/<namespace>/textures/item/<id>.png — the texture
3. The ZIP is served over HTTP on serve_port; its SHA-1 hash is sent with the URL so clients cache it.
4. Players receive the pack during the configuration phase and see custom visuals for any stack carrying the matching CMD.

Bedrock clients

1. GoCraft generates a .mcaddon in memory containing a resource pack (textures + item_texture.json) and a behavior pack (one items/<ns>/<id>.json per item).
2. The .mcaddon is injected into the Bedrock listener's pack list and pushed at login.
3. Custom identifiers and runtime IDs are registered in the StartGame packet's item table (ComponentBased: true), so Bedrock clients recognise the items without a full vanilla server.

ID stability

CMD values and Bedrock runtime IDs are assigned once and persisted to packs/.registry.yml. They never change between restarts, so items already stored in world saves or player inventories stay valid after updates. Do not edit .registry.yml by hand.

Giving custom items

Use the give commands with the namespaced ID (see Commands), e.g. /give <player> mypacks:ruby_sword.

Limitations

• Textures are 16×16 PNGs referenced by filename.
• Behavior beyond appearance/stack-size (custom durability logic, abilities) is limited — the system focuses on cross-edition item identity and visuals.