# ThrowableFireballs<\/p>\n
A highly configurable Minecraft Paper plugin that allows players to throw fireballs as projectiles. Built with multi-version support (1.16.5 through latest Paper) and clean architecture to avoid NMS dependencies.<\/p>\n
## Features<\/p>\n
\u2728 **Throwable Fireballs** – Right-click with a fire charge (or custom item) to launch a fireball projectile
\n\ud83c\udfaf **Configurable Damage** – Separate control for block damage and entity damage
\n\ud83d\udee1\ufe0f **Protection Integration** – WorldGuard soft dependency with fallback protection
\n\u23f1\ufe0f **Anti-Spam Cooldowns** – Per-player cooldowns with action bar messages
\n\ud83c\udfa8 **Fully Customizable** – Everything from item type to explosion power is configurable
\n\ud83d\udc64 **Per-Player Settings** – Players can toggle block damage for their own fireballs
\n\ud83d\udd27 **Multi-Version Support** – Works on Paper 1.16.5+ without NMS
\n\ud83d\udce6 **Easy to Use** – Simple commands and intuitive permissions system<\/p>\n
## Key Feature: Block Damage vs Entity Damage<\/p>\n
**IMPORTANT:** This plugin allows you to **disable block damage while keeping entity\/player damage enabled**. This means:<\/p>\n
– \u2705 Fireballs can damage players and mobs
\n– \u274c Fireballs won’t break blocks or terrain
\n– \u2705 Explosion effects, knockback, and fire still work
\n– \ud83c\udfaf Perfect for PvP servers that want to protect builds<\/p>\n
Configure this in `config.yml`:
\n“`yaml
\nexplosion:
\n block-damage: false # Blocks are safe
\n entity-damage: true # Players still take damage
\n“`<\/p>\n
Players can also toggle block damage for their own fireballs: ## Installation<\/p>\n 1. **Download** the latest release JAR from the releases page ## Requirements<\/p>\n – **Minecraft Server**: Paper 1.21.x (also compatible with 1.16.5 – 1.21.x) ## Commands<\/p>\n | Command | Description | Permission | **Aliases:** `\/tfb`, `\/throwablefireball`<\/p>\n ## Permissions<\/p>\n ### Main Permissions<\/p>\n | Permission | Description | Default | ### Advanced Permissions<\/p>\n | Permission | Description | Default | ## Configuration<\/p>\n The `config.yml` file is extensively documented. Here are the key sections:<\/p>\n ### Item Settings ### Projectile Settings ### Explosion Settings ### Cooldown Settings ### Protection Settings ### Per-Player Settings All messages are customizable with color code support (`&` codes).<\/p>\n ## Multi-Version Support<\/p>\n This plugin is designed to work across multiple Paper versions (1.16.5+) without using NMS (Net Minecraft Server) code.<\/p>\n ### How It Works<\/p>\n The plugin uses a **Version Adapter** pattern:<\/p>\n 1. **VersionAdapter Interface** – Defines version-specific operations (e.g., action bar messages) The plugin automatically detects your server version and uses the appropriate adapter.<\/p>\n ### API Version<\/p>\n In `plugin.yml`, we set `api-version: 1.21` because: ### Supported Versions<\/p>\n | Version | Status | Notes | ## Building from Source<\/p>\n ### Prerequisites ### Build Steps<\/p>\n “`bash # Build with Gradle # The JAR will be in build\/libs\/ThrowableFireballs-1.1.0.jar ### Gradle Tasks<\/p>\n “`bash ## How It Works<\/p>\n ### Throwing Fireballs<\/p>\n 1. Player right-clicks with a fire charge (or configured item) ### Explosion Control<\/p>\n When a fireball explodes:<\/p>\n 1. Plugin checks if it’s tagged as “ours” (via `PersistentDataContainer`) **Critical Detail:** Even when `block-damage: false`, the explosion event is NOT cancelled, so entity damage still occurs naturally through Bukkit’s damage system.<\/p>\n ### Damage Handling<\/p>\n The plugin handles damage in two ways:<\/p>\n 1. **Direct Hit** – `EntityDamageByEntityEvent` with `PROJECTILE` cause 2. **Explosion Damage** – Handled by Minecraft’s explosion system ## Troubleshooting<\/p>\n ### Fireballs Don’t Break Blocks ### Action Bar Messages Don’t Show ### WorldGuard Integration Not Working ### Players Can Spam Fireballs ### Explosions Are Too Weak\/Strong ## Performance<\/p>\n The plugin is designed to be lightweight and performant:<\/p>\n – \u2705 **No tick loops** – Event-driven architecture ## WorldGuard Integration<\/p>\n If WorldGuard is installed:<\/p>\n 1. Plugin detects WorldGuard on startup For now, the plugin respects basic WorldGuard presence and can be extended with full API integration.<\/p>\n ## Development<\/p>\n ### Project Structure<\/p>\n “` ### Adding Features<\/p>\n To add new features:<\/p>\n 1. Add config options to `config.yml` and `ConfigManager.java` ## License<\/p>\n This project is provided as-is for educational and server use. Feel free to modify and use it on your server.<\/p>\n ## Credits<\/p>\n – **Author**: nandoothjuuh ## Support<\/p>\n For issues, questions, or suggestions: —<\/p>\n **Note:** This plugin is designed for Paper servers. While it may work on Spigot, Paper is highly recommended for best performance and compatibility.<\/p>\n","protected":false},"excerpt":{"rendered":" Add configurable, throwable fireballs to your Paper server. With per-player block damage control, PvP-friendly explosions, and full protection support.<\/p>\n","protected":false},"featured_media":156088,"template":"","meta":{"_minecraft_slug":"throwablefireballsplus","_minecraft_project_id":"hYwxRUOV","_minecraft_author":"nandoothjuuh","_minecraft_license":"MIT","_minecraft_downloads":27,"_minecraft_follows":0,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"throwablefireballsplus.zip","_minecraft_size_bytes":93935,"_minecraft_version_count":3,"_minecraft_updated_at":"2026-05-15T22:14:24.797665Z","_minecraft_date_created":"2026-02-11T01:15:32.905194Z","_minecraft_date_modified":"2026-02-10T15:08:04.767533Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/throwablefireballsplus","_minecraft_icon_attachment_id":156088,"_minecraft_imported_at":"2026-06-09T12:22:03+00:00","_minecraft_import_hash":"a7407a1b7a2c24be0046a9124db68f5f","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[125,89,866,127,128,92],"mod_loader":[131,132,133],"minecraft_version":[118,119,120,46,47,48,62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-156087","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-folia","mod_category-game-mechanics","mod_category-minigame","mod_category-paper","mod_category-purpur","mod_category-utility","mod_loader-folia","mod_loader-paper","mod_loader-purpur","minecraft_version-1-16","minecraft_version-1-16-1","minecraft_version-1-16-2","minecraft_version-1-16-3","minecraft_version-1-16-4","minecraft_version-1-16-5","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\n“`
\n\/tfireballs blockdamage
\n“`<\/p>\n
\n2. **Place** the JAR file in your server’s `plugins\/` folder
\n3. **Restart** your server (or use a plugin manager)
\n4. **Configure** the plugin in `plugins\/ThrowableFireballs\/config.yml`
\n5. **(Optional)** Install WorldGuard for advanced region protection<\/p>\n
\n– **Java**: 21 or newer (Java 17 minimum)
\n– **Optional**: WorldGuard 7.0+ for region protection<\/p>\n
\n|———|————-|————|
\n| `\/tfireballs reload` | Reload configuration | `throwablefireballs.admin` |
\n| `\/tfireballs give
\n| `\/tfireballs blockdamage
\n|————|————-|———|
\n| `throwablefireballs.*` | Grant all permissions | op |
\n| `throwablefireballs.use` | Throw fireballs | true (everyone) |
\n| `throwablefireballs.admin` | Access admin commands | op |<\/p>\n
\n|————|————-|———|
\n| `throwablefireballs.bypasscooldown` | Bypass throw cooldown | op |
\n| `throwablefireballs.bypassprotection` | Bypass region protection | op |
\n| `throwablefireballs.blockdamage.toggle` | Toggle personal block damage | true |<\/p>\n
\n“`yaml
\nitem:
\n material: FIRE_CHARGE # Item to throw
\n consume-on-throw: true # Consume item?
\n consume-in-creative: false # Consume in creative?
\n custom-model-data: # For resource packs
\n enabled: false
\n value: 0
\n“`<\/p>\n
\n“`yaml
\nprojectile:
\n type: SMALL # SMALL or LARGE
\n speed: 1.5 # Velocity multiplier
\n“`<\/p>\n
\n“`yaml
\nexplosion:
\n block-damage: false # Break blocks?
\n entity-damage: true # Damage players\/mobs?
\n power: 1.0 # Explosion radius
\n create-fire: true # Create fire?
\n fire-ticks: 100 # Fire duration
\n“`<\/p>\n
\n“`yaml
\ncooldown:
\n time-millis: 1000 # 1 second cooldown
\n show-actionbar: true # Show message?
\n“`<\/p>\n
\n“`yaml
\nprotection:
\n respect-worldguard: true # Use WorldGuard?
\n check-build-permission: true # Basic protection
\n“`<\/p>\n
\n“`yaml
\nper-player-settings:
\n allow-block-damage-toggle: true # Players can toggle?
\n“`<\/p>\n
\n2. **ModernVersionAdapter** – Uses Paper’s Adventure API (1.16.5+)
\n3. **LegacyVersionAdapter** – Reflection-based fallback for older versions<\/p>\n
\n– Version 1.1.0 targets Minecraft 1.21.x
\n– Maintains backward compatibility with 1.16.5+ due to no NMS usage
\n– Paper’s API is stable across versions
\n– Modern features and optimizations available in 1.21<\/p>\n
\n|———|——–|——-|
\n| 1.16.5 | \u2705 Compatible | Minimum supported |
\n| 1.17.x | \u2705 Compatible | Uses modern adapter |
\n| 1.18.x | \u2705 Compatible | Uses modern adapter |
\n| 1.19.x | \u2705 Compatible | Uses modern adapter |
\n| 1.20.x | \u2705 Compatible | Uses modern adapter |
\n| 1.21.x | \u2705 Tested | **Primary target** |
\n| Future | \u2705 Should work | No NMS dependencies |<\/p>\n
\n– Java 17 JDK or newer
\n– Git<\/p>\n
\n# Clone the repository
\ngit clone https:\/\/github.com\/nando123412\/ThrowableFireballs.git
\ncd ThrowableFireballs<\/p>\n
\n.\/gradlew build<\/p>\n
\n“`<\/p>\n
\n.\/gradlew clean # Clean build directory
\n.\/gradlew build # Build JAR (includes shadowJar)
\n.\/gradlew shadowJar # Build shaded JAR with dependencies
\n“`<\/p>\n
\n2. Plugin checks:
\n – Permission (`throwablefireballs.use`)
\n – Cooldown (unless bypassed)
\n – Item validity (material, custom model data, display name)
\n – Region protection (WorldGuard or basic checks)
\n3. Fireball is spawned with:
\n – Player’s eye direction
\n – Configured velocity
\n – Tagged with `PersistentDataContainer` (player UUID stored)
\n4. Item is consumed (if configured)
\n5. Cooldown is applied<\/p>\n
\n2. If not tagged, explosion proceeds normally (vanilla behavior)
\n3. If tagged:
\n – Gets the player UUID from the tag
\n – Checks per-player settings (if enabled)
\n – Falls back to global config
\n – **Block Damage**: If disabled, clears block list and sets yield to 0
\n – **Entity Damage**: If disabled, cancels damage events
\n – **Fire**: Applies fire ticks if configured<\/p>\n
\n – Applies custom damage if configured
\n – Can be disabled with `entity-damage: false`<\/p>\n
\n – Works automatically when explosion is not cancelled
\n – Controlled by `entity-damage` config option<\/p>\n
\n**Solution:** This is intentional if `explosion.block-damage: false` in config. Players still take damage.<\/p>\n
\n**Solution:** The plugin uses Adventure API (Paper 1.16.5+). If using older Spigot, messages fall back to chat.<\/p>\n
\n**Solution:** Ensure WorldGuard 7.0+ is installed and `protection.respect-worldguard: true` in config.<\/p>\n
\n**Solution:** Reduce `cooldown.time-millis` or ensure players don’t have `throwablefireballs.bypasscooldown` permission.<\/p>\n
\n**Solution:** Adjust `explosion.power` in config. Vanilla TNT is 4.0, Creeper is 3.0.<\/p>\n
\n– \u2705 **Minimal reflection** – Only for action bars on legacy versions
\n– \u2705 **Efficient cooldowns** – HashMap-based with cleanup
\n– \u2705 **No database** – All data in memory
\n– \u2705 **PersistentDataContainer** – Uses Bukkit’s built-in tagging system<\/p>\n
\n2. Basic region checks are performed
\n3. **Note:** Full WorldGuard integration requires additional API usage
\n4. Server admins can use WorldGuard flags to control fireball behavior:
\n – `creeper-explosion` flag
\n – `ghast-fireball` flag
\n – Custom flags (requires WorldGuard configuration)<\/p>\n
\nsrc\/main\/java\/com\/nandoothjuuh\/throwablefireballs\/
\n\u251c\u2500\u2500 ThrowableFireballsPlugin.java # Main plugin class
\n\u251c\u2500\u2500 commands\/
\n\u2502 \u251c\u2500\u2500 TFireballsCommand.java # Command executor
\n\u2502 \u2514\u2500\u2500 TFireballsTabCompleter.java # Tab completion
\n\u251c\u2500\u2500 compat\/
\n\u2502 \u251c\u2500\u2500 VersionAdapter.java # Version adapter interface
\n\u2502 \u251c\u2500\u2500 ModernVersionAdapter.java # Adventure API (1.16.5+)
\n\u2502 \u2514\u2500\u2500 LegacyVersionAdapter.java # Reflection fallback
\n\u251c\u2500\u2500 config\/
\n\u2502 \u251c\u2500\u2500 ConfigManager.java # Config wrapper
\n\u2502 \u2514\u2500\u2500 MessageManager.java # Message handler
\n\u251c\u2500\u2500 cooldown\/
\n\u2502 \u2514\u2500\u2500 CooldownManager.java # Cooldown tracking
\n\u251c\u2500\u2500 items\/
\n\u2502 \u2514\u2500\u2500 FireballItemFactory.java # Item creation
\n\u251c\u2500\u2500 listeners\/
\n\u2502 \u251c\u2500\u2500 ThrowListener.java # Throw event handler
\n\u2502 \u2514\u2500\u2500 ExplosionControlListener.java # Explosion control
\n\u2514\u2500\u2500 util\/
\n \u2514\u2500\u2500 TextUtil.java # Text utilities
\n“`<\/p>\n
\n2. Add messages to `config.yml` and `MessageManager.java`
\n3. Create new listeners or modify existing ones
\n4. Register listeners in `ThrowableFireballsPlugin.java`
\n5. Add permissions to `plugin.yml`
\n6. Update README.md<\/p>\n
\n– **Plugin API**: Paper\/Spigot\/Bukkit
\n– **Built with**: Java 17, Gradle<\/p>\n
\n– Open an issue on GitHub
\n– Check the wiki for detailed guides
\n– Join the community Discord (if available)<\/p>\n