ThrowableFireballs
一个高度可配置的 Minecraft Paper 插件,允许玩家投掷火球作为投射物。采用多版本支持(1.16.5 至最新 Paper)和清晰的架构构建,以避免依赖 NMS。
功能
✨ 可投掷的火球 - 右键点击火焰弹(或自定义物品)以发射火球投射物
? 可配置的伤害 - 分别控制方块伤害和实体伤害
?️ 保护集成 - 软依赖 WorldGuard 并提供备用保护机制
⏱️ 防刷屏冷却 - 每个玩家的独立冷却时间,并显示动作栏消息
? 完全可定制 - 从物品类型到爆炸威力均可配置
? 玩家个人设置 - 玩家可以为自己投掷的火球切换方块伤害
? 多版本支持 - 在 Paper 1.16.5+ 上无需 NMS 即可运行
? 易于使用 - 简单的命令和直观的权限系统
核心功能:方块伤害与实体伤害
重要提示: 本插件允许您禁用方块伤害,同时保持对实体/玩家的伤害。这意味着:
- ✅ 火球可以伤害玩家和生物
- ❌ 火球不会破坏方块或地形
- ✅ 爆炸效果、击退和着火仍然有效
- ? 非常适合希望保护建筑的玩家对战服务器
在 config.yml 中配置此选项:
explosion:
block-damage: false # 方块安全
entity-damage: true # 玩家仍会受伤
玩家也可以切换自己投掷的火球的方块伤害:
/tfireballs blockdamage <on|off>
安装
- 下载 发布页面中的最新版本 JAR 文件
- 放置 JAR 文件到服务器的
plugins/ 文件夹中
- 重启 您的服务器(或使用插件管理器)
- 配置 插件,位于
plugins/ThrowableFireballs/config.yml
- (可选) 安装 WorldGuard 以获得高级区域保护
要求
- Minecraft Server: Paper 1.21.x(也兼容 1.16.5 - 1.21.x)
- Java: 21 或更高版本(最低 Java 17)
- 可选: WorldGuard 7.0+ 用于区域保护
命令
| 命令 |
描述 |
权限 |
/tfireballs reload |
重新加载配置 |
throwablefireballs.admin |
/tfireballs give <player> [amount] |
给予火球物品 |
throwablefireballs.admin |
/tfireballs blockdamage <on|off> |
切换自己火球的方块伤害 |
throwablefireballs.blockdamage.toggle |
别名: /tfb, /throwablefireball
权限
主要权限
| 权限 |
描述 |
默认值 |
throwablefireballs.* |
授予所有权限 |
op |
throwablefireballs.use |
投掷火球 |
true (所有人) |
throwablefireballs.admin |
访问管理员命令 |
op |
高级权限
| 权限 |
描述 |
默认值 |
throwablefireballs.bypasscooldown |
绕过投掷冷却 |
op |
throwablefireballs.bypassprotection |
绕过区域保护 |
op |
throwablefireballs.blockdamage.toggle |
切换个人方块伤害 |
true |
配置
config.yml 文件包含大量文档说明。以下是关键部分:
物品设置
item:
material: FIRE_CHARGE # 要投掷的物品
consume-on-throw: true # 投掷时消耗物品?
consume-in-creative: false # 创造模式下是否消耗?
custom-model-data: # 用于资源包
enabled: false
value: 0
投射物设置
projectile:
type: SMALL # SMALL 或 LARGE
speed: 1.5 # 速度倍率
爆炸设置
explosion:
block-damage: false # 破坏方块?
entity-damage: true # 伤害玩家/生物?
power: 1.0 # 爆炸半径
create-fire: true # 产生火焰?
fire-ticks: 100 # 火焰持续时间
冷却设置
cooldown:
time-millis: 1000 # 1 秒冷却时间
show-actionbar: true # 显示消息?
保护设置
protection:
respect-worldguard: true # 使用 WorldGuard?
check-build-permission: true # 基本保护检查
玩家个人设置
per-player-settings:
allow-block-damage-toggle: true # 玩家是否可以切换?
所有消息均支持颜色代码(& 代码),可进行自定义。
多版本支持
本插件设计为在多个 Paper 版本(1.16.5+)上运行,而无需使用 NMS(Net Minecraft Server)代码。
工作原理
插件使用版本适配器模式:
- VersionAdapter 接口 - 定义特定于版本的操作(例如,动作栏消息)
- ModernVersionAdapter - 使用 Paper 的 Adventure API(1.16.5+)
- LegacyVersionAdapter - 基于反射的旧版本回退方案
插件会自动检测您的服务器版本并使用相应的适配器。
API 版本
在 plugin.yml 中,我们设置 api-version: 1.21,因为:
- 版本 1.1.0 针对 Minecraft 1.21.x
- 由于未使用 NMS,保持了与 1.16.5+ 的向后兼容性
- Paper 的 API 在各版本间保持稳定
- 1.21 中提供了现代功能和优化
支持的版本
| 版本 |
状态 |
备注 |
| 1.16.5 |
✅ 兼容 |
最低支持版本 |
| 1.17.x |
✅ 兼容 |
使用现代适配器 |
| 1.18.x |
✅ 兼容 |
使用现代适配器 |
| 1.19.x |
✅ 兼容 |
使用现代适配器 |
| 1.20.x |
✅ 兼容 |
使用现代适配器 |
| 1.21.x |
✅ 已测试 |
主要目标版本 |
| 未来版本 |
✅ 应该可用 |
无 NMS 依赖 |
从源码构建
前提条件
构建步骤
# 克隆仓库
git clone https://github.com/nando123412/ThrowableFireballs.git
cd ThrowableFireballs
# 使用 Gradle 构建
./gradlew build
JAR 文件将位于 build/libs/ThrowableFireballs-1.1.0.jar
### Gradle 任务
```bash
./gradlew clean # 清理构建目录
./gradlew build # 构建 JAR(包含 shadowJar)
./gradlew shadowJar # 构建带有依赖的阴影 JAR
工作原理
投掷火球
- 玩家手持火药粉(或配置的物品)右键点击
- 插件检查:
- 权限 (
throwablefireballs.use)
- 冷却时间(除非被绕过)
- 物品有效性(材质、自定义模型数据、显示名称)
- 区域保护(WorldGuard 或基础检查)
- 生成火球,具备以下属性:
- 玩家的视线方向
- 配置的初速度
- 标记有
PersistentDataContainer(存储玩家 UUID)
- 消耗物品(如果已配置)
- 应用冷却时间
爆炸控制
当火球爆炸时:
- 插件检查其是否被标记为“我们的”(通过
PersistentDataContainer)
- 如果未标记,爆炸按正常流程进行(原版行为)
- 如果已标记:
- 从标签中获取玩家 UUID
- 检查每个玩家的设置(如果启用)
- 回退到全局配置
- 方块伤害:如果禁用,清除方块列表并将掉落物设为 0
- 实体伤害:如果禁用,取消伤害事件
- 火焰:如果配置了则施加燃烧效果
关键细节: 即使 block-damage: false,爆炸事件也不会被取消,因此实体伤害仍会通过 Bukkit 的伤害系统自然发生。
伤害处理
插件以两种方式处理伤害:
-
直接命中 - EntityDamageByEntityEvent,原因类型为 PROJECTILE
- 如果配置了则应用自定义伤害
- 可以通过
entity-damage: false 禁用
-
爆炸伤害 - 由 Minecraft 的爆炸系统处理
- 当爆炸未被取消时自动生效
- 由
entity-damage 配置选项控制
故障排除
火球无法破坏方块
解决方案: 如果配置中设置了 explosion.block-damage: false,这是预期行为。玩家仍然会受到伤害。
动作栏消息不显示
解决方案: 该插件使用 Adventure API(Paper 1.16.5+)。如果使用较旧版本的 Spigot,消息将回退到聊天栏。
WorldGuard 集成不起作用
解决方案: 确保安装了 WorldGuard 7.0+,并在配置中设置 protection.respect-worldguard: true。
玩家可以滥用火球
解决方案: 减少 cooldown.time-millis 的值,或确保玩家没有 throwablefireballs.bypasscooldown 权限。
爆炸威力过弱/过强
解决方案: 调整配置中的 explosion.power。原版 TNT 的威力为 4.0,苦力怕为 3.0。
性能
该插件设计为轻量级且高效:
- ✅ 无 tick 循环 - 基于事件驱动的架构
- ✅ 最小化反射 - 仅在旧版本上用于动作栏
- ✅ 高效的冷却管理 - 基于 HashMap 并带有清理机制
- ✅ 无需数据库 - 所有数据均在内存中
- ✅ PersistentDataContainer - 使用 Bukkit 内置的标记系统
WorldGuard 集成
如果安装了 WorldGuard:
- 插件在启动时检测 WorldGuard
- 执行基本的区域检查
- 注意: 完整的 WorldGuard 集成需要额外的 API 调用
- 服务器管理员可以使用 WorldGuard 标志来控制火球行为:
creeper-explosion 标志
ghast-fireball 标志
- 自定义标志(需要配置 WorldGuard)
目前,该插件尊重基本的 WorldGuard 存在情况,并可通过完整的 API 集成进行扩展。
开发
项目结构
src/main/java/com/nandoothjuuh/throwablefireballs/
├── ThrowableFireballsPlugin.java # 主插件类
├── commands/
│ ├── TFireballsCommand.java # 命令执行器
│ └── TFireballsTabCompleter.java # Tab 补全
├── compat/
│ ├── VersionAdapter.java # 版本适配接口
│ ├── ModernVersionAdapter.java # Adventure API (1.16.5+)
│ └── LegacyVersionAdapter.java # 反射回退方案
├── config/
│ ├── ConfigManager.java # 配置包装器
│ └── MessageManager.java # 消息处理器
├── cooldown/
│ └── CooldownManager.java # 冷却时间追踪
├── items/
│ └── FireballItemFactory.java # 物品创建
├── listeners/
│ ├── ThrowListener.java # 投掷事件处理器
│ └── ExplosionControlListener.java # 爆炸控制
└── util/
└── TextUtil.java # 文本工具
添加功能
要添加新功能:
- 在
config.yml 和 ConfigManager.java 中添加配置选项
- 在
config.yml 和 MessageManager.java 中添加消息
- 创建新监听器或修改现有监听器
- 在
ThrowableFireballsPlugin.java 中注册监听器
- 在
plugin.yml 中添加权限
- 更新 README.md
许可证
本项目按原样提供,仅供教育和服务器使用。您可以自由修改并在您的服务器上使用。
致谢
- 作者: nandoothjuuh
- 插件 API: Paper/Spigot/Bukkit
- 开发环境: Java 17, Gradle
支持
如有问题、疑问或建议:
- 在 GitHub 上提交 Issue
- 查看 Wiki 获取详细指南
- 加入社区 Discord(如果可用)
注意: 此插件专为 Paper 服务器设计。虽然它可能在 Spigot 上也能运行,但强烈建议使用 Paper 以获得最佳性能和兼容性。
ThrowableFireballs
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.
Features
✨ Throwable Fireballs - Right-click with a fire charge (or custom item) to launch a fireball projectile
? Configurable Damage - Separate control for block damage and entity damage
?️ Protection Integration - WorldGuard soft dependency with fallback protection
⏱️ Anti-Spam Cooldowns - Per-player cooldowns with action bar messages
? Fully Customizable - Everything from item type to explosion power is configurable
? Per-Player Settings - Players can toggle block damage for their own fireballs
? Multi-Version Support - Works on Paper 1.16.5+ without NMS
? Easy to Use - Simple commands and intuitive permissions system
Key Feature: Block Damage vs Entity Damage
IMPORTANT: This plugin allows you to disable block damage while keeping entity/player damage enabled. This means:
- ✅ Fireballs can damage players and mobs
- ❌ Fireballs won't break blocks or terrain
- ✅ Explosion effects, knockback, and fire still work
- ? Perfect for PvP servers that want to protect builds
Configure this in config.yml:
explosion:
block-damage: false # Blocks are safe
entity-damage: true # Players still take damage
Players can also toggle block damage for their own fireballs:
/tfireballs blockdamage <on|off>
Installation
- Download the latest release JAR from the releases page
- Place the JAR file in your server's
plugins/ folder
- Restart your server (or use a plugin manager)
- Configure the plugin in
plugins/ThrowableFireballs/config.yml
- (Optional) Install WorldGuard for advanced region protection
Requirements
- Minecraft Server: Paper 1.21.x (also compatible with 1.16.5 - 1.21.x)
- Java: 21 or newer (Java 17 minimum)
- Optional: WorldGuard 7.0+ for region protection
Commands
| Command |
Description |
Permission |
/tfireballs reload |
Reload configuration |
throwablefireballs.admin |
/tfireballs give <player> [amount] |
Give fireball items |
throwablefireballs.admin |
/tfireballs blockdamage <on|off> |
Toggle block damage for your fireballs |
throwablefireballs.blockdamage.toggle |
Aliases: /tfb, /throwablefireball
Permissions
Main Permissions
| Permission |
Description |
Default |
throwablefireballs.* |
Grant all permissions |
op |
throwablefireballs.use |
Throw fireballs |
true (everyone) |
throwablefireballs.admin |
Access admin commands |
op |
Advanced Permissions
| Permission |
Description |
Default |
throwablefireballs.bypasscooldown |
Bypass throw cooldown |
op |
throwablefireballs.bypassprotection |
Bypass region protection |
op |
throwablefireballs.blockdamage.toggle |
Toggle personal block damage |
true |
Configuration
The config.yml file is extensively documented. Here are the key sections:
Item Settings
item:
material: FIRE_CHARGE # Item to throw
consume-on-throw: true # Consume item?
consume-in-creative: false # Consume in creative?
custom-model-data: # For resource packs
enabled: false
value: 0
Projectile Settings
projectile:
type: SMALL # SMALL or LARGE
speed: 1.5 # Velocity multiplier
Explosion Settings
explosion:
block-damage: false # Break blocks?
entity-damage: true # Damage players/mobs?
power: 1.0 # Explosion radius
create-fire: true # Create fire?
fire-ticks: 100 # Fire duration
Cooldown Settings
cooldown:
time-millis: 1000 # 1 second cooldown
show-actionbar: true # Show message?
Protection Settings
protection:
respect-worldguard: true # Use WorldGuard?
check-build-permission: true # Basic protection
Per-Player Settings
per-player-settings:
allow-block-damage-toggle: true # Players can toggle?
All messages are customizable with color code support (& codes).
Multi-Version Support
This plugin is designed to work across multiple Paper versions (1.16.5+) without using NMS (Net Minecraft Server) code.
How It Works
The plugin uses a Version Adapter pattern:
- VersionAdapter Interface - Defines version-specific operations (e.g., action bar messages)
- ModernVersionAdapter - Uses Paper's Adventure API (1.16.5+)
- LegacyVersionAdapter - Reflection-based fallback for older versions
The plugin automatically detects your server version and uses the appropriate adapter.
API Version
In plugin.yml, we set api-version: 1.21 because:
- Version 1.1.0 targets Minecraft 1.21.x
- Maintains backward compatibility with 1.16.5+ due to no NMS usage
- Paper's API is stable across versions
- Modern features and optimizations available in 1.21
Supported Versions
| Version |
Status |
Notes |
| 1.16.5 |
✅ Compatible |
Minimum supported |
| 1.17.x |
✅ Compatible |
Uses modern adapter |
| 1.18.x |
✅ Compatible |
Uses modern adapter |
| 1.19.x |
✅ Compatible |
Uses modern adapter |
| 1.20.x |
✅ Compatible |
Uses modern adapter |
| 1.21.x |
✅ Tested |
Primary target |
| Future |
✅ Should work |
No NMS dependencies |
Building from Source
Prerequisites
Build Steps
# Clone the repository
git clone https://github.com/nando123412/ThrowableFireballs.git
cd ThrowableFireballs
# Build with Gradle
./gradlew build
# The JAR will be in build/libs/ThrowableFireballs-1.1.0.jar
Gradle Tasks
./gradlew clean # Clean build directory
./gradlew build # Build JAR (includes shadowJar)
./gradlew shadowJar # Build shaded JAR with dependencies
How It Works
Throwing Fireballs
- Player right-clicks with a fire charge (or configured item)
- Plugin checks:
- Permission (
throwablefireballs.use)
- Cooldown (unless bypassed)
- Item validity (material, custom model data, display name)
- Region protection (WorldGuard or basic checks)
- Fireball is spawned with:
- Player's eye direction
- Configured velocity
- Tagged with
PersistentDataContainer (player UUID stored)
- Item is consumed (if configured)
- Cooldown is applied
Explosion Control
When a fireball explodes:
- Plugin checks if it's tagged as "ours" (via
PersistentDataContainer)
- If not tagged, explosion proceeds normally (vanilla behavior)
- If tagged:
- Gets the player UUID from the tag
- Checks per-player settings (if enabled)
- Falls back to global config
- Block Damage: If disabled, clears block list and sets yield to 0
- Entity Damage: If disabled, cancels damage events
- Fire: Applies fire ticks if configured
Critical Detail: Even when block-damage: false, the explosion event is NOT cancelled, so entity damage still occurs naturally through Bukkit's damage system.
Damage Handling
The plugin handles damage in two ways:
-
Direct Hit - EntityDamageByEntityEvent with PROJECTILE cause
- Applies custom damage if configured
- Can be disabled with
entity-damage: false
-
Explosion Damage - Handled by Minecraft's explosion system
- Works automatically when explosion is not cancelled
- Controlled by
entity-damage config option
Troubleshooting
Fireballs Don't Break Blocks
Solution: This is intentional if explosion.block-damage: false in config. Players still take damage.
Action Bar Messages Don't Show
Solution: The plugin uses Adventure API (Paper 1.16.5+). If using older Spigot, messages fall back to chat.
WorldGuard Integration Not Working
Solution: Ensure WorldGuard 7.0+ is installed and protection.respect-worldguard: true in config.
Players Can Spam Fireballs
Solution: Reduce cooldown.time-millis or ensure players don't have throwablefireballs.bypasscooldown permission.
Explosions Are Too Weak/Strong
Solution: Adjust explosion.power in config. Vanilla TNT is 4.0, Creeper is 3.0.
Performance
The plugin is designed to be lightweight and performant:
- ✅ No tick loops - Event-driven architecture
- ✅ Minimal reflection - Only for action bars on legacy versions
- ✅ Efficient cooldowns - HashMap-based with cleanup
- ✅ No database - All data in memory
- ✅ PersistentDataContainer - Uses Bukkit's built-in tagging system
WorldGuard Integration
If WorldGuard is installed:
- Plugin detects WorldGuard on startup
- Basic region checks are performed
- Note: Full WorldGuard integration requires additional API usage
- Server admins can use WorldGuard flags to control fireball behavior:
creeper-explosion flag
ghast-fireball flag
- Custom flags (requires WorldGuard configuration)
For now, the plugin respects basic WorldGuard presence and can be extended with full API integration.
Development
Project Structure
src/main/java/com/nandoothjuuh/throwablefireballs/
├── ThrowableFireballsPlugin.java # Main plugin class
├── commands/
│ ├── TFireballsCommand.java # Command executor
│ └── TFireballsTabCompleter.java # Tab completion
├── compat/
│ ├── VersionAdapter.java # Version adapter interface
│ ├── ModernVersionAdapter.java # Adventure API (1.16.5+)
│ └── LegacyVersionAdapter.java # Reflection fallback
├── config/
│ ├── ConfigManager.java # Config wrapper
│ └── MessageManager.java # Message handler
├── cooldown/
│ └── CooldownManager.java # Cooldown tracking
├── items/
│ └── FireballItemFactory.java # Item creation
├── listeners/
│ ├── ThrowListener.java # Throw event handler
│ └── ExplosionControlListener.java # Explosion control
└── util/
└── TextUtil.java # Text utilities
Adding Features
To add new features:
- Add config options to
config.yml and ConfigManager.java
- Add messages to
config.yml and MessageManager.java
- Create new listeners or modify existing ones
- Register listeners in
ThrowableFireballsPlugin.java
- Add permissions to
plugin.yml
- Update README.md
License
This project is provided as-is for educational and server use. Feel free to modify and use it on your server.
Credits
- Author: nandoothjuuh
- Plugin API: Paper/Spigot/Bukkit
- Built with: Java 17, Gradle
Support
For issues, questions, or suggestions:
- Open an issue on GitHub
- Check the wiki for detailed guides
- Join the community Discord (if available)
Note: This plugin is designed for Paper servers. While it may work on Spigot, Paper is highly recommended for best performance and compatibility.
评论 0
登录后参与评分
还没有评论,来抢沙发吧