CapsulaX is a Minecraft plugin that allows players to capture creatures in special capsules (eggs) and release them whenever they want. Similar to Pokémon mechanics, players can throw capsules at mobs to capture them, store them in their inventory, and release them later.

Key Features

✅ Capture any mob - Over 100+ different creature types supported
✅ Configurable probabilities - Customize capture rates by mob category
✅ Crafting system - Players can craft their own capsules
✅ Economy integration - Buy/sell capsules with Vault
✅ World management - Control where capsules can be used
✅ Visual effects - Particles and sounds for captures
✅ Multilingual - Supports English and Spanish (expandable)
✅ Permissions - Granular control per mob type

📦 Installation

Requirements

Server Type: Paper, Spigot, or any Paper/Spigot fork
Minecraft Version: 1.21.4 or higher
Java Version: 17 or higher

Optional Dependencies

Vault - For economy features (buying capsules)
WorldGuard - For region protection (planned)
MythicMobs - For custom mob support (planned)

Installation Steps

Download CapsulaX.jar from the release page
Stop your server
Place the .jar file in your plugins/ folder
Start your server
Configure the plugin in plugins/CapsulaX/config.yml
Reload with /capsulax reload

🚀 Getting Started

First Steps

After installing CapsulaX, follow these steps:

Give yourself a capsule:
```
/capsulax give <your_name> 10
```
Check available mobs:
```
/capsulax list
```
Find a mob in your world
Throw the capsule at the mob or right-click on it
If successful, the mob will be captured and you'll receive a filled capsule
Right-click with the filled capsule to release the mob

🔨 Crafting Capsules

Default Recipe

Players can craft capture capsules using the following recipe:

[I] [I] [I]
[I] [G] [I]
[I] [I] [I]

I = Iron Ingot
G = Glass Block

Result: 8 Capture Capsules

Recipe Details

Pattern: 3x3 crafting table
Center: 1 Glass Block
Surrounding: 8 Iron Ingots
Output: 8 Empty Capsules

Customizing the Recipe

You can change the recipe in config.yml:

crafting:
  enabled: true
  pattern:
    - "III"
    - "IGI" 
    - "III"
  ingredients:
    I: "IRON_INGOT"
    G: "GLASS"
  result-amount: 8

Example - Diamond Recipe:

crafting:
  enabled: true
  pattern:
    - "DDD"
    - "DGD" 
    - "DDD"
  ingredients:
    D: "DIAMOND"
    G: "GLASS"
  result-amount: 4

Disabling Crafting

Set enabled: false in the crafting section:

crafting:
  enabled: false

Players will only be able to get capsules through commands or economy.

🎯 How to Use Capsules

Capturing Mobs

There are two methods to capture mobs:

Method 1: Throwing Capsules (Recommended)

Hold an empty capsule in your hand
Aim at the mob you want to capture
Throw the capsule (right-click)
The capsule will fly toward the mob
If it hits the mob, capture attempt begins

Advantages:

✅ Safer - capture from distance
✅ Works on fast or dangerous mobs
✅ More immersive gameplay

Method 2: Direct Click

Hold an empty capsule in your hand
Right-click directly on the mob
Capture attempt begins immediately

Advantages:

✅ More precise
✅ Works better in tight spaces
✅ Doesn't consume capsule if capture fails

Capture Success or Failure

When you attempt to capture a mob:

✅ Success:

Mob disappears
You receive a filled capsule with the mob inside
Success sound and particles appear
Capture statistics are recorded

❌ Failure:

Mob escapes
Capsule is consumed
Failure sound plays
Mob may move randomly

Releasing Mobs

To release a captured mob:

Hold the filled capsule in your hand
Right-click in the air or on a block
The mob will spawn at your location
You receive an empty capsule back

Notes:

The mob spawns with the same health and attributes
Baby mobs stay baby, tamed wolves stay tamed, etc.
You cannot release mobs in protected worlds (if configured)

📊 Capture Probability System

CapsulaX uses a sophisticated probability system based on several factors:

Base Capture Chance

Default: 70% (configurable in config.yml)

capsules:
  base-capture-chance: 0.7  # 70%

Mob Categories

Different mob types have different capture multipliers:

1. Passive Mobs (100% of base)

Multiplier: 1.0 → 70% capture rate

Cow, Pig, Sheep, Chicken
Horse, Donkey, Llama
Cat, Wolf, Rabbit
Villagers, Iron Golems
Fox, Panda, Bee

2. Hostile Mobs (70% of base)

Multiplier: 0.7 → 49% capture rate

Zombie, Skeleton, Creeper
Spider, Cave Spider
Enderman, Witch, Blaze
Ghast, Slime, Phantom
Pillager, Vindicator, Evoker

3. Water Mobs (60% of base)

Multiplier: 0.6 → 42% capture rate

Squid, Glow Squid
Dolphin, Turtle
Guardian, Elder Guardian
Fish (Cod, Salmon, Tropical Fish, Pufferfish)
Axolotl

4. Nether Mobs (40% of base)

Multiplier: 0.4 → 28% capture rate

Piglin, Piglin Brute
Hoglin, Zoglin
Zombified Piglin
Wither Skeleton
Magma Cube, Strider

5. End Mobs (30% of base)

Multiplier: 0.3 → 21% capture rate

Shulker
Endermite

6. Boss Mobs (10% of base - Disabled by default)

Multiplier: 0.1 → 7% capture rate

Ender Dragon
Wither
Elder Guardian
Warden

Health-Based Multiplier

The mob's current health affects capture chance:

Formula:

Health Multiplier = 1.0 - (Current Health / Max Health) × 0.5

Examples:

Mob at 100% health: multiplier = 0.5 (50% capture rate)
Mob at 50% health: multiplier = 0.75 (75% capture rate)
Mob at 10% health: multiplier = 0.95 (95% capture rate)
Mob at 1 HP: multiplier = 0.99 (99% capture rate)

💡 Strategy: Damage mobs before capturing them for better success rates!

Final Calculation

The final capture chance is:

Final Chance = Base Chance × Category Multiplier × Health Multiplier

Example 1 - Healthy Cow:

Base: 70%
Category (Passive): 100%
Health: 50%
Final: 35%

Example 2 - Damaged Zombie:

Base: 70%
Category (Hostile): 70%
Health: 75% (mob at 50% HP)
Final: 36.75%

Example 3 - Nearly Dead Creeper:

Base: 70%
Category (Hostile): 70%
Health: 95% (mob at 10% HP)
Final: 46.55%

Custom Overrides

You can override specific mob probabilities:

capsules:
  overrides:
    CREEPER: 0.9    # 90% catch rate for Creepers
    ZOMBIE: 0.5     # 50% catch rate for Zombies
    ENDER_DRAGON: 0.01  # 1% catch rate for Dragon

⚙️ Configuration Guide

The main configuration file is located at: plugins/CapsulaX/config.yml

General Settings

general:
  language: es  # Language: 'es' or 'en'
  update-check: true  # Check for updates on startup

Capsule Settings

capsules:
  item: EGG  # Item type for capsules (EGG, SNOWBALL, etc.)
  display-name: "&6Capture Capsule"
  lore:
    - "&7Throw this capsule at a creature"
    - "&7to attempt to capture it."
    - ""
    - "&eCatch 'em all!"
  projectile-type: EGG  # Projectile type when thrown
  base-capture-chance: 0.7  # 70% base chance

Sound Effects

sounds:
  enabled: true
  capture-success: ENTITY_PLAYER_LEVELUP  # Sound on success
  capture-fail: ENTITY_ENDERMAN_TELEPORT  # Sound on failure
  volume: 1.0
  pitch: 1.0

Available sounds: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Sound.html

Particle Effects

particles:
  enabled: true
  capture-particle: HEART  # Particle type
  amount: 10  # Number of particles
  radius: 1.0  # Spread radius

Available particles: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Particle.html

Storage Settings

storage:
  type: YAML  # YAML, MYSQL, or SQLITE
  
  # MySQL settings (if type: MYSQL)
  mysql:
    host: localhost
    port: 3306
    database: minecraft
    username: user
    password: password
    table-prefix: capsulax_
  
  # SQLite settings (if type: SQLITE)
  sqlite:
    filename: capsulax.db

Debug Settings

debug:
  verbose-logging: false  # Detailed console logs
  log-captures: true  # Log capture attempts
  log-releases: true  # Log mob releases

🌍 World Management

CapsulaX includes a flexible world management system with three modes:

Mode 1: ALL (Allow All Worlds)

Default mode - Capsules work in all worlds

worlds:
  mode: ALL

Use case: Simple servers, vanilla gameplay

Mode 2: WHITELIST (Allow Specific Worlds)

Only allows capsules in listed worlds

worlds:
  mode: WHITELIST
  enabled-worlds:
    - world
    - world_nether
    - world_the_end
    - custom_survival
    - resource_world

Use case:

Servers with many worlds
Strict control needed
Want to block new worlds by default

Advantages:

✅ New worlds are automatically blocked
✅ Maximum control
✅ Ideal for large servers

Mode 3: BLACKLIST (Block Specific Worlds)

Allows capsules in all worlds EXCEPT listed ones

worlds:
  mode: BLACKLIST
  disabled-worlds:
    - lobby
    - spawn
    - hub
    - creative_world
    - minigames

Use case:

Most worlds allow capsules
Only need to block specific worlds (lobby, spawn, etc.)
Want new worlds to allow capsules by default

Advantages:

✅ New worlds automatically allow capsules
✅ Less configuration maintenance
✅ Flexible for growing servers

World Names

⚠️ Important: World names are case-sensitive!

Correct: world, world_nether, MyCustomWorld
Wrong: World, WORLD_NETHER, mycustomworld

How to find exact world names:

Look in your server's root folder
World folders = world names
Or use /mv list if using Multiverse

💰 Economy System

Requires Vault plugin installed.

Configuration

economy:
  enabled: true
  capsule-price: 100.0  # Price per capsule
  
  # Rewards for capturing rare mobs
  capture-rewards:
    ENDER_DRAGON: 10000.0
    WITHER: 5000.0
    ELDER_GUARDIAN: 3000.0
    WARDEN: 2500.0

Buying Capsules

Players can buy capsules with in-game money:

/capsulax buy [amount]

Examples:

/capsulax buy      → Buy 1 capsule for $100
/capsulax buy 5    → Buy 5 capsules for $500
/capsulax buy 64   → Buy 64 capsules for $6400

Capture Rewards

When a player captures a rare mob (if configured), they receive money:

Ender Dragon: $10,000
Wither: $5,000
Elder Guardian: $3,000
Warden: $2,500

Customize rewards in config.yml under economy.capture-rewards.

📜 Commands

Main Command

/capsulax [subcommand]

Aliases: /cx, /capsula

Available Subcommands

1. Give Capsules

/capsulax give <player> [mob] [amount]

Permission: capsulax.command.give

Examples:

# Give 10 empty capsules to Steve
/capsulax give Steve 10

# Give 5 empty capsules to Steve
/capsulax give Steve 5

# Give 1 capsule with a Cow to Steve
/capsulax give Steve COW 1

# Give 3 capsules with Creepers to Alex
/capsulax give Alex CREEPER 3

2. List Capturable Mobs

/capsulax list [page]

Permission: capsulax.command.list

Examples:

/capsulax list      # Show page 1
/capsulax list 2    # Show page 2
/capsulax list 5    # Show page 5

Shows all mobs that can be captured with their capture rates.

3. Buy Capsules

/capsulax buy [amount]

Permission: capsulax.command.buy
Requires: Vault + Economy plugin

Examples:

/capsulax buy       # Buy 1 capsule
/capsulax buy 10    # Buy 10 capsules
/capsulax buy 64    # Buy 64 capsules (max)

4. Reload Configuration

/capsulax reload

Permission: capsulax.command.reload

Reloads all configuration files without restarting the server.

Reloads:

config.yml
messages files
crafting recipes
world settings

5. Help

/capsulax help

Permission: capsulax.command

Shows all available commands based on your permissions.

🔐 Permissions

Basic Permissions

Permission	Description	Default
`capsulax.command`	Use /capsulax command	Everyone
`capsulax.command.give`	Give capsules to players	OP
`capsulax.command.reload`	Reload configuration	OP
`capsulax.command.list`	List capturable mobs	Everyone
`capsulax.command.buy`	Buy capsules	Everyone

Capture Permissions

Control which mobs players can capture:

Individual Mob Permissions

capsulax.capture.<mob_name>

Examples:

# Allow capturing specific mobs
permissions:
  - capsulax.capture.cow
  - capsulax.capture.pig
  - capsulax.capture.chicken
  - capsulax.capture.zombie
  - capsulax.capture.creeper

Wildcard Permission

capsulax.capture.*

Allows capturing all mobs (including bosses if enabled)

Release Permissions

Control which mobs players can release:

capsulax.spawn.<mob_name>

Default Behavior: If a player has permission to capture a mob, they automatically have permission to release it. This is logical - if you can catch it, you should be able to release it!

Permission Hierarchy:

capsulax.capture.<mob> → Automatically grants release permission
capsulax.spawn.<mob> → Explicit release permission
capsulax.spawn.* → Release all mobs (default: true)

Examples:

# Player with capture permission can automatically release
permissions:
  - capsulax.capture.cow  # Can capture AND release cows

# Or use explicit spawn permission
permissions:
  - capsulax.spawn.cow    # Can release cows
  - capsulax.spawn.zombie # Can release zombies
  - capsulax.spawn.*      # Can release all mobs (DEFAULT)

Important: The capsulax.spawn.* permission is enabled by default for all players, so normal players can release any mob they capture.

Crafting Permissions

capsulax.crafting.capsule

Default: OP only

Players need this permission to craft capsules.

Permission Groups Example

For LuckPerms:

# Basic player - can only capture passive mobs
lp group default permission set capsulax.command true
lp group default permission set capsulax.command.list true
lp group default permission set capsulax.capture.cow true
lp group default permission set capsulax.capture.pig true
lp group default permission set capsulax.capture.sheep true

# VIP - can capture passive + hostile mobs
lp group vip permission set capsulax.capture.zombie true
lp group vip permission set capsulax.capture.skeleton true
lp group vip permission set capsulax.capture.creeper true

# Admin - can capture everything
lp group admin permission set capsulax.capture.* true
lp group admin permission set capsulax.command.give true
lp group admin permission set capsulax.command.reload true

🎨 Custom Configuration

Example 1: High Capture Rates (Easy Mode)

capsules:
  base-capture-chance: 0.95  # 95% base rate
  capture-settings:
    passive:
      multiplier: 1.0
    hostile:
      multiplier: 0.9
    bosses:
      enabled: true
      multiplier: 0.5  # 50% for bosses

Example 2: Hard Mode (Challenging)

capsules:
  base-capture-chance: 0.3  # 30% base rate
  capture-settings:
    passive:
      multiplier: 0.8
    hostile:
      multiplier: 0.4
    bosses:
      enabled: true
      multiplier: 0.05  # 5% for bosses

Example 3: Boss Only Server

capsules:
  base-capture-chance: 0.1
  capture-settings:
    passive:
      enabled: false
    hostile:
      enabled: false
    bosses:
      enabled: true
      multiplier: 1.0

Example 4: Custom Mob Rates

capsules:
  base-capture-chance: 0.7
  overrides:
    # Easy to catch
    CHICKEN: 1.0
    COW: 1.0
    PIG: 1.0
    
    # Medium difficulty
    ZOMBIE: 0.5
    SKELETON: 0.5
    
    # Hard to catch
    CREEPER: 0.3
    ENDERMAN: 0.2
    
    # Very rare
    WITHER: 0.01
    ENDER_DRAGON: 0.005

🔧 Troubleshooting

Capsules don't work in any world

Solutions:

Check worlds.mode in config.yml
If using WHITELIST, make sure your world is listed
Use /capsulax reload after changes
Check console for errors

Capsules work in worlds they shouldn't

Solutions:

Verify world name is spelled correctly (case-sensitive)
If using BLACKLIST, make sure the world is in disabled-worlds
Use /capsulax reload after changes

Capture always fails

Solutions:

Check capture probabilities in config.yml
Increase base-capture-chance
Make sure mob is not in a protected region
Check permissions: capsulax.capture.<mob>

Crafting recipe doesn't work

Solutions:

Check crafting.enabled: true in config
Verify player has permission: capsulax.crafting.capsule
Make sure ingredients are correct
Try /capsulax reload

Economy features don't work

Solutions:

Install Vault plugin
Install an economy plugin (EssentialsX, etc.)
Check economy.enabled: true in config
Restart server after installing Vault

Plugin doesn't load

Solutions:

Check Minecraft version (1.21.4+ required)
Check Java version (Java 17+ required)
Look for errors in console
Make sure you're using Paper or Spigot
Check for conflicting plugins

❓ FAQ

Can I capture player-owned horses/pets?

Yes, but only if the player has the appropriate permissions. Tamed animals keep their owner when captured and released.

Do mobs keep their equipment when captured?

Yes! All mob data is preserved:

Equipment (armor, weapons)
Custom names
Potion effects
Baby/Adult state
Villager professions
And more!

Can I capture Mythic Mobs?

Support for MythicMobs is planned but not yet implemented.

What happens if my inventory is full?

The filled capsule will drop on the ground at your feet.

Can I stack filled capsules?

No, filled capsules cannot stack. Each filled capsule contains unique mob data.

Can I sell filled capsules?

Not directly through the plugin, but players can trade them normally.

Does this work with Multiverse?

Yes! CapsulaX works with any world management plugin.

Can I capture the Ender Dragon?

Only if you enable boss capturing in the config:

capsules:
  capture-settings:
    bosses:
      enabled: true

How do I increase capture rates?

Edit config.yml:

capsules:
  base-capture-chance: 0.95  # Increase this value

Can I disable capsules in specific regions?

WorldGuard integration is planned for future versions. Currently, use world management to disable entire worlds.

Do captured mobs count toward the mob cap?

Released mobs count toward the normal mob cap, same as spawned mobs.

Can I customize the capsule item?

Yes! Change the item type:

capsules:
  item: SNOWBALL  # or any other item
  projectile-type: SNOWBALL

🎉 Thank You!

Thank you for using CapsulaX! We hope you and your players enjoy capturing and collecting creatures in Minecraft.

CapsulaX v1.0.1 - Catch 'em all! 🎮

CapsulaX

📖About CapsulaX

Key Features

📦 Installation

Requirements

Optional Dependencies

Installation Steps

🚀 Getting Started

First Steps

🔨 Crafting Capsules

Default Recipe

Recipe Details

Customizing the Recipe

Disabling Crafting

🎯 How to Use Capsules

Capturing Mobs

Method 1: Throwing Capsules (Recommended)

Method 2: Direct Click

Capture Success or Failure

Releasing Mobs

📊 Capture Probability System

Base Capture Chance

Mob Categories

1. Passive Mobs (100% of base)

2. Hostile Mobs (70% of base)

3. Water Mobs (60% of base)

4. Nether Mobs (40% of base)

5. End Mobs (30% of base)

6. Boss Mobs (10% of base - Disabled by default)

Health-Based Multiplier

Final Calculation

Custom Overrides

⚙️ Configuration Guide

General Settings

Capsule Settings

Sound Effects

Particle Effects

Storage Settings

Debug Settings

🌍 World Management

Mode 1: ALL (Allow All Worlds)

Mode 2: WHITELIST (Allow Specific Worlds)

Mode 3: BLACKLIST (Block Specific Worlds)

World Names

💰 Economy System

Configuration

Buying Capsules

Capture Rewards

📜 Commands

Main Command

Available Subcommands

1. Give Capsules

2. List Capturable Mobs

3. Buy Capsules

4. Reload Configuration

5. Help

🔐 Permissions

Basic Permissions

Capture Permissions

Individual Mob Permissions

Wildcard Permission

Release Permissions

Crafting Permissions

Permission Groups Example

🎨 Custom Configuration

Example 1: High Capture Rates (Easy Mode)

Example 2: Hard Mode (Challenging)

Example 3: Boss Only Server

Example 4: Custom Mob Rates

🔧 Troubleshooting

Capsules don't work in any world

Capsules work in worlds they shouldn't

Capture always fails

Crafting recipe doesn't work

Economy features don't work

Plugin doesn't load

❓ FAQ

Can I capture player-owned horses/pets?

Do mobs keep their equipment when captured?

Can I capture Mythic Mobs?