"Your friend. Your rival. Your doom."

📖 Overview

Evil Companion is a revolutionary Minecraft mod that completely reimagines the boss fight experience. Instead of a static encounter, you get a dynamic, evolving rival that starts as your annoying friend but can become your ultimate nemesis. Perfect for players who want a persistent challenge that grows with them!

� Quick Features

Feature	Description
🎭 Dual Personality	Friendly prankster → Hostile rival
📈 Infinite Scaling	Balanced progression from Level 1 to 1000+
👥 Multiplayer Modes	SHARED, PER_PLAYER, RATIO, or MANUAL spawning
🧠 Smart AI	15+ behaviors: mining, stealing, climbing, fighting
🎨 Custom Textures	Bespoke calm/enraged skins with Steve fallback
🧱 Trap Master	Breaks blocks to escape, climbs ladders, uses doors
⚡ Teleportation	Follows you across dimensions
🎯 Gear Thief	Steals your best equipment and uses it!
🐉 End Boss	Defends Ender Dragon, rebuilds crystals
🧪 Peace Items	Craft tonics and elixirs for temporary truces
📘 In-Game Guide	16-page field guide with all mechanics explained
⚙️ Fully Configurable	50+ config options for custom difficulty

🌟 What Makes It Special?

Unlike traditional boss mods with one-time fights, Evil Companion offers:

Progressive Storytelling: Watch your companion evolve from playful to dangerous
Persistent Challenge: Boss survives death, levels up, and remembers you
Dynamic Difficulty: Balanced scaling ensures fair fights at all levels (NEW in v1.1.0!)
Multiplayer Excellence: Four spawn modes adapt to any server size (v1.1.1+)
Player-Like Intelligence: Uses doors, climbs ladders, presses buttons, blocks attacks
Emotional Investment: You'll love to hate this annoying, gear-stealing menace!

🎮 THE EXPERIENCE

v1.1.0 Update: Now with balanced progression, enhanced AI, and complete field guide!

Level 1: The Mischievous Friend 😊

Your companion spawns at Level 1 and is NOT hostile. Instead, it acts like a playful, greedy player:

Core Behaviors:

⛏️ Mining: Competes with you for diamonds, gold, emeralds
🌳 Chopping: Mines wood alongside you
📦 Item Stealing: Picks up dropped valuables before you can
🗨️ Chat Messages: "Yoink! Thanks for the Diamond!"
🚪 Teleportation: Teleports to you when you're >100 blocks away
- Message: "Surprise! :)" or "Found you!"
- Cooldown: Every 2 minutes
🧗 Climbing: NEW! Climbs ladders, vines, and scaffolding
🚪 Interactions: NEW! Opens doors, presses buttons, pulls levers
⚔️ Monster Fighter: NEW! Fights hostile mobs to protect itself (even at Level 1!)

The Greed Counter:

Every mischievous action increases the companion's "greed"
Higher greed = more frequent stealing and annoying actions
Greed 10+: Starts stealing from your inventory directly
Greed 15+: Begins breaking your blocks (griefing)
Greed 20+: Raids your chests

Survival Tips:

Don't leave valuables on the ground - it WILL steal them
Lock up your chests with redstone mechanisms
Avoid hitting it unless you're ready for war!

Level 2: MAXIMUM ANNOYANCE 😈

Everything gets 2x more frequent:

Activity	Level 1	Level 2
Mining	Every 15s	Every 7.5s
Item Stealing	Every 30s	Every 15s
Inventory Theft	Greed 10+	Greed 5+
Chest Raiding	Greed 20+	Greed 10+
Griefing	Greed 15+	Greed 8+
Teleportation	Every 120s	Every 60s

🎯 Gear Stealing System!

The companion has a smart gear evaluation AI:

Compares your equipped gear vs its own
Steals better weapons and armor
Immediately equips stolen gear
Drops its old equipment
Chat: "§6Thanks [Player] for the [Netherite Sword]! Nice upgrade! :D"

Gear Scoring Algorithm:

Score = Material Value + (Enchantments × 10) + (Durability × 5)

Material Values:
- Netherite: 100
- Diamond: 80
- Iron: 60
- Gold: 40 (but enchants can make it better!)
- Leather: 20

Example: A fully enchanted Diamond Sword (5+ enchants) can be worth MORE than an unenchanted Netherite Sword!

💥 Becoming Hostile

After 3 hits (configurable), the companion becomes HOSTILE:

⚠️ Message: "§cThe Evil Companion is now HOSTILE!"
All combat abilities activate
Infinite progression begins
Boss bar appears with health display
True boss fight starts!
Point of no return - only death or truce items can stop it now!

🌐 MULTIPLAYER FEATURES

Perfect for servers! Three spawn modes to fit any player count:

Spawn Modes:

Mode	Description	Best For
SHARED (Default)	One boss for entire server	Co-op teams, small servers
PER_PLAYER	One boss per player	Competitive servers, solo challenges
RATIO	One boss per X players	Medium/large servers, balanced gameplay
MANUAL (v1.1.1+)	No automatic spawning	Event servers, full admin control

1. SHARED Mode (Cooperative)

One boss for entire server
Everyone fights together
Boss tracks all players
Promotes teamwork
Scales difficulty with player count
Example: 5 players vs 1 super-powered boss

2. PER_PLAYER Mode (Competitive)

One boss per player
Each player has their own companion
Independent progression
Competitive leaderboards
No interference between players
Example: 10 players = 10 separate bosses

3. RATIO Mode (Balanced)

One boss per X players (configurable)
Example: ratio = 2 means 1 boss per 2 players
Balanced server performance
Fair difficulty distribution
Adapts to server size
Example: 20 players with ratio 5 = 4 bosses

4. MANUAL Mode (Admin Controlled) NEW in v1.1.1

Zero automatic spawning
Admins spawn bosses with /ec spawn-boss <player>
Perfect for event servers and custom scenarios
Complete control over when and who gets a boss
Ideal for story-driven gameplay or scheduled events
Example use: Boss fights only during server events

Advanced Player Assignment:

Boss tracks "assigned players" via UUID (persistent across restarts)
Teleports between assigned players fairly
Prioritizes distant players (more annoying!)
Updates when players join/leave
Handles dimension changes gracefully
Despawns when all assigned players are offline

Edge Cases Handled:

✅ Player changes dimension → Boss waits or reassigns
✅ Player dies → Boss continues hunting
✅ All players offline → Boss despawns cleanly
✅ Player in combat → Teleport priority increases
✅ Boss stuck in unloaded chunks → Auto-teleports to nearest player

⚔️ COMBAT & PROGRESSION

v1.1.0 Major Balance Update: Completely rewritten progression system with diminishing returns for fair fights at all levels!

Balanced Infinite Scaling (Levels 3+)

Once hostile, the companion scales infinitely with smart diminishing returns:

New Stats Formula (v1.1.0):

Early Game (Levels 1-10): Linear Growth
- Health = Base + (Level × Multiplier)
- Damage = Base + (Level × Multiplier)
- Fast progression for accessible early game

Mid Game (Levels 11-50): Square Root Scaling
- Health = Base + (√(Level - 10) × Multiplier × 8)
- Damage = Base + (√(Level - 10) × Multiplier × 3)
- Moderate progression for balanced mid game

Late Game (Levels 51+): Logarithmic Scaling
- Health = Base + (log(Level - 50 + 1) × Multiplier × 20)
- Damage = Base + (log(Level - 50 + 1) × Multiplier × 8)
- Slow progression prevents impossible fights

Additional Stats:
- Armor = Base + (Level × 0.5), max 30
- Knockback Resist = Level × 5%, max 100%

Balanced Examples:

Level	Health	Damage	Armor	Notes
1	120 HP	4 DMG	0	Starting stats (Iron equipment)
10	220 HP	12 DMG	5	End of linear growth
25	420 HP	20 DMG	12.5	Diamond equipment
50	720 HP	28 DMG	25	Netherite equipment
100	1,100 HP	38 DMG	30	Challenging but fair
200	1,560 HP	50 DMG	30	Requires strategy
500	2,100 HP	70 DMG	30	Epic endgame fight
1000	2,700 HP	85 DMG	30	Legendary challenge

Why Diminishing Returns?

✅ Boss remains challenging but beatable at ALL levels
✅ No more impossible Level 200+ fights
✅ Encourages long-term progression
✅ Fair for all player skill levels
✅ Maintains difficulty curve without exponential spikes

Equipment Progression:

The boss automatically upgrades its gear as it levels up:

Level	Weapon	Armor	Enchantments
1-4	Iron Sword	Iron Armor	None
5-9	Diamond Sword	Diamond Armor	Sharpness II, Protection II
10-14	Netherite Sword	Diamond Armor	Sharpness IV, Protection III
15-19	Netherite Sword	Netherite Armor	Sharpness V, Protection IV, Fire Aspect II
20-24	Netherite Sword	Netherite Armor	+ Unbreaking III on all items
25+	Netherite Sword	Netherite Armor	+ Sweeping Edge III, Looting III
30+	Netherite Sword	Netherite Armor	All enchantments max level

Special Equipment Features:

Shield: NEW! Boss now uses shield with proper blocking animation
- Cooldown: 5 seconds between uses
- Only activates below 80% health
- Shows crouch and shield-raise animations
Enchantment Scaling: Enchantment levels increase infinitely with boss level
Gear Stealing: Boss can upgrade mid-fight by stealing YOUR gear!

Pro Tip: The boss evaluates gear quality intelligently - a heavily enchanted Diamond sword might be worth more than a plain Netherite sword!

Special Abilities:

The boss unlocks powerful abilities as it levels up:

Level	Ability	Effect	Details
1+	Trap Escape	Breaks blocks when stuck	NEW! Stops breaking during combat
1+	Climbing	NEW! Climbs ladders, vines, scaffolding	Full navigation freedom
1+	Door Usage	NEW! Opens doors, presses buttons, pulls levers	Player-like intelligence
1+	Shield Defense	NEW! Blocks attacks with shield	5s cooldown, <80% HP only
3+	Speed Boost	Speed II-V when below 30% HP	Retreat or aggressive chase
5+	Minion Summoning	Spawns zombies (1 + Level/5)	Up to 20+ minions
7+	Regeneration	Regen I-IV (scales every 5 levels)	Hard to wear down
10+	Resistance	Resistance II-IV when blocking	Damage reduction
12+	Fire Aura	Burns entities within 3-8 blocks	Area denial
15+	Lightning Strike	Summons lightning on players	Devastating AoE
20+	Weather Control	Creates thunderstorms	10min cooldown
30+	Strength	Permanent Strength I-III	Increased melee damage
40+	Jump Boost	Permanent Jump Boost III	Superior mobility

Combat Abilities Summary:

Defensive: Shield blocking, regeneration, resistance
Offensive: Fire aura, lightning strikes, strength buffs
Mobility: Speed boost, jump boost, climbing, teleportation
Strategic: Weather control, minion summoning, trap escape

Note: All ability levels are configurable in config/evil_companion-common.toml

🧱 Trap Escape & Navigation System:

v1.1.0: Boss now stops breaking blocks when it can attack or reach you directly!

The companion has advanced pathfinding AI to escape traps and reach targets:

Breaking Rules:

Level	Can Break
1-2	Soft blocks (dirt, wood, glass, leaves)
3-9	+ Stone, cobblestone, ores
10+	ANY block except bedrock

When It Activates:

✅ Boss hasn't moved for 3+ seconds (stuck detection)
✅ Boss is surrounded by blocks (trapped/enclosed)
✅ Target is visible but unreachable (pathfinding needed)
❌ Boss is NOT angry, hostile, or has a reachable target (NEW in v1.1.0)

Smart Detection:

Detects enclosed spaces (walls on 3+ sides)
Detects ceiling traps (blocks overhead)
Detects pit traps and obstacles
Prioritizes blocks toward target player
NEW: Stops breaking when it can fight instead

Break Speed:

Scales with boss level (faster at higher levels)
Visual break particles and sound effects
Level 5+: Chat message "§6[Boss] breaks through your trap!"

Navigation Abilities (v1.1.0):

🧗 Climbing: Ladders, vines, scaffolding, webs
🚪 Doors: Opens wooden and iron doors
🔘 Buttons: Presses buttons to open paths
🎚️ Levers: Pulls levers strategically
🏊 Swimming: Floats in water, swims to targets
🌨️ Snow Walking: Climbs on top of powder snow

Strategy Tips:

✅ Early game: Stone traps work until Level 3
✅ Mid game: Obsidian slows (but won't stop Level 10+)
✅ Late game: Constant movement > static traps
❌ Don't rely on doors, buttons, or levers - it can use them!
❌ Vertical traps are less effective - it can climb now!

Minion Spawning:

The boss can summon reinforcements during combat:

Unlock Level: 5+
Minion Type: Zombies (equipped with gear)
Count Formula: 1 + (Level ÷ 5), maximum 20 minions
Equipment: Scales with boss level (better gear at higher levels)
Cooldown: 30 seconds at Level 5 → Near-instant at Level 50+
Behavior: Minions actively hunt assigned players

Examples:

Level 10: 3 zombies every 25 seconds
Level 25: 6 zombies every 15 seconds
Level 50: 11 zombies every 5 seconds
Level 100: 21 zombies near-instantly

🐉 END DIMENSION MECHANICS

v1.1.0 Complete Overhaul: Fixed all major bugs, improved AI, and balanced spawning!

When the Ender Dragon is alive, the companion gets special powers:

Instant Respawn:

Normal: 30+ seconds
In End: 5 seconds (when dragon is alive)
NEW: Only spawns once per death (no more spam!)
NEW: Checks entire End dimension for existing boss
NEW: Only spawns if players are present
Message: "A Boss arrives to defend the Dragon!"

Dragon Defense AI:

1. Rebuild End Crystals 🔮

How it works:

Scans 100-block radius for destroyed pillars
Finds nearest pillar needing a crystal
Navigates to pillar base
NEW: Towers up by placing obsidian blocks beneath itself
Places crystal on bedrock top only
Verifies no duplicate crystals

Improvements (v1.1.0):

✅ Proper pathfinding to pillars
✅ Actual towering behavior
✅ Only places on valid bedrock positions
✅ Checks for existing crystals first
✅ 10-second action cooldown

2. Spawn Reinforcements 🐚

Spawn System:

70% Endermen (less annoying)
30% Shulkers (with 30-second cooldown)
Spawns near boss (3-6 block radius)
NEW: Void-safe spawning (Y >= 10 only)
Targets assigned players
Portal particle effects

Improvements (v1.1.0):

✅ Balanced Endermen/Shulker ratio
✅ Shulker spam prevented (30s cooldown)
✅ Won't spawn in void
✅ Validates spawn positions

3. Aggressive Combat ⚔️

Attack Abilities:

Foot Trap: Immobilizes player (no roof, boss can attack from above!)
Disarm: Knocks items from hands
Launch: Throws players into air
NEW: 3-second global cooldown between abilities
NEW: Only one ability at a time

Safety Improvements (v1.1.0):

✅ Won't trap near End portals (5-block radius)
✅ Won't trap players in mid-air
✅ Won't trap near void (Y < 10)
✅ Foot trap only (legs), not full cage
✅ Boss can attack trapped players from above

4. Void Avoidance 🌌

NEW in v1.1.0:

Detects Y < 0 and teleports to safety immediately
Stops falling at Y < 10
Finds nearest assigned player or End spawn
Locates safe solid ground above Y=10
Result: Boss never dies to void!

5. Enhanced Priority System ⚡

v1.1.0 Priority Logic:

Crystal Rebuilding (Highest)
- Check every 10 seconds
- 40% chance to attempt
- 10-second cooldown
Helper Spawning (Medium)
- Check every 5 seconds
- 25% chance to attempt
- 5-second cooldown
Combat Abilities (Low)
- 3-second global cooldown
- Only targets assigned players
- One ability at a time

Benefits:

✅ No action conflicts
✅ Predictable behavior
✅ Balanced threat level
✅ Fair for players

Special Targeting Rules (v1.1.0):

When Hostile in End:

✅ Targets assigned players only
✅ Targets Iron Golems (natural enemy)
❌ Does NOT mine blocks (focuses on combat)
❌ Does NOT attack all mobs randomly

Result: Focused, intelligent combat that feels fair!

💎 LOOT SYSTEM

Killing the boss rewards you with infinitely scaling loot:

Always Drops:

Resource	Formula	Example (Level 50)
Diamonds	Level + (Level ÷ 3)	66 diamonds
Iron Ingots	(Level + 5) + (Level ÷ 5)	65 iron
Gold Ingots	(Level ÷ 2 + 1) + (Level ÷ 10)	31 gold
Experience	50 + (Level × 10) + (Level^1.3 × 2)	~800 XP

Progressive Drops:

Level	Items	Drop Chance	Notes
5+	Emeralds	100%	(Level - 4) + (Level ÷ 5)
10+	Netherite Scrap	100%	(Level - 9) ÷ 2 + (Level ÷ 10)
15+	Nether Stars	100%	1 + (Level ÷ 20)
15+	Enchanted Golden Apples	100%	1 + (Level ÷ 15)
25+	Netherite Ingots	100%	(Level - 24) ÷ 5
35+	Totem of Undying	30%	Chance based
40+	Elytra	50%	Chance based
50+	Dragon Egg	100%	Legendary prize!
60+	Beacon	100%	Ultimate reward!

Enchanted Books:

Starting Level: 3+ (configurable)
Base Drop: 1 book, 50% chance
Scaling: +1 book per 10 levels (max 11+ books at Level 100+)
Chance Increase: +1% per level
Enchantments: 1-3 random enchantments per book based on boss level
- Level 3-19: 1 enchantment (low-mid level)
- Level 20-49: 2 enchantments (mid-high level)
- Level 50+: 3 enchantments (max level)

Boss Equipment:

The boss drops its equipped gear on death:

Weapons (often Netherite with max enchants)
Armor (full Netherite set at high levels)
Shield (if equipped)
Any stolen player gear

Pro Tip: High-level bosses drop more loot than Wither and Ender Dragon combined!

🧪 PEACE ITEMS & CRAFTING

Companion Field Guide 📘

NEW in v1.1.0: Comprehensive 16-page guidebook with all mechanics explained!

Recipe: Book + Stick = Field Guide

[  ] [ ] [  ]
[  ] [B] [  ]
[  ] [S] [  ]

B = Book
S = Stick

Contents:

Introduction & overview
Level progression system
Combat abilities reference
AI behaviors explained
Anger system mechanics
Visual crafting recipes
Survival tips & strategies
Loot tables
Multiplayer guide

How to Get:

Craft it using recipe above (NEW: Recipe unlocks automatically!)
Use /ec guide command (all players)
Recipe appears in crafting table by default (advancement system)

Truce Tonics & Treaty Elixir 🧪

Brew these items to temporarily pacify the boss:

Item	Duration	Recipe Cost	Use Case
Truce Tonic (Simple)	30 seconds	Honey Bottle + Glow Berries	Quick break
Truce Tonic	45 seconds	+ Regeneration Potion	Exploration time
Truce Tonic (Potent)	90 seconds	+ Golden Apple	Major projects
Treaty Elixir	60 seconds	+ Dragon Breath + Totem + Netherite Scrap	Capture/defeat boss

Effects:

Boss becomes friendly temporarily
Won't attack or annoy you during duration
Treaty Elixir Special: Boss stays vulnerable to attacks (can be killed/captured during truce)
Regular Tonics: Boss is immune to damage during truce
All recipes unlock automatically when you get honey bottle

Crafting Location: Standard crafting table Recipe Book: All recipes shown in field guide with visuals

🎮 COMMANDS SYSTEM

NEW in v1.1.0: Complete command system for players and admins!
EXPANDED in v1.1.1: Boss customization commands with professional naming! Also supports /ec shorthand!

Player Commands:

Command	Permission	Description
`/ec guide`	All players	Receive Companion Field Guide book

Admin Commands - Boss Management (OP Level 2):

Command	Description	Example
`/ec remove-boss <player>`	Completely remove a player's boss	`/ec remove-boss Steve`
`/ec set-level <player> <level>`	Change boss level (1-1000)	`/ec set-level Alex 50`
`/ec disable-boss <player>`	Disable boss spawning for player	`/ec disable-boss Steve`
`/ec enable-boss <player>`	Enable boss spawning (note below)	`/ec enable-boss Steve`
`/ec spawn-boss <player>`	Force spawn/assign boss for player	`/ec spawn-boss Alex`
`/ec reload`	Reload configuration file in-game	`/ec reload`

Admin Commands - Customization (OP Level 2): NEW in v1.1.1

Command	Description	Example
`/ec set-name <player> <name>`	Change a boss's name dynamically	`/ec set-name Steve "The Destroyer"`
`/ec set-texture <player> <normal\|hostile> <path>`	Set custom texture for player boss	`/ec set-texture Alex hostile mypack:angry.png`
`/ec set-texture all <normal\|hostile> <path>`	Set texture for ALL active bosses	`/ec set-texture all normal minecraft:textures/entity/zombie/zombie.png`
`/ec reassign-boss <fromPlayer> <toPlayer>`	Transfer boss ownership between players	`/ec reassign-boss Steve Alex`

Features:

Tab completion for player names
Permission level 2 required for admin commands
Confirmation messages for all actions
Works in both single-player and multiplayer
Respects server spawn mode (SHARED, PER_PLAYER, RATIO, MANUAL)
NEW: Boss names and textures persist through restarts
NEW: Per-boss customization with admin commands

Use Cases:

Remove Boss: Player wants to reset their companion
Set Level: Test specific difficulty levels or fix issues
Set Boss Name: Create roleplay narratives or character themes
Set Texture: Event-specific appearances or player preferences
Reassign Boss: Transfer bosses when players switch characters or fix assignment issues
Disable Boss: Permanently stop boss from spawning for a player
Enable Boss: Allow boss spawning (requires manual spawn via spawnboss command)
Spawn Boss: Force create boss for player based on server config (clears dragon defeat status)
Reload Config: Apply config changes without restarting server
Get Guide: New players need the field guide book

Important: spawnboss command now automatically clears the dragon defeat status, so you can use it after disableboss without issues!

🎨 BOSS CUSTOMIZATION

NEW in v1.1.1: Full customization control for boss appearance and identity!

Customizable Boss Names:

Configure in config/evil_companion-common.toml:

["Boss Appearance"]
    # List of possible boss names (randomly chosen on spawn)
    # Leave empty to use default names
    # Add your own custom names separated by commas
    bossNames = ["Zyren", "Kaelix", "Vorn", "Drayen", ...]

48 default fantasy names included
Add unlimited custom names to the list
Names persist through level-ups and restarts
Admins can override specific boss names with /evilcompanion setbossname

Custom Textures System:

Three levels of texture customization:

Config-Wide Textures (Global default):

["Boss Appearance"]
    # Texture path for normal/unhostile boss appearance
    # Format: namespace:path/to/texture.png (ResourceLocation format)
    # Leave as 'default' to use default player skin or mod textures
    normalTexturePath = "default"

    # Texture path for hostile boss appearance
    hostileTexturePath = "default"

Per-Boss Textures (Admin override):

/evilcompanion settexture Steve normal mypack:custom/steve_calm.png
/evilcompanion settexture Alex hostile horror:entities/ghost.png

All-Bosses Textures (Event override):

/evilcompanion settexture all hostile event:boss_angry.png

Texture Priority:
Per-Boss Command → Config Global → Default Mod Textures → Player Skin

Texture Path Format:

ResourceLocation format: namespace:path/to/texture.png
Namespace: Your resource pack ID or mod ID
Path: Can be anywhere in your assets/namespace/textures/ folder
Examples:
- minecraft:textures/entity/zombie/zombie.png (vanilla zombie)
- mypack:boss.png (root of your pack's textures)
- evil_companion:textures/entity/player_boss_custom.png (custom in mod)
- horror:entities/evil/ghost.png (nested folders)

How to Add Custom Textures:

Method 1: Resource Pack (Recommended)

Create folder: .minecraft/resourcepacks/MyBossPack/
Add pack.mcmeta:

{
  "pack": {
    "pack_format": 15,
    "description": "Custom Evil Companion Textures"
  }
}

Add texture: assets/mypack/textures/boss_evil.png
Enable resource pack in Minecraft
Set in config: hostileTexturePath = "mypack:boss_evil.png"

Method 2: Admin Commands (Quick testing)

/evilcompanion settexture Steve normal minecraft:textures/entity/zombie/zombie.png

Test textures without editing config
Per-player customization
Changes persist through restarts

Customization Use Cases:

Roleplay Servers: Different names/textures per character
Event Servers: Themed bosses for special events
Testing: Quick A/B testing of different appearances
Player Requests: Personalized boss appearances
Thematic Servers: Match server lore/aesthetic

⚙️ CONFIGURATION

Over 50 configurable options to customize your experience!

Key Configuration Options:

Difficulty Settings:

# Base stats (v1.1.0+: Separate health for unhostile vs hostile)
unhostile_base_health = 100.0   # Levels 1-2 (easier)
hostile_base_health = 60.0     # Level 3+ (harder)
health_per_level = 10.0
base_damage = 4.0
damage_per_level = 1.0

# Legacy config (deprecated but kept for compatibility)
base_health = 120.0

# Hits before hostile (default: 3)
hits_until_hostile = 3

# Speed boost threshold (default: 30%)
speed_boost_health_threshold = 30

Balance Tip: Unhostile phase (L1-2) uses higher base health (100 HP) for longer friendly interactions. Hostile phase (L3+) uses lower base health (60 HP) for better challenging combats!

Spawn Mode:

# Options: "SHARED", "PER_PLAYER", "RATIO"
spawn_mode = "SHARED"

# For RATIO mode only
players_per_boss = 2

Behavior Toggles:

# Enable/disable features
can_teleport = true
can_steal_items = true
can_steal_from_inventory = true
can_grief_blocks = true
can_mine_blocks = true
can_spawn_minions = true

# Greed thresholds
inventory_theft_greed = 10
chest_raiding_greed = 20
griefing_greed = 15

Ability Unlock Levels:

speed_boost_level = 3
regeneration_level = 7
resistance_level = 10
fire_aura_level = 12
lightning_level = 15
weather_control_level = 20
strength_level = 30
jump_boost_level = 40

Configuration File Location:

Single-Player/Client:

%appdata%\.minecraft\config\evil_companion-common.toml

Dedicated Server:

<server_folder>/config/evil_companion-common.toml

Applying Config Changes:

Option A: Restart Minecraft/Server (always works)
Option B: Use /evilcompanion reload command (requires OP, NEW in v1.1.0)

Important: Delete old config when upgrading from v1.0.0 to v1.1.0 for balanced progression!

📦 INSTALLATION

Requirements:

Minecraft: 1.20.1
Forge: 47.2.1 or higher
Java: 17 or higher

Installation Steps:

Download the latest version of Evil Companion from CurseForge
Locate your Minecraft installation folder:
- Windows: %appdata%\.minecraft
- macOS: ~/Library/Application Support/minecraft
- Linux: ~/.minecraft
Place the downloaded JAR file into the mods folder
Launch Minecraft with Forge 47.2.1 profile
Verify mod loaded successfully (check mods list in main menu)

First Time Setup:

Join a world or create a new one
Boss will spawn automatically based on config settings
Recommended: Craft the Companion Field Guide immediately (Book + Stick)
Read the guide to understand mechanics

Upgrading from v1.0.0:

Download v1.1.0 JAR file
Delete old config file: config/evil_companion-common.toml
Replace old JAR with new JAR in mods folder
Launch game - new config will generate automatically
Important: Deleting config ensures you get balanced progression formulas!

🔗 COMPATIBILITY

✅ Compatible With:

Performance Mods: OptiFine, Sodium, Phosphor, Lithium
World Gen Mods: Biomes O' Plenty, Terralith, Alex's Mobs
Dimension Mods: The Twilight Forest, The Aether
Difficulty Mods: Scaling Health, Infernal Mobs
Quest Mods: FTB Quests, Better Quests
Multiplayer Servers: Forge servers, LAN worlds
Datapack Compatible: Fully supports vanilla datapacks

⚠️ Potential Issues:

Mob AI Mods: Mods that heavily modify entity AI may conflict
Boss Mods: Multiple boss mods may cause balancing issues
Teleportation Blockers: Mods preventing teleportation will affect boss behavior

🛠️ Troubleshooting:

Boss Not Spawning:

Check spawn mode in config (spawn_mode = "SHARED" etc.)
Verify you're in correct dimension (Overworld by default)
Try /evilcompanion setlevel <player> 1 to force spawn

Performance Issues:

Reduce minion spawn count in config
Increase minion spawn cooldown
Disable particle effects in config
Lower render distance

Config Not Loading:

Ensure file is in correct location: config/evil_companion-common.toml
Check for syntax errors in TOML file
Use /evilcompanion reload command after editing
Restart game if reload doesn't work

❓ FREQUENTLY ASKED QUESTIONS

General Questions:

Q: Can I remove the boss permanently?
A: Yes! Use /evilcompanion removeboss <player> (requires OP). Truce items only provide temporary peace (30-90 seconds).

Q: Does the boss respawn after death?
A: Yes, the boss respawns after 30+ seconds (5 seconds in End dimension). It remembers its level and equipment.

Q: Can I have multiple bosses?
A: Yes! Use spawn_mode = "PER_PLAYER" for one boss per player, or spawn_mode = "RATIO" for balanced spawning.

Q: Is this mod balanced for multiplayer?
A: Absolutely! Three spawn modes (SHARED, PER_PLAYER, RATIO) adapt to any server size. v1.1.0 includes major balance improvements.

Q: Can I disable annoying features?
A: Yes! Configure can_teleport, can_steal_items, can_grief_blocks in config file.

Gameplay Questions:

Q: How do I prevent the boss from becoming hostile?
A: Don't hit it! If you accidentally hit it, use a Truce Tonic to reset hostility.

Q: Can I use traps to kill it?
A: Early levels yes, but it breaks blocks to escape. Level 10+ breaks anything except bedrock. Best strategy: direct combat + mobility.

Q: What's the best way to fight high-level bosses?
A: Balanced approach: Netherite armor (Protection IV), Netherite sword (Sharpness V), Shield, Golden Apples, Potions (Strength, Regeneration), Totems of Undying.

Q: Does it steal my items when I die?
A: No, it only steals from dropped items on ground and directly from your inventory (when greed is high).

Q: Can it break my base?
A: Only if greed is high (15+) or it's trapped. It stops griefing when it can reach you directly (v1.1.0).

Q: Can the boss break End portals or bedrock?
A: No! The boss never breaks or replaces: bedrock, End portals, End portal frames, End gateways, barriers, or command blocks. Your portal home is always safe.

📝 CHANGELOG

v1.1.0 - November 3, 2025

⚖️ Balanced Progression: Diminishing returns system for fair fights
🎨 Enhanced Animations: Shield crouch and blocking animations
🤺 Improved AI: Climbing, door usage, monster combat
📘 Complete Guide: 16-page field guide book
🎮 Commands: Admin and player commands
📦 Recipe Fix: Auto-unlock recipes in crafting table
🐛 Bug Fixes: Armor rendering, shield spam, AI behavior

🙏 CREDITS

Developer: zaber-dev

Special Thanks:

Minecraft Forge team for the excellent modding framework
CurseForge community for feedback and bug reports
All players who tested and provided balance suggestions
Content creators who showcased the mod

Inspiration:

Traditional boss mods (Wither, Ender Dragon)
Annoying companion tropes from RPGs
Player vs Player dynamic combat

📜 LICENSE

Summary:

✅ Play and enjoy the mod
✅ Use in modpacks (with credit)
✅ Create content (videos, streams)
❌ Reupload or redistribute
❌ Claim ownership or modification

🎉 FINAL WORDS

Thank you for choosing Evil Companion! This mod represents months of development, balancing, and community feedback. Version 1.1.0 brings major improvements to make the experience fair and fun for everyone.

Whether you're playing solo or with friends, at Level 1 or Level 1000, we hope you enjoy the unique challenge of having a mischievous friend turned ultimate rival.

Good luck, and remember: Every hit counts. Every level matters. Every fight is personal. 😈