1.0.0
release
CapsulaX
CapsulaX is a Minecraft plugin that allows players to capture creatures in special capsules and then release them whenever they want.
70
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
- ✅ Permissions - Over 100+ different creature types supported - ✅ Permissions - Customize capture rates by mob category - ✅ Permissions - Players can craft their own capsules - ✅ Permissions - Buy/sell capsules with Vault - ✅ Permissions - Control where capsules can be used - ✅ Permissions - Particles and sounds for captures - ✅ Permissions - Supports English and Spanish (expandable) - ✅ Permissions - Granular control per mob type
---
📦 Installation
Requirements
- Java Version: Paper, Spigot, or any Paper/Spigot fork - Java Version: 1.21.4 or higher - Java Version: 17 or higher
Optional Dependencies
- MythicMobs - For economy features (buying capsules) - MythicMobs - For region protection (planned) - MythicMobs - For custom mob support (planned)
Installation Steps
1. Reload CapsulaX.jar from the release page 2. Reload your server 3. Reload the .jar file in your `plugins/` folder 4. Reload your server 5. Reload 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
- Output: 3x3 crafting table - Output: 1 Glass Block - Output: 8 Iron Ingots - Output: 8 Empty Capsules
Customizing the Recipe
You can change the recipe in `config.yml`:
```yaml crafting: enabled: true pattern: - "III" - "IGI" - "III" ingredients: I: "IRON_INGOT" G: "GLASS" result-amount: 8 ```
Example - Diamond Recipe: ```yaml crafting: enabled: true pattern: - "DDD" - "DGD" - "DDD" ingredients: D: "DIAMOND" G: "GLASS" result-amount: 4 ```
Disabling Crafting
Set `enabled: false` in the crafting section: ```yaml 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. If it hits an empty capsule in your hand 2. If it hits at the mob you want to capture 3. If it hits 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. Right-click 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. Right-click 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`)
```yaml capsules: base-capture-chance: 0.7 # 70% ```
Mob Categories
Different mob types have different capture multipliers:
1. Passive Mobs (100% of base)
70% capture rate 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)
49% capture rate 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)
42% capture rate 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)
28% capture rate 0.4 → 28% capture rate
- Piglin, Piglin Brute - Hoglin, Zoglin - Zombified Piglin - Wither Skeleton - Magma Cube, Strider
5. End Mobs (30% of base)
21% capture rate 0.3 → 21% capture rate
- Shulker - Endermite
6. Boss Mobs (10% of base - Disabled by default)
7% capture rate 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 ```
Final: 35% - Base: 70% - Category (Passive): 100% - Health: 50% - Final: 35%
Final: 36.75% - Base: 70% - Category (Hostile): 70% - Health: 75% (mob at 50% HP) - Final: 36.75%
Final: 46.55% - Base: 70% - Category (Hostile): 70% - Health: 95% (mob at 10% HP) - Final: 46.55%
Custom Overrides
You can override specific mob probabilities:
```yaml 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
```yaml general: language: es # Language: 'es' or 'en' update-check: true # Check for updates on startup ```
Capsule Settings
```yaml 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
```yaml 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
```yaml 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
```yaml 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
```yaml 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
```yaml worlds: mode: ALL ```
Use case: Simple servers, vanilla gameplay
---
Mode 2: WHITELIST (Allow Specific Worlds)
Only allows capsules in listed worlds
```yaml 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
```yaml 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
⚠️ case-sensitive World names are case-sensitive!
- Correct: `world`, `world_nether`, `MyCustomWorld` - Wrong: `World`, `WORLD_NETHER`, `mycustomworld`
How to find exact world names: 1. Look in your server's root folder 2. World folders = world names 3. Or use `/mv list` if using Multiverse
---
💰 Economy System
Requires Vault plugin installed.
Configuration
```yaml 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: ```bash
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: ```bash /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] ```
Requires: `capsulax.command.buy` Requires: Vault + Economy plugin
Examples: ```bash /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: ```yaml
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> ```
release If a player has permission to release 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: 1. `capsulax.capture.<mob>` → Automatically grants release permission 2. `capsulax.spawn.<mob>` → Explicit release permission 3. `capsulax.spawn.*` → Release all mobs (default: true)
Examples: ```yaml
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) ```
enabled by default 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:
```bash
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)
```yaml 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)
```yaml 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
```yaml 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
```yaml 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: 1. Check `worlds.mode` in config.yml 2. If using WHITELIST, make sure your world is listed 3. Use `/capsulax reload` after changes 4. Check console for errors
---
Capsules work in worlds they shouldn't
Solutions: 1. Verify world name is spelled correctly (case-sensitive) 2. If using BLACKLIST, make sure the world is in `disabled-worlds` 3. Use `/capsulax reload` after changes
---
Capture always fails
Solutions: 1. Check capture probabilities in config.yml 2. Increase `base-capture-chance` 3. Make sure mob is not in a protected region 4. Check permissions: `capsulax.capture.<mob>`
---
Crafting recipe doesn't work
Solutions: 1. Check `crafting.enabled: true` in config 2. Verify player has permission: `capsulax.crafting.capsule` 3. Make sure ingredients are correct 4. Try `/capsulax reload`
---
Economy features don't work
Solutions: 1. Install Vault plugin 2. Install an economy plugin (EssentialsX, etc.) 3. Check `economy.enabled: true` in config 4. Restart server after installing Vault
---
Plugin doesn't load
Solutions: 1. Check Minecraft version (1.21.4+ required) 2. Check Java version (Java 17+ required) 3. Look for errors in console 4. Make sure you're using Paper or Spigot 5. 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: ```yaml capsules: capture-settings: bosses: enabled: true ```
---
How do I increase capture rates?
Edit `config.yml`: ```yaml 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: ```yaml 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! 🎮
Gallery
Versions
1.0.1
release