Skip to content

Animal Interaction Format

Jump to bottom
BONNe edited this page Mar 13, 2026 · 2 revisions

Custom Animal Interactions Guide

Overview

This guide explains how to create custom data-driven animal interactions for your Minecraft mod. Interactions are defined using JSON files that specify what items trigger interactions, what conditions must be met, what rewards are given, and much more.

Table of Contents

  1. [Basic Structure](#basic-structure)
  2. [Required Fields](#required-fields)
  3. [Optional Fields](#optional-fields)
  4. [Conditions](#conditions)
  5. [Cooldown Types](#cooldown-types)
  6. [Loot Configuration](#loot-configuration)
  7. [Functions](#functions)
  8. [Text Entries](#text-entries)
  9. [Complete Examples](#complete-examples)

Basic Structure

An animal interaction is defined in JSON format with the following basic structure:

{
  "id": <name>,
  "items": [ ... ],
  "conditions": [ ... ],
  "even_entity_count": <true|false>,
  "consumer": { ... },
  "loot": { ... },
  "cooldown": { ... },
  "text_lines": [ ... ],
  "run_functions": [ ... ],
  "finish_functions": [ ... ],
  "sound": <sound_file>,
  "redstone_signal": [0-3]
}

Required Fields

id (string)

A unique identifier for this interaction. Used internally to track cooldowns.

Example:

"id": "feeding"

items (CustomIngredient)

Defines what items can trigger this interaction. If omitted, defaults to an empty ingredient (no items). You can define as many items as you want. It also supports item tags (adding "#" at the front).

Example:

"items": [
  "minecraft:wheat",
  "#minecraft:fishes"
]

Optional Fields

even_entity_count (boolean)

When set to true, the interaction will only work on an even number of entities. If there's an odd number, one entity will be excluded from the interaction.

Default: false

Example:

"even_entity_count": true

consumer (ConsumerEntry)

Defines how items are consumed during the interaction. There are four consumer types available.

Default: Interact mode (item is not consumed)

See the Consumer Types section for detailed information about each type.

redstone_signal (integer)

The bit index of the redstone signal affected by this interaction. As Minecraft supports redstone signals up to 16, you can only define values from 0 to 3.

Default: 0

Example:

"redstone_signal": 1

sound (ResourceLocation)

A sound effect to play when the interaction is performed.

Example:

"sound": "minecraft:entity.cow.ambient"

Consumer Types

Consumer types determine how items are handled when an interaction is performed. There are four types available:

1. Interact

The item is not consumed or damaged - it's just used to trigger the interaction.

"consumer": {
  "type": "interact"
}

Use case: Tools that shouldn't be consumed (like a bucket or bowl)

2. Damage

The item takes durability damage but is not consumed.

"consumer": {
  "type": "damage",
  "damage": 1
}

Fields:

  • damage (integer): Amount of durability damage to apply

Use case: Shears, tools, or any item that should degrade with use

Example:

"consumer": {
  "type": "damage",
  "damage": 5
}

Item takes 5 durability damage per interaction

3. Consume

The item is consumed (removed from inventory).

"consumer": {
  "type": "consume",
  "limit_to_stack": true
}

Fields:

  • limit_to_stack (boolean):
    • true: Only consume items from the held stack
    • false: Consume items from entire inventory if needed

Use case: Food items

Example - Limited to Hand:

"consumer": {
  "type": "consume",
  "limit_to_stack": true
}

Only uses items from the stack in hand. If you have 6 wheat in hand and 20 animals, only 6 animals will be fed.

Example - Full Inventory:

"consumer": {
  "type": "consume",
  "limit_to_stack": false
}

Searches entire inventory for items. If you have 5 wheat in hand and 15 in inventory with 20 animals, all 20 animals will be fed. This option is needed for non-stacked items, like a bucket of fish to feed axolotl.

4. Replace

The item is replaced with the first loot item generated. Remaining loot items are dropped.

"consumer": {
  "type": "replace"
}

Use case: Buckets (empty bucket → milk bucket), bottles (empty bottle → honey bottle), containers

How it works:

  1. If loot is generated, the first item replaces the held item
  2. Any additional loot items are dropped on the ground
  3. If no loot is generated, the item is consumed like normal

Example - Milking with Bucket:

{
  "id": "milk_cow",
  "items": {
    "item": "minecraft:bucket"
  },
  "consumer": {
    "type": "replace"
  },
  "loot": {
    "id": "mymod:milk_bucket_loot",
    "drop_limit": 1,
    "per_entity": false
  }
}

Empty bucket in hand is replaced with milk bucket (first loot item)

Consumer Type Comparison

Type Item Consumed? Item Damaged? Uses Inventory? Replaces Item?
Interact ❌ No ❌ No ❌ No ❌ No
Damage ❌ No ✅ Yes ❌ No ❌ No
Consume ✅ Yes ❌ No ⚙️ Configurable ❌ No
Replace ✅ Yes (if no loot) ❌ No ❌ No ✅ Yes (with loot)

Conditions

Conditions determine when an interaction can be performed. All conditions must be satisfied for the interaction to trigger.

Condition Types

1. Amount Condition

Checks the number of animals in the pen.

{
  "type": "amount",
  "operator": ">=",
  "value": 2
}

2. Mob Condition

Checks NBT data directly on the mob entity.

{
  "type": "mob",
  "key": "Type",
  "operator": "match",
  "value": "brown"
}

3. Properties Condition

Checks custom data stored in the animal pen's data storage.

{
  "type": "data",
  "key": "last_feeding_increment",
  "operator": ">",
  "value": 2
}

Available Operators

  • = - Equal to
  • != - Not equal to
  • < - Less than
  • <= - Less than or equal to
  • > - Greater than
  • >= - Greater than or equal to
  • has - Check if key exists (use with mob conditions)
  • match - Check if key value matches entity/properties value.

Example with Multiple Conditions

"conditions": [
{
  "key": "EffectId",
  "operator": "has",
  "value": true,
  "type": "mob"
},
{
  "key": "Type",
  "operator": "match",
  "value": "brown",
  "type": "mob"
}
]

Cooldown Types

Cooldowns prevent interactions from being used too frequently. There are three types:

1. Static Cooldown

A fixed cooldown regardless of animal count.

"cooldown": {
  "type": "static",
  "base": 6000
}

Cooldown: 6000 ticks (5 minutes) always

2. Linear Cooldown

Cooldown scales with the number of animals.

"cooldown": {
  "type": "linear",
  "base": 1200,
  "delta": -100,
  "limit": 200
}

Starts at 1200 ticks, decreases by 100 per animal, minimum 200 ticks

  • Positive delta: Cooldown increases with more animals (use limit as maximum)
  • Negative delta: Cooldown decreases with more animals (use limit as minimum)

3. Randomized Cooldown

Random cooldown between min and max values.

"cooldown": {
  "type": "random",
  "min": 1200,
  "max": 2400
}

Random cooldown between 1200-2400 ticks (1-2 minutes)

Loot Configuration

The loot system determines what items are generated when the interaction is performed.

"loot": {
  "id": "animal_pen:animal_interactions/shear/wool",
  "drop_limit": 320,
  "per_entity": true
}

Fields

  • id (ResourceLocation): The loot table to use. It should be a GIFT type loot table
  • drop_limit (integer): Maximum number of items to drop
  • per_entity (boolean):
    • true: Roll loot table once per animal
    • false: Roll loot table once per interaction item

Example: Wool from Sheep

"loot": {
  "id": "animal_pen:animal_interactions/shear/wool",
  "drop_limit": 320,
  "per_entity": true
}

Functions

Functions are executed when the interaction occurs. They can modify mob data, trigger effects, and more. Functions are Registry-based, and mods can introduce their own functions to run.

Run Functions

Executed immediately when interaction is triggered.

"run_functions": [
  {
     "id": "animal_pen:feeding"
  },
  {
     "id": "animal_pen:increment_key",
     "key": "pollen_level",
     "value": -5
  }
]

Finish Functions

Executed after the cooldown completes.

"finish_functions": [
  {
     "id": "animal_pen:increment_key",
     "key": "pollen_level"
  }
]

Function Types

Functions vary based on your implementation. Common patterns include:

  • Setting NBT values
  • Incrementing counters
  • Triggering effects
  • Modifying mob properties

Functions are separated in 3 different types: Player, Dispenser and Trigger.

By default, there are implemented 10 functions:

  • "animal_pen:feeding" - increases mob count on interaction. Can be triggered by player or dispenser
  • "animal_pen:duplicate" - duplicates mob count on interaction. Can be triggered by player or dispenser
  • "animal_pen:mob_set_sheared" - changes mob sheared status [requires code implementation]. Can be triggered by all 3
  • "animal_pen:sheep_change_color" - changes sheep wool color. Can be triggered by player or dispenser
  • "animal_pen:mooshroom_set_effect" - applies effect to mooshroom. Can be triggered by player
  • "animal_pen:mooshroom_failed_effect" - fails to apply effect to mooshroom. Can be triggered by player
  • "animal_pen:mooshroom_remove_effect" - removes effect from mooshroom. Can be triggered by player or dispenser
  • "animal_pen:water_bucket_pickup" - Triggers bucketable entity pickup into the bucket. Can be triggered by player
  • "animal_pen:increment_key" - Increments certain data key by specified amount. Can be triggered by all 3
  • "animal_pen:turtle_drop_scute" - Drops turtle scutes based on how many animals were fed. Can be triggered by all 3

Text Entries

Text entries provide visual feedback to players about the interaction status.

"text_lines": [
  {
    "short_text": "display.animal_pen.ready",
    "long_text": "interaction.mymod.feed_animals",
    "main_item": [
      "minecraft:wheat"
    ],
    "result_item": [
      "minecraft:egg"
    ],
    "visibility": "READY",
    "parameters": []
  }
]

Fields

  • short_text: Translation key for short display (above block)
  • long_text: Translation key for extended menu
  • main_item: Icon displayed in slot 1 (defaults to interaction item)
  • result_item: Icon displayed in slot 2
  • visibility: When to show this text entry
    • READY - Interaction is ready (green)
    • COOLDOWN - Interaction is on cooldown (white)
    • NOT_MATCH - Conditions not met (gold)
    • ON_MATCH - Conditions are met (gold)
  • parameters: Additional values to display (see below)

Parameters

Parameters are placeholders in your translation strings that get replaced with dynamic values.

"parameters": ["[cooldown]", [pollen_level], "Static Text"]
  • [cooldown] - Displays remaining cooldown time (MM:SS format)
  • [your_key] - Displays value from animal data storage with key "your_key"
  • Plain text - Displayed as-is

Translation Example:

"display.animal_pen.food_cooldown": "%1$s §eFeeding in %3$s"

Note: %1$s and %2$s are reserved for main_item and result_item icons

Complete Examples

Example 1: Simple Feeding Interaction

{
      "id": "feeding",
      "items": [
        "minecraft:wheat_seeds",
        "minecraft:melon_seeds",
        "minecraft:pumpkin_seeds",
        "minecraft:beetroot_seeds"
      ],
      "conditions": [
        {
          "operator": ">=",
          "value": 2,
          "type": "amount"
        }
      ],
      "even_entity_count": true,
      "consumer": {
        "limit_to_stack": true,
        "type": "consume"
      },
      "cooldown": {
        "base": 1160,
        "delta": 20,
        "limit": 6000,
        "type": "linear"
      },
      "text_lines": [
        {
          "result_item": [
            "minecraft:wheat_seeds",
            "minecraft:melon_seeds",
            "minecraft:pumpkin_seeds",
            "minecraft:beetroot_seeds"
          ],
          "visibility": "ready",
          "short_text": "display.animal_pen.ready",
          "long_text": "display.animal_pen.food_ready"
        },
        {
          "result_item": [
            "minecraft:wheat_seeds",
            "minecraft:melon_seeds",
            "minecraft:pumpkin_seeds",
            "minecraft:beetroot_seeds"
          ],
          "visibility": "cooldown",
          "parameters": [
            "[cooldown]"
          ],
          "short_text": "display.animal_pen.cooldown",
          "long_text": "display.animal_pen.food_cooldown"
        },
        {
          "result_item": [
            "minecraft:wheat_seeds",
            "minecraft:melon_seeds",
            "minecraft:pumpkin_seeds",
            "minecraft:beetroot_seeds"
          ],
          "visibility": "not_match",
          "parameters": [
            "2"
          ],
          "long_text": "display.animal_pen.requires_food"
        }
      ],
      "run_functions": [
        {
          "id": "animal_pen:feeding"
        }
      ],
      "redstone_signal": 1
    }

Example 2: Random function that is constantly running in background

    {
      "sound": "minecraft:entity.chicken.ambient",
      "cooldown": {
        "min": 1200,
        "max": 6000,
        "type": "random"
      },
      "id": "ambient"
    }

Example 3: Shearing a white sheep

{
      "id": "shearing",
      "items": [
        "minecraft:shears",
        "#forge:shears",
        "#c:shears"
      ],
      "conditions": [
        {
          "key": "Color",
          "operator": "=",
          "value": 0,
          "type": "mob"
        }
      ],
      "consumer": {
        "damage": 1,
        "type": "damage"
      },
      "loot": {
        "id": "animal_pen:animal_interactions/shear/wool",
        "drop_limit": 320,
        "per_entity": true
      },
      "run_functions": [
        {
          "id": "animal_pen:sheep_set_sheared",
          "value": true
        }
      ],
      "finish_functions": [
        {
          "id": "animal_pen:sheep_set_sheared",
          "value": false
        }
      ],
      "cooldown": {
        "base": 1200,
        "type": "static"
      },
      "text_lines": [
        {
          "result_item": [
            "minecraft:white_wool"
          ],
          "visibility": "ready",
          "short_text": "display.animal_pen.ready",
          "long_text": "display.animal_pen.full_ready"
        },
        {
          "result_item": [
            "minecraft:white_wool"
          ],
          "visibility": "cooldown",
          "parameters": [
            "[cooldown]"
          ],
          "short_text": "display.animal_pen.cooldown",
          "long_text": "display.animal_pen.wool_cooldown"
        }
      ],
      "sound": "Minecraft: entity.sheep.shear",
      "redstone_signal": 2
    }

Common Issues

Interaction not triggering?

  • Check that all conditions are met
  • Verify the item ingredient matches what you're using
  • Ensure there's no active cooldown

Cooldown not working?

  • Verify cooldown type and values are correct
  • Check that the interaction ID is unique

Text not displaying?

  • Ensure translation keys exist in your language files
  • Check that visibility matches the current interaction state
  • Verify parameters reference existing data keys

File Location

Place your interaction JSON files in your datapack or mod at:

data/<namespace>/animal_interactions/<filename>.json

Each file can contain multiple interaction definitions:

{
  "entity": "<entity_id>",
  "interactions": [
     ...
   ]
}

Clone this wiki locally