CompanionCraft 2.0.0

make sure to check out my ko-fi for custom plugin services

Core features

• Capture any vanilla Bukkit Mob, including passive, neutral, hostile, aquatic, flying, daylight-sensitive, dimension-sensitive, Wither, and Ender Dragon entities.
• Basic, Advanced, and Legendary Companion Arrows fired from bows or crossbows. Missed normally-recoverable arrows remain pickupable; mob impacts consume the arrow.
• Up to three active companions per owner with duplicate-resistant runtime identities.
• Follow, Stay, Passive, Wander, Defend, and Aggressive modes, plus safe recall and all-summoned group controls.
• Persistent JSON appearance snapshots with backward-compatible semicolon snapshot restoration.
• Stable variants, baby/adult state, scale, equipment, saddles, mount storage, internal mob inventories, villager trades, Copper Golem oxidation/state, and species-specific appearance data.
• Level 1–60 progression. Owner kills grant XP and a companion's kill grants twice the owner reward.
• Exact configurable critical curve from 5% at level 1 to 35% at level 60; critical hits use a 2x multiplier by default.
• Level 60 grants the configured 30% health/damage/defense bonus and a secure 27-slot companion inventory.
• Manage Gear for held items, armor, body/mount armor, and saddles, including Nautilus-family equipment on Paper 26.2.
• Favorites, name colors, per-companion mute, critical-notification mute, and linked Summon Sticks.
• 1v1, 2v2, and 3v3 exhibition duels with All Out and Singles formats, virtual boundaries, knockouts, restored health, and locked external controls.
• Companion death returns the companion to its roster instead of deleting it.
• Permanent release requires confirmation and an empty companion inventory.

Companion modes

• Follow: Follows the owner and safely teleports back if separated by more than 25 blocks.
• Stay: Remains at the exact assigned location. Distance recall and follow movement are disabled.
• Passive: Follows the owner but does not initiate or respond with combat. The 25-block recall remains active.
• Wander: Freely wanders using normal mob movement. It does not follow or teleport back to the owner.
• Defend: Uses wolf-style defensive behavior. It attacks only entities that damage the owner or the companion. It may chase an authorized target up to 20 blocks before returning and uses the 25-block owner recall when not anchored in combat.
• Aggressive: Automatically targets hostile mobs within 10 blocks of the owner. It never intentionally targets players, passive mobs, or neutral mobs. It may chase its selected target up to 20 blocks before returning, and it will not chain to a new target unless that target is within 10 blocks of the owner.

All summoned companions can be assigned a mode together through the controller-friendly All Summoned Companions menu.

Crafting

• Basic Companion Arrow: Arrow in middle-left and Name Tag in center.
• Advanced Companion Arrow: Basic Companion Arrow in center, surrounded by Gold Nuggets.
• Legendary Companion Arrow: Advanced Companion Arrow in center, surrounded by Gold Ingots.
• Summon Stick: one Stick plus one Torch anywhere in a crafting grid.

The first successful capture grants one owner-bound Companion Key and the signed in-game guide. Further captures do not create duplicate keys. An administrator can rotate a genuinely lost key with /companion key <player>; every old copy becomes invalid.

Commands and permissions
Player commands:

• /companion menu, /companion list, /companion guide
• /companion summon <id>, /companion dismiss
• /companion follow|stay|passive|wander|defend|aggressive
• /companion release <id> confirm

Administrator commands:

• /companion arrow <player> <basic|advanced|legendary> <amount>
• /companion key [player]
• /companion audit [player|uuid]
• /companion backup [player|uuid]
• /companion repair [player|uuid]
• /companion status

Permissions:

• companioncraft.use — capture and open the manager; default true
• companioncraft.manage — summon and modify companions; default true
• companioncraft.admin — maintenance and item administration; default op

Upgrade and data-safety contract
Never delete the CompanionCraft data folder to update the plugin. Version 2 uses additive migrations and retains legacy roster fields. Current captures use snapshot version 7; existing semicolon snapshots and earlier JSON snapshots remain readable.

Roster saves use forced temporary files, atomic replacement where supported, rotating backups, stale-write generation guards, and validation before recovery. Companion storage and Manage Gear transfers use a write-ahead transaction journal. If a roster and every backup are unreadable, the roster is quarantined from overwrite rather than being interpreted as empty.

Recommended upgrade process:

1. Stop the server cleanly.
2. Back up the world and the complete plugins/CompanionCraft folder.
3. Replace only the plugin JAR.
4. Start Paper and review the startup log.
5. Run /companion status and /companion audit <test-player>.
6. Perform the manual smoke tests in RELEASE_CHECKLIST.md before opening the server publicly.

Building
mvn clean test package

The release artifact is target/CompanionCraft-2.0.0.jar. Paper is a provided dependency and is not bundled into the JAR.

Configuration
config.yml validates movement, combat, progression, capture, environment, duel, persistence, and interface settings at startup. Invalid or unsafe numeric values fall back to bounded defaults. Existing player or companion data is never reset when configuration changes.

Boss capture probabilities are decimal probabilities: 0.0001 = 0.01%, 0.0010 = 0.10%, and 0.0099 = 0.99%.