AnimalHunger Plugin - Complete Wiki

Introduction

AnimalHunger is a comprehensive Minecraft plugin that transforms passive animals into interactive companions with hunger, leveling, bonding, and resource production systems. Animals require care and feeding, and in return, they provide resources, can be ridden, and develop unique bonds with players.

Key Features

• Hunger System: Animals need regular feeding to survive
• Leveling System: Animals gain levels through feeding and care
• Bond System: Build relationships with animals for better rewards
• Resource Production: Animals produce resources based on bond level
• Riding System: Ride high-level animals with advanced controls
• Feeding Stations: Automated feeding systems for multiple animals
• Animal Homes: Define territories where animals stay (Premium)
• Custom Drops: MMOItems and MythicMobs integration
• Database Storage: MySQL or SQLite support

Installation

Requirements

• Minecraft: 1.18+ (Paper/Spigot)
• ProtocolLib: Required dependency
• Java: 17+

Optional Dependencies

• PlaceholderAPI: For placeholder support
• MMOItems: For custom item drops
• MythicMobs: For custom mob support

Installation Steps

1. Download the plugin from SpigotMC
2. Install ProtocolLib if not already installed
3. Place JAR file in your server's /plugins/ folder
4. Start the server to generate configuration files
5. Configure config.yml and messages.yml to your preferences
6. Restart the server to apply changes

Core Features

1. Hunger System

Animals have a hunger bar that depletes over time. When hunger reaches zero:

• Death Prevention: Can be disabled in config (disable-animal-death-on-starvation: true)
• Bond Loss: Starving animals lose bond levels
• Visual Indicator: Hunger bars display above animals

Configuration:

yaml

disable-hunger-system: false
hunger-decrease-interval: 6000  # 5 minutes in ticks
hunger-restore-amount: 2
max-hunger-cap: 20

2. Leveling System

Animals gain levels by being fed:

• Max Level: Configurable (default: 10)
• Feedings Required: Set per level
• Benefits:Increased max hunger
• Better drop quality
• Unlock riding at level 6
• Enable breeding at level 6

Configuration:

yaml

max-level: 10
feedings-per-level: 3

3. Bond System

Build relationships with animals through care:

Bond Levels:

• 0-24%: Weak Bond (Basic interactions)
• 25-49%: Moderate Bond (Decoration upgrades)
• 50-74%: Strong Bond (Resource production begins)
• 75-99%: Legendary Bond (Rare resource drops)
• 100%: Maximum Bond (Bonus resources)

Bond Gain/Loss:

yaml

bond:
  feeding-bond-gain: 8
  starving-bond-loss: 1
  upgrade-bond-gain: 15
  enable-decay: false  # Optional time-based decay

4. Resource Production

Animals produce resources automatically based on bond level:

Production Tiers:

• Level 1 (Bond ≥50%): 5% chance per check
• Level 2 (Bond ≥75%): 10% chance, rare items unlocked
• Level 3 (Bond ≥100%): 15% chance, bonus amounts

Configuration:

yaml

resource_production:
  production_check_interval: 600  # 30 seconds
  min_bond_to_produce: 50
  rare_resource_bond_threshold: 75
  bonus_resource_bond_threshold: 100

Configuration

Main Config Structure

The config.yml is organized into logical sections:

World Settings

yaml

world-settings:
  mode: "blacklist"  # or "whitelist"
  worlds:
    - "world_nether"
    - "world_the_end"

Storage Settings

yaml

storage:
  type: "mysql"  # or "sqlite"
  mysql:
    host: "localhost"
    port: 3306
    database: "animalhunger"
    username: "user"
    password: "password"

Animal-Specific Settings

Each animal type has its own configuration:

yaml

animals:
  cow:
    display_name: "Cow"
    feed_items: ["WHEAT", "HAY_BLOCK", "GRASS"]
    resource_items: ["LEATHER", "BEEF"]
    riding_speed: 0.12
    rideable: true

Supported Animals:

• Farm: Cow, Sheep, Pig, Chicken, Rabbit
• Equines: Horse, Donkey, Mule, Llama
• Predators: Wolf, Cat, Ocelot, Fox
• Exotic: Panda, Polar Bear, Goat, Strider
• Special: Iron Golem, Snow Golem, Villager

Food Values

Different foods restore different amounts:

yaml

food-values:
  hay_block: 5
  wheat: 1
  golden_carrot: 3
  carrot: 2
  apple: 2

Commands

Main Commands

Command Description Permission
/animalhunger Show plugin info animalhunger.use
/animalhunger reloadReload configurationanimalhunger.reload
/animalhunger debugShow debug info for selected animalanimalhunger.admin
/animalhunger resourcesView resource usage statisticsanimalhunger.admin
/animalhunger dbstatsView database statisticsanimalhunger.admin
/animalhunger dbcleanup [days]Clean old recordsanimalhunger.admin
/animalhunger limitCheck your animal limitanimalhunger.use

Riding Command

Command Description Permission
/sp Sit on nearest rideable animal (level 6+) animalhunger.ride

Animal Home Commands (Premium)

Command Description Permission
/animalhome set <radius> Visualize home zone animalhunger.animalhome.use
/animalhome confirm Apply home zone animalhunger.animalhome.use
/animalhome cancelCancel visualization animalhunger.animalhome.use
/animalhome removeRemove animal's home animalhunger.animalhome.use

Permissions

Player Permissions

yaml

animalhunger.use: true          # Basic plugin usage
animalhunger.feed: true         # Feed animals
animalhunger.kill: true         # Kill animals via GUI
animalhunger.upgrade: true      # Upgrade animals
animalhunger.collect: true      # Collect resources
animalhunger.rename: true       # Rename animals
animalhunger.info: true         # View animal info
animalhunger.ride: true         # Ride animals

Admin Permissions

yaml

animalhunger.admin: op          # Admin notifications & features
animalhunger.reload: op         # Reload plugin
animalhunger.bypass: op         # Bypass hunger mechanics
animalhunger.resources: op      # View resource statistics

Station Permissions

yaml

animalhunger.station.create: true  # Create feeding stations

GUI System

Main Animal GUI

Opening the GUI:

• Sneak + Right-Click on any supported animal

GUI Sizes: The GUI adapts based on animal level/bond:

• Small (27 slots): Basic animals
• Medium (45 slots): Developing animals
• Large (54 slots): Advanced animals

GUI Items

1. Level Display

• Material: Experience Bottle
• Shows: Current level, progress to next level
• Info: Feed count and requirements

2. Hunger Display

• Material: Golden Apple
• Shows: Current/Max hunger
• Info: Hunger status, acceptable foods
• Status Colors:Green (75-100%): Healthy
• Yellow (50-74%): Hungry
• Orange (25-49%): Starving
• Red (0-24%): Critical

3. Bond Display

• Material: Heart of the Sea
• Shows: Bond percentage and effects
• Info: Multipliers, thresholds, benefits

4. Name Display

• Material: Name Tag
• Action: Click to rename animal
• Limits: 20 characters max
• Click: Opens chat prompt for new name

5. Name Color

• Material: Pink Dye
• Action: Opens color selection menu
• Colors Available: 16 color options
• Premium: Gradient support (if enabled)

6. Feed Action

• Material: Wheat (or animal's food)
• Action: Feed using item in hand
• Requirements: Valid food in main hand
• Effects:Restores hunger
• Grants bond XP
• May trigger level up

7. Collect Resources

• Material: Chest
• Action: Collect produced resources
• Requirements: Bond ≥50%, resources available
• Visual: Glows when resources ready

8. Upgrade Action

• Material: Golden Carrot
• Action: Upgrade animal level
• Cost: Configurable items (default: Golden Carrots)
• Effects:+1 Level
• +2 Max Hunger
• +Bond

9. Kill Action

• Material: Netherite Sword
• Action: Shift + Click to kill animal
• Requirements:Minimum level 2
• Confirmation required
• Drops: Quality based on level/bond

10. Info Display

• Material: Book
• Shows: Detailed statistics
• Info: All animal data, feeding history

11. Page 2 Button

• Material: Paper
• Action: Open second page
• Contains: Animal Home, advanced features

Second Page GUI

Animal Home (Premium)

• Status Display: Shows if home is set
• Set Home: Define territory
• Remove Home: Clear territory
• Visual Preview: Particle boundaries

Back Button

Returns to main GUI page

Color Selection GUI

Features:

• 16 color options
• Real-time preview
• Applies to animal name display
• Supports hex colors via configuration

Colors Available:

• Red, Orange, Yellow, Lime
• Aqua, Blue, Purple, Pink
• White, Gray, Dark Gray, Black
• And more!

Animal Management

Feeding Animals

Methods:

1. Direct Feeding:Hold valid food
2. Right-click animal
3. Restores hunger instantly
4. GUI Feeding:Open animal GUI
5. Click Feed button
6. Uses food from inventory
7. Feeding Stations:Automated feeding
8. Multi-animal support
9. Upgradeable tiers

Valid Foods by Animal:

Animal Foods
Cow - Wheat, Hay Block, Grass, Golden Carrot
Pig - Carrot, Potato, Beetroot, Golden Carrot
Sheep - Wheat, Hay Block, Grass
Chicken - Seeds (Wheat, Beetroot, Pumpkin, Melon)
Wolf - Meat (Beef, Chicken, Pork, Fish)
Horse - Wheat, Apple, Carrot, Sugar, Hay Block

Leveling Up

Automatic Level Up:

• Feed animal required number of times
• Automatic when threshold reached
• Visual effects: particles, sounds
• Benefits apply immediately

Manual Upgrade:

• Open GUI → Upgrade button
• Requires upgrade items (Golden Carrots)
• Instant level gain
• Bonus bond increase

Level Benefits:

• Level 1-5: Basic progression
• Level 6: Riding unlocked, breeding enabled
• Level 7-10: Enhanced stats, better drops

Resource Collection

How It Works:

1. Animals produce resources over time (30s intervals)
2. Production chance based on bond level
3. Resources stored until collected
4. Collection via GUI Collect button

Resource Types:

Standard Resources:

• Cow: Leather, Beef
• Sheep: Wool, Mutton
• Chicken: Feathers, Eggs
• Pig: Porkchop, Leather

Rare Resources (Bond ≥75%):

• Cow: Milk Bucket
• Sheep: Colored Wool
• Chicken: Golden Eggs
• Horse: Saddle

Bonus Resources (Bond ≥100%):

• 1-2 extra items per collection
• Enhanced quality

Breeding System

Requirements:

• Both parents Level 6+
• Both off cooldown (5 minutes)
• Standing near each other (8 blocks)
• Proper feeding

Baby Stats:

• Inherits average level (÷3)
• Inherits average hunger (÷2)
• Inherits 25% of parents' bond
• Starts as baby (if Ageable)

Cooldown:

• 5 minutes per parent
• Prevents over-breeding
• Visual indication in GUI

Advanced Features

Feeding Stations

Overview: Automated structures that feed nearby animals from a container.

Creation:

1. Place Barrel
2. Sneak + Place (with permission)
3. Station activates automatically

Management:

• Sneak + Right-Click: Open GUI
• Add Food: Place in barrel inventory
• Upgrade: Purchase higher tiers

Tiers:

Level Radius Animals/Tick Upgrade Cost
1 5 blocks 2 Free (Base)
2 8 blocks 4 32 Iron Ingots
3 12 blocks 6 16 Diamonds
4 15 blocks 10 4 Netherite Ingots

Features:

• Hologram display (toggleable)
• Particle radius preview
• Automatic feeding every tick
• Multi-animal support

Configuration:

yaml

feeding_stations:
  enabled: true
  interval: 100  # Ticks between feeds
  material: BARREL
  enable_particles: true
```

### Riding System

**Requirements:**
- Animal level 6+
- Hunger >50%
- No cooldown (5 seconds)
- Optional: Saddle (for pigs)

**Controls:**
- **Move**: Look direction + WASD
- **Jump**: Space bar
- **Dismount**: Sneak

**Features:**
- Auto-jump over obstacles
- Smooth acceleration
- Hunger consumption while riding
- Speed based on level + bond

**Speed Calculation:**
```
Final Speed = Base Speed × Speed Multiplier × (1 + Level Bonus + Bond Bonus)

Configuration:

yaml

riding:
  min_level: 6
  min_hunger_to_ride: 5
  speed_multiplier: 1.5
  jump_force: 0.42
  auto_jump_enabled: true

Animal Home System (Premium)

Purpose: Define territories where animals will stay.

Setup:

1. Select animal (right-click)
2. /animalhome set <radius>
3. View particle visualization
4. /animalhome confirm

Features:

• Circular or square boundaries
• Visual particle preview
• Auto-return if animal leaves
• Configurable radius (3-32 blocks)

Configuration:

yaml

animal-home:
  default-radius: 8
  max-radius: 32
  min-radius: 3
  prevent-teleport-out: true
  enable-visual-preview: true

Kill System

Requirements:

• Minimum level 2
• Shift + Click confirmation (in GUI)
• Optional: Specific tool requirement

Bond Influence:

• Bond ≥75%: Rare drops enabled
• Bond ≥100%: Bonus drop amounts

Configuration:

yaml

kill:
  required-level: 2
  required-item: ""  # Empty = any tool
  drop-chance: 0.85

Entity Display System

Animals show custom information above their heads.

Display Format:

yaml

entity_display:
  format: "&#F4A460{name} &#FFD700{level} &#DDA0DD{bond} {bar}"
```

**Components:**
- `{name}`: Animal name (custom or default)
- `{level}`: Level badge
- `{bond}`: Bond percentage
- `{bar}`: Visual hunger bar

**Hunger Bar:**
```
[████████░░] = 80% hunger
Colors: Green (full) → Red (empty)

Configuration:

yaml

entity_display:
  enabled: true
  show_level: true
  show_bond: false
  show_only_after_rename: false
  min_level_to_show: 2

Integration

PlaceholderAPI

Available Placeholders:

Placeholder Description Example
%animalhunger_hunger% Current hunger 15
%animalhunger_max_hunger% Maximum hunger 20
%animalhunger_level% Animal level 7
%animalhunger_bond% Bond percentage 85
%%animalhunger_resources% Stored resources 12
%animalhunger_hunger_bar% Visual hunger bar[████░]
%animalhunger_bond_bar% Visual bond bar [███░░]
%animalhunger_level_by_id_<id>% Level by animal ID 5

Usage Example:

yaml

# In scoreboard or chat format
- "Animal: %animalhunger_level%"
- "Health: %animalhunger_hunger_bar%"

MMOItems Integration

Custom Drops:

yaml

custom_drops:
  cow:
    kill_drops:
      rare_meat:
        type: mmoitems
        mmo_type: CONSUMABLE
        mmo_id: GOLDEN_BEEF
        chance: 25.0
        amount: 1

Supported Drop Types:

• mmoitems: MMOItems custom items
• vanilla: Standard Minecraft items

Features:

• Drop chance configuration
• Amount ranges
• Custom lore and names (vanilla)
• Full MMOItems integration

MythicMobs Integration

Support:

• All MythicMobs entities supported
• Custom display names
• Unique configurations per mob type

Example:

yaml

animals:
  CustomCow:  # MythicMob ID
    display_name: "Magical Cow"
    feed_items: ["GOLDEN_APPLE"]
    resource_items: ["DIAMOND"]

Troubleshooting

Common Issues

1. Animals Not Saving

Symptoms: Data resets on restart

Solutions:

• Check database connection
• Verify storage.type in config
• Check MySQL credentials
• Enable debug mode: debug: true

2. Riding Not Working

Symptoms: Cannot mount animals

Solutions:

• Verify level 6+ requirement
• Check hunger >50%
• Ensure disable-riding: false
• Check permission: animalhunger.ride

3. GUI Not Opening

Symptoms: No GUI on shift-right-click

Solutions:

• Check permission: animalhunger.use
• Verify entity is supported
• Check world whitelist/blacklist
• Review ignored entity types

4. Feeding Stations Not Working

Symptoms: Station doesn't feed animals

Solutions:

• Verify correct block type (BARREL)
• Check food in station inventory
• Ensure animals within radius
• Confirm feeding_stations.enabled: true

5. High MSPT/Lag

Symptoms: Server performance issues

Solutions:

yaml

# Optimize intervals
hunger-decrease-interval: 12000  # 10 minutes
resource_production.production_check_interval: 1200  # 60 seconds

# Reduce tick frequency
feeding_stations.interval: 200  # Slower checks

6. Database Errors

MySQL Connection:

yaml

storage:
  type: "mysql"
  mysql:
    host: "localhost"
    port: 3306
    database: "animalhunger"
    username: "your_username"
    password: "your_password"
    useSSL: false
    autoReconnect: true

SQLite (Alternative):

yaml

storage:
  type: "sqlite"
```

### Debug Commands

**View Animal Data:**
```
/animalhunger debug
```
Shows: UUID, hunger, level, bond, resources

**Check Resources:**
```
/animalhunger resources
```
Shows: MSPT impact, tick counts, active animals

**Database Stats:**
```
/animalhunger dbstats

Shows: Record count, database size, storage type

Performance Optimization

Recommended Settings (Large Servers):

yaml

# Core intervals
hunger-decrease-interval: 12000  # 10 min
resource_production.production_check_interval: 1200  # 60s

# Feeding stations
feeding_stations.interval: 200  # 10s

# Bond decay
bond.enable-decay: false  # Disable if not needed

# Cache cleanup
# Automatic every 10 minutes

# World restrictions
world-settings:
  mode: "whitelist"
  worlds:
    - "world"  # Only main world
```

**Database Cleanup:**
```
/animalhunger dbcleanup 30  # Remove records older than 30 days

Tips & Best Practices

For Players

1. Start Small: Focus on 1-2 animals initially
2. Prioritize Bond: Higher bond = better rewards
3. Use Stations: Automate feeding for efficiency
4. Breed Strategically: Wait for high-level parents
5. Name Your Animals: Easier to track and manage

For Server Admins

1. Set Player Limits: Prevent animal hoarding

yaml

   bond.max-animals-per-player: 5

1. Configure Intervals: Balance gameplay vs performance
2. Enable Auto-Save: Prevent data loss
3. Use MySQL: Better for larger servers
4. Monitor Performance: Regular /animalhunger resources checks
5. Clean Old Data: Monthly /animalhunger dbcleanup 30

Recommended Configurations

Survival Server (Default):

yaml

max-level: 10
feedings-per-level: 3
bond.max-animals-per-player: 5
hunger-decrease-interval: 6000  # 5 min

Hardcore Server:

yaml

max-level: 15
feedings-per-level: 5
bond.max-animals-per-player: 3
hunger-decrease-interval: 3600  # 3 min
disable-animal-death-on-starvation: false

Casual/Creative Server:

yaml

max-level: 20
feedings-per-level: 2
bond.max-animals-per-player: 0  # Unlimited
hunger-decrease-interval: 12000  # 10 min
disable-animal-death-on-starvation: true

API Information

For Developers

Getting Animal Data:

java

AnimalHunger plugin = (AnimalHunger) Bukkit.getPluginManager().getPlugin("AnimalHunger");
UUID animalId = animal.getUniqueId();
AnimalData data = plugin.getAnimalData(animalId);

Modifying Data:

java

data.setHunger(15);
data.setLevel(5);
data.setBondLevel(75);
plugin.saveAnimalData(animalId);

Events: Plugin uses standard Bukkit events:

• PlayerInteractEntityEvent: For interactions
• EntityDamageByEntityEvent: For killing
• CreatureSpawnEvent: For spawning