Custom food

In this guide you will make a Ruby Apple: a snack that fills a good chunk of the hunger bar, can be eaten even when you are full, and gives a short burst of speed. You will learn how hunger and saturation work and how long eating takes.

This guide builds on Your first custom item. If you have not made an item yet, start there: the icon, texture and name steps are exactly the same.

The quick way: GodCraft

GodCraft has a Food object with sliders for everything below, and it writes the effect script for you.

1. Open the Workshop and add a Food to your add-on.
2. Draw the icon in the pixel editor.
3. Set the hunger points, saturation and any effects you want.
4. Tap Export and eat it in game.

Want to see the files it makes? Here they are.

By hand

We use the namespace myname. Replace it with your own everywhere.

Step 1: the food item

Create this file in your behavior pack:

{
  "format_version": "1.26.30",
  "minecraft:item": {
    "description": {
      "identifier": "myname:ruby_apple",
      "menu_category": {
        "category": "items"
      }
    },
    "components": {
      "minecraft:icon": {
        "textures": {
          "default": "myname_ruby_apple"
        }
      },
      "minecraft:display_name": {
        "value": "item.myname:ruby_apple.name"
      },
      "minecraft:max_stack_size": 16,
      "minecraft:food": {
        "nutrition": 6,
        "saturation_modifier": 0.8,
        "can_always_eat": true
      },
      "minecraft:use_modifiers": {
        "use_duration": 1.6,
        "movement_modifier": 0.35
      },
      "minecraft:use_animation": "eat",
      "minecraft:tags": {
        "tags": ["minecraft:is_food"]
      }
    }
  }
}

The new parts are the last four components. Let's look at each one.

The food component

minecraft:food makes the item edible.

• nutrition is how many hunger points it restores. One drumstick on the hunger bar is 2 points, so 6 fills three drumsticks. A vanilla apple gives 4, a steak gives 8.
• saturation_modifier controls the hidden "fullness" that keeps your hunger bar from dropping. The game adds nutrition x saturation_modifier x 2 saturation. Low values (around 0.1 to 0.3) feel like a snack, 0.6 is normal, and 0.8 or more is a filling meal.
• can_always_eat lets players eat it even with a full hunger bar. Leave it out (it defaults to false) for normal food.

There is one more field you might like: using_converts_to. It gives the player another item after eating, like a bowl after soup:

"using_converts_to": "minecraft:bowl"

How long eating takes

Food needs minecraft:use_modifiers, or the player cannot hold the use button to eat it.

• use_duration is the eating time in seconds. Vanilla food takes 1.6 seconds. Dried kelp takes about half of that.
• movement_modifier slows the player down while eating. 0.35 is the vanilla value, and 1 means no slowdown at all.

Animation and tags

• minecraft:use_animation set to "eat" shows the chewing animation and crumb particles. Use "drink" for something like a potion or a smoothie.
• minecraft:tags with minecraft:is_food marks it as food, the same way vanilla foods are marked.

Step 2: texture and name

These work just like in the first guide. Add the texture to your existing item_texture.json (inside texture_data, next to your other entries):

"myname_ruby_apple": {
  "textures": "textures/items/ruby_apple"
}

Save a 16x16 PNG at RP/textures/items/ruby_apple.png, then add the name:

item.myname:ruby_apple.name=Ruby Apple

Now /give @s myname:ruby_apple and take a bite. See /give if you need a refresher.

Adding effects when eaten

Old add-ons gave food effects with an effects list inside minecraft:food. That field is not part of the current item format any more. If you add it to a file with a modern format_version, the game ignores it and shows a warning in the Content Log.

Today the way to do it is a custom component: your item names a component you invent, and a small script decides what it does. It sounds scary, but it is about 15 lines.

Step 1: add the component to the item

Add this to the components of ruby_apple.json. The name is yours to choose, and the object holds your own settings:

"myname:eat_effect": {
  "effect": "speed",
  "seconds": 10,
  "amplifier": 1
}

Step 2: write the script

Your behavior pack needs a script module in its manifest for this. Project setup explains how to add one. Then create the script:

import { system } from "@minecraft/server";

system.beforeEvents.startup.subscribe(({ itemComponentRegistry }) => {
  itemComponentRegistry.registerCustomComponent("myname:eat_effect", {
    onConsume(event, { params }) {
      event.source.addEffect(params.effect, params.seconds * 20, {
        amplifier: params.amplifier,
      });
    },
  });
});

How it works:

1. When the world starts, the script tells the game what myname:eat_effect means.
2. onConsume runs each time a player finishes eating an item that has the component.
3. params is the object you wrote in the item file, so you can reuse this one script for many foods with different effects.
4. Effect durations in scripts are in ticks, and there are 20 ticks in a second. That is why seconds is multiplied by 20.
5. amplifier 0 is level I, 1 is level II, and so on.

GodCraft does this whole part for you: pick effects in the Food editor and it adds the component and the script when you export.

Tips for balanced food

• Match vanilla. A snack is 2 to 4 nutrition, a meal is 6 to 8. Very high numbers make every other food pointless.
• Effects should cost something. A powerful effect is fun on a rare food, not on one you can craft from dirt. Tie it to a hard recipe (see Crafting and furnace recipes).
• Keep can_always_eat special. Vanilla only uses it for things like golden apples, so it feels like a reward.
• Stack size matters. Lower stacks (16) make strong food harder to hoard.

When something goes wrong

More help is in Troubleshooting. Next up: Weapons and tools.