Loyal Companion

---

✨ About Loyal Companions

Loyal Companions adds a full companion progression system to Minecraft. Friendly mobs can become personal pets with their own levels, XP, skill points, inventory, gear, rarity, accessories, behavior modes, HUD, and revival mechanics.

Your companions can follow you, fight beside you, carry items, wear special gear, equip magical gems and amulets, be stored as transferable totems, and return through a magical shrine if they fall in battle.

Loyal Companions also includes a compatibility API and config whitelist system, allowing mod developers and modpack creators to add support for friendly mobs from other mods.

---

⭐ Main Features

• 🐾 Capture friendly mobs and turn them into loyal companions
• 📈 Custom leveling system with XP, levels, and skill points
• 💪 Upgrade companion stats:
  • Strength — increases damage
  • Defense — improves protection
  • Attack Speed — reduces attack cooldown
  • Vitality — increases maximum health
• 🌟 Rarity system with stat bonuses and colored visual effects
• ✨ Enhanced companions with smaller size and bonus inventory potential
• 🖥️ Custom companion menu with calculated values and 3D preview
• 📊 Moveable companion HUD with health, XP, level, name, and model preview
• 🎒 Pet inventory with normal slots, food slot, gear slot, gem slot, amulet slot, and bonus slots
• ⌨️ Configurable keybind to open the active companion inventory directly
• 🛡️ Companion gear with harnesses and armor plating
• 💎 Companion gems and amulets with unique stat bonuses and loot sources
• 🩹 Pet healing items with small, medium, and large bandages
• ⚔️ Behavior modes including safe monster targeting and full mob targeting
• 🍖 Feeding system based on each companion’s mob type
• 📣 Companion Whistle with pet selection menu
• 🧿 Companion Totems for storing, transferring, and reviving pets
• 🛕 Companion Shrine with revival animation and pet storage
• 💔 Companion Hearts dropped by Iron Golems for revival
• 🔌 Public read-only API for other mods to detect companions, owners, levels, stats, and companion damage sources
• 🧩 Modded mob compatibility API for other mod authors
• 📜 Config whitelist and blacklist for modpack creators and users
• 👥 Optional PartyLink compatibility
• ⚙️ Server and singleplayer configs for important gameplay settings

---

🐕 Capture & Train Companions

Use a Capture Charm on a friendly mob to bind it as your companion. Your pet will follow you, gain XP, level up, and become stronger over time.

Each level grants 1 skill point, which can be spent in the companion menu. Build your pet as a stronger fighter, tougher guardian, faster attacker, or more durable travel partner.

---

🌟 Rarity & Enhanced Companions

Companions can have a rarity, giving them additional base stat bonuses and colored visual effects. Enhanced status is separate from rarity, so a companion can be both Enhanced and Legendary.

• Normal — no bonus stat points
• Rare — +1 to every attribute
• Epic — +3 to every attribute
• Legendary — +5 to every attribute

Enhanced companions are smaller, visually special, and can unlock additional inventory space at higher levels.

---

🎒 Pet Inventory

Companions have their own inventory screen with custom slots and tooltips. The active companion inventory can also be opened directly with a configurable keybind.

• 9 normal inventory slots
• 1 food slot
• 1 gear slot
• 1 gem slot
• 1 amulet slot
• 9 bonus slots for Enhanced companions at level 20

The inventory includes the player inventory and hotbar for easy item movement. Item names and descriptions are shown directly in custom screens.

---

🛡️ Companion Gear

Equip your companion with special gear to improve its power and survivability.

• Companion Leather Harness
• Companion Iron Plating
• Companion Gold Plating
• Companion Diamond Plating
• Companion Netherite Plating

Gear can provide bonuses such as armor, health, and attack speed. Equipped gear also adds a small visual effect to your companion.

---

💎 Gems & Amulets

Loyal Companions adds magical gems and amulets for your pet. These accessories provide additional stat bonuses and can be found through crafting, village loot, dungeon loot, Nether enemies, bosses, and the Ender Dragon.

💠 Gems

• Frostbound Gem — craftable starter gem
• Verdant Gem — found in village loot
• Crimson Labyrinth Gem — found in dungeon loot
• Soulflame Gem — rare Wither Skeleton drop
• Dragon Prism Gem — powerful Ender Dragon drop

🧿 Amulets

• Guardian Heart Amulet — craftable starter amulet
• Villagekeeper Amulet — found in village loot
• Wayfinder Amulet — found in dungeon loot
• Wraithbone Amulet — Wither drop
• Dragon Eye Amulet — powerful Ender Dragon drop

The strongest accessories are designed as rare boss rewards, giving the Ender Dragon a valuable companion-focused loot progression.

---

🩹 Pet Healing Items

Companions can be healed with dedicated bandages.

• Small Companion Bandage — restores a small amount of health
• Medium Companion Bandage — restores a moderate amount of health
• Large Companion Bandage — restores a large amount of health

These items make long adventures, dungeon runs, and boss fights much safer for your companion.

---

⚔️ Behavior Modes

• Follow — follows the player normally
• Wait — stays in place
• Passive — does not attack
• Protect — protects the player from nearby threats
• Bad Monsters — attacks only clearly hostile monster enemies
• All Mobs — attacks most mobs, while still protecting players, villagers, traders, and companions

This allows you to choose between a safe monster-only mode and a stronger aggressive mode for hunting.

---

📣 Companion Whistle & Pet Slots

The Companion Whistle opens a pet selection menu. Depending on the config, players can manage multiple companion slots.

For stability and balance, only one companion can be active at a time. Despawn your current pet before summoning another stored companion.

---

🛕 Companion Shrine & Revival

When a companion falls, it can be stored inside a Companion Totem. The totem contains important pet data such as name, mob type, level, stats, inventory, rarity, Enhanced status, and supported special mob data such as fox type, wolf type, horse color, saddle, armor, and ownership.

To revive a fallen companion, place a Companion Totem and a Companion Heart into the Companion Shrine. The shrine plays a short revival animation and restores the pet afterward.

You can also use the shrine to store your active companion as a totem without killing it. This makes it possible to trade or transfer pets between players.

---

🧩 Modded Mob Compatibility

Loyal Companions includes two ways to support friendly mobs from other mods:

• Developer API — for mod authors who want to add direct support
• Config whitelist — for modpack creators or users who want to enable specific modded mobs manually

This system is useful for mods that add friendly animals, wildlife, fantasy creatures, or tamable mobs. As an example, this description uses WildCreatures.

📜 Config Example: WildCreatures

Add entries like this to your Loyal Companions config:

companion_entity_whitelist=wildcreatures:crab companion_entity_blacklist=wildcreatures:shark,wildcreatures:jellyfish,wildcreatures:mussel companion_food_overrides=wildcreatures:crab=minecraft:wheat

In this example:

• wildcreatures:crab can be captured as a companion
• wildcreatures:shark, wildcreatures:jellyfish, and wildcreatures:mussel are blocked
• The crab accepts Wheat as companion food

🍖 Food Override Format

A simple single-item food override:

companion_food_overrides=wildcreatures:crab=minecraft:wheat

Multiple accepted food items:

companion_food_overrides=wildcreatures:crab=minecraft:wheat|minecraft:apple|minecraft:carrot

Custom display text with a translation key:

companion_food_overrides=wildcreatures:crab=food.wildcreatures.crab|minecraft:wheat|minecraft:apple

When only one food item is configured, the companion menu will display the item name automatically, for example Wheat instead of a generic “Configured Food” label.

🧪 Developer API Example

Other mods can register their own companion support directly:

LoyalCompanionsApi.allowCompanionEntity("wildcreatures:crab");

LoyalCompanionsApi.setCompanionFood( "wildcreatures:crab", "food.wildcreatures.crab", "minecraft:wheat", "minecraft:apple" );

LoyalCompanionsApi.blockCompanionEntity("wildcreatures:shark"); LoyalCompanionsApi.blockCompanionEntity("wildcreatures:jellyfish");

Blacklist entries always win over whitelist or API registrations. The entity still needs to be a valid mob entity, so technical or unsafe entities are not made companion-compatible accidentally.

---

🔌 Public Read-Only API for Other Mods

Loyal Companions provides a public read-only API so other mods can safely detect companions, check ownership, read companion stats, and identify companion damage sources without accessing internal mod classes.

This is useful for dungeon mods, boss mods, combat balancing mods, party systems, claim protection mods, and mods such as Solo Mining that need to treat companion damage differently from player damage.

API class:

com.mki.loyalcompanions.api.LoyalCompanionsApi

🐾 Companion Detection

Other mods can check if an entity is a Loyal Companions pet:

if (LoyalCompanionsApi.isCompanion(attacker)) {
    // Companion damage can be handled here
}

Available methods:

public static boolean isCompanion(Entity entity)

public static boolean isOwnedCompanion(Entity entity, UUID ownerUuid)

public static Optional<UUID> getCompanionOwner(Entity entity)

public static boolean isOwnedByPlayer(Entity entity, ServerPlayer player)

📊 Companion Stats

Other mods can safely read companion progression values:

public static int getCompanionLevel(Entity entity)

public static int getCompanionAttack(Entity entity)

public static int getCompanionStrength(Entity entity)

public static int getCompanionDefense(Entity entity)

public static int getCompanionVitality(Entity entity)

These values are read-only and do not modify the companion.

⚔️ Damage Source Helpers

For combat-related mods, the API also provides helper methods for checking whether damage came from a companion:

public static boolean isCompanionDamageSource(DamageSource source)

public static Optional<LivingEntity> getCompanionAttacker(DamageSource source)

Example:

LoyalCompanionsApi.getCompanionAttacker(source).ifPresent(companion -> {
    // Damage was caused by a Loyal Companions pet
});

🎒 Stored Companion Helper

Other mods can also check if an item stack contains a stored companion:

public static boolean isStoredCompanion(ItemStack stack)

🔒 API Safety

The public API is intentionally read-only. It is designed for compatibility and detection only.

Other mods should use:

com.mki.loyalcompanions.api.LoyalCompanionsApi

and should not directly access internal classes such as:

com.mki.loyalcompanions.companion.CompanionData

---

👥 Optional PartyLink Support

Loyal Companions includes optional compatibility with PartyLink. If PartyLink is installed, party companions are protected from friendly fire.

• Party members’ pets will not attack each other
• Party PvP settings are respected
• The mod still works normally without PartyLink

---

⚙️ Configuration

Loyal Companions supports separate configuration handling for dedicated servers and local singleplayer worlds.

• Enable or disable companion revival
• Companion Heart drop chance
• Enhanced companion chance
• Rarity chances
• Maximum companion level
• Maximum managed companion slots per player
• Protect mode radius
• Aggressive mode radius
• Maximum bonus skill points from companion candy
• Companion candy and loot behavior
• Modded companion whitelist
• Modded companion blacklist
• Modded companion food overrides

---

🧭 Perfect For

• Survival worlds
• Adventure modpacks
• RPG-style progression
• Multiplayer servers
• Players who want pets with real gameplay value
• Modpacks with custom wildlife and friendly creatures

---