custom items

Configurable custom items

Simple custom items can be declared under custom-items in a data-pack config.yml or configs/*.yml without writing a feature class. Keeping the definition beside its texture makes the pack portable. Definitions in the plugin's main config.yml are also supported for items without pack assets. Each item is registered with the Item API and can be created by other plugins with api.items().createCustomItem("fried-egg").

Features and plugins can register a CustomItemPropertyHandler to support parameterised identifiers such as stemcraft:animal_crate[animal=chicken]. The same identifier works through ItemService#createCustomItem and /give.

custom-items:
  fried-egg:
    material: DRIED_KELP
    name: "<gold>Fried Egg"
    texture: "item/fried_egg"
    lore:
      - "<gray>Warm and crispy"
    placement: DENY       # DENY or VANILLA
    max-stack-size: 64    # optional
    max-damage: 256       # optional durability for a tool; use max-stack-size: 1
    glint: false          # optional
    food:                 # optional
      nutrition: 3
      saturation: 2.4
      always-edible: false
      heal: 0.0           # health points restored after consumption
      damage: 0.0         # damage applied after consumption
      returns: BOWL       # optional vanilla/custom item returned afterward
      effects:            # optional status effects
        - type: HASTE
          duration-seconds: 75
          amplifier: 0
          probability: 1.0

The material controls the server-side behaviour. For food, choose an edible base material and override its food values. placement: DENY prevents a block-based item from being placed. Names and lore support MiniMessage formatting. max-damage gives an item a durability bar and lets code damage it with ItemStack#damage; durable items should have a maximum stack size of one.

The pack directory name supplies the namespace (stemcraft-survival becomes stemcraft_survival). The item ID and single texture value derive the Java item/model definitions, Bedrock identifier and icon, and a stable auto-assigned custom-model-data value. name is reused as Bedrock's plain display name. The texture above resolves to contents/stemcraft_survival/textures/item/fried_egg.png, is included in the generated Java pack, and is copied into the generated Bedrock pack.

Items can define internal visual states without creating another player-facing item:

    visual-states:
      excited:
        texture: "item/slime_bucket_excited"

Apply a state with ItemService#applyCustomItemVisualState(item, "excited"); pass null to restore the normal visual. State changes preserve the item's logical ID and all unrelated item metadata. Each state receives equivalent generated Java and Bedrock/Geyser definitions.

Unusual items can override only the derived values they need:

    overrides:
      java:
        custom-model-data: 46003
        item-model: "another_namespace:special_item"
        model: "another_namespace:item/special_item"
      bedrock:
        identifier: "another_namespace:special_item"
        icon: "special_item"
        display-name: "Special Item"

Recipe results

Every configurable shaped, shapeless, cooking, or smithing-transform recipe can return a configured item using the same public namespaced ID accepted by /give. Recipes may be placed beside custom-items in the same data-pack configuration:

recipes:
  furnace:
    fried_egg:
      input: EGG
      result: "stemcraft:fried_egg"
      amount: 1
      exp: 0.1
      time: 200

Material results such as result: COOKED_COD continue to work unchanged.

Recipe ingredients may also use custom item identifiers. They are registered as exact choices, so the backing vanilla material cannot substitute for the configured ingredient. Brewing recipes and persistent crops/forage tables are documented in agriculture-and-cooking.md.

Giving configured items

STEMCraft registers the bare /give command so its command tree includes configured items as well as all vanilla materials. When the item argument resolves to a configured item, selectors and counts work normally:

/give @s stemcraft:fried_egg
/give James stemcraft:fried_egg 16

The namespace is accepted as a convenient command form; underscores in the path resolve to hyphens in the configured ID. Vanilla item requests are delegated to minecraft:give, retaining Minecraft's item-component syntax and behaviour. Item components after the count remain a vanilla-only facility.

When a registered campfire recipe accepts EGG, STEMCraft automatically inserts the egg into an empty campfire slot instead of allowing its normal throwing interaction. No custom-item flag is required; removing the campfire recipe removes the override.