CapsulaX

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

1. Download CapsulaX.jar from the release page 2. Stop your server 3. Place the .jar file in your plugins/ folder 4. Start your server 5. Configure the plugin in plugins/CapsulaX/config.yml 6. Reload with /capsulax reload ---

Getting Started

First Steps

After installing CapsulaX, follow these steps: 1. Give yourself a capsule:

   /capsulax give <your_name> 10
   

2. Check available mobs:

   /capsulax list
   

3. Find a mob in your world 4. Throw the capsule at the mob or right-click on it 5. If successful, the mob will be captured and you'll receive a filled capsule 6. 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) 1. Hold an empty capsule in your hand 2. Aim at the mob you want to capture 3. Throw the capsule (right-click) 4. The capsule will fly toward the mob 5. 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 1. Hold an empty capsule in your hand 2. Right-click directly on the mob 3. 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: 1. Hold the filled capsule in your hand 2. Right-click in the air or on a block 3. The mob will spawn at your location 4. 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…

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/