** ? MaceCooldown 插件 - 完整说明
? 概述
MaceCooldown 是一款轻量级、性能优化的 Minecraft 插件,专为 Paper/Spigot 1.21.1-1.21.11 服务器设计。它为 Mace(战锤)武器引入了策略性的冷却机制,防止攻击 spam(频繁连击),并为 PvP 和 PvE 战斗场景增添了战术深度。
当玩家使用战锤攻击任何实体时,该武器将被置于冷却状态,持续时间为可配置的时间段。在此期间,玩家无法再次使用战锤。这有助于平衡游戏玩法,并防止战锤过度滥用。
✨ 主要功能
1. 冷却系统
- ⏱️ 可配置时长:设置以秒为单位的冷却时间(默认:120 秒 / 2 分钟)
- ? 原生 Minecraft API:使用官方
Player.setCooldown() 方法实现无缝集成
- ? 自动转换:秒数自动转换为 Minecraft 刻(1 秒 = 20 刻)
- ? 玩家反馈:视觉消息告知玩家冷却已生效
2. 智能检测
- ? 实体攻击触发:仅在玩家实际击中实体时激活
- ✋ 主手检测:仅当战锤位于主手槽位时触发
- ?️ 实体无关性:适用于所有类型的实体(玩家、生物、Boss、自定义实体)
3. 配置系统
- ? 完全可定制:编辑
config.yml 以满足服务器需求
- ? 开关控制:无需卸载即可完全禁用插件
- ? 热重载:使用
/macecooldown reload 在不重启服务器的情况下应用配置更改
- ? 文档齐全:配置文件包含每个设置的清晰注释
4. 管理功能
- ? 管理员命令:使用
/macecooldown reload 管理插件
- ? 权限系统:
macecooldown.admin 权限(默认 OP 拥有)
- ? 状态反馈:重新加载时命令显示当前配置
5. 性能与兼容性
- ⚡ 轻量级:资源占用极小,事件处理经过优化
- ? 现代 Minecraft:支持 1.21.1 至 1.21.11
- ☕ Java 21:基于最新的 Java LTS 构建,以获得最佳性能
- ? Paper/Spigot:兼容两种服务器平台
? 用例与应用
PvP 服务器
- 平衡战斗:防止决斗和竞技场中的战锤 spam
- 策略性玩法:玩家必须仔细把握战锤攻击时机
- 武器多样性:鼓励在不同武器之间切换
- 技巧型战斗:奖励战术思维而非无脑按键
生存/SMP 服务器
- Boss 战:使 Boss 战斗更具挑战性和趣味性
- 刷怪:防止通过战锤 spam 轻易刷怪
- 资源平衡:鼓励多样化使用武器并管理耐久度
RPG/冒险服务器
- 职业系统:与基于职业的系统集成,用于战士的冷却机制
- 任务平衡:通过限制强力武器增加任务难度
- 进度控制:通过冷却机制限制强大战锤的使用
小游戏
- PvP 竞技场:为战斗小游戏增添战略深度
- 自定义事件:创建带有武器冷却限制的限时挑战
- 比赛平衡:确保竞技活动中公平的对决
? 工作原理
技术流程:
1. 玩家在主手使用战锤攻击实体
↓
2. 插件检测到 EntityDamageByEntityEvent
↓
3. 检查是否启用冷却 cooldown-enabled = true
↓
4. 验证攻击者为 Player
↓
5. 检查武器是否为 Material.MACE
↓
6. 将配置的秒数转换为刻(秒 × 20)
↓
7. 使用 player.setCooldown(Material.MACE, ticks) 应用冷却
↓
8. 玩家收到反馈消息
↓
9. 在冷却结束前无法使用战锤
玩家视觉体验:
- ✅ 冷却前:战锤正常工作
- ⚔️ 攻击实体:玩家使用战锤击中任何生物/玩家
- ⏳ 冷却激活:战锤图标显示冷却动画
- ? 消息出现:“战锤冷却已应用,持续 120 秒!”
- ⏱️ 等待期间:玩家必须等待(或切换武器)
- ✅ 冷却结束:战锤再次可用
⚙️ 配置详情
config.yml 分解:
cooldown-enabled: true
- 类型:布尔值 (
true 或 false)
- 默认值:
true
- 用途:整个插件的主开关
- 效果:当设置为
false 时,插件不执行任何操作(可用于临时禁用)
cooldown-seconds: 120
- 类型:整数(正整数)
- 默认值:
120(2 分钟)
- 范围:任意正数(推荐:10-300)
- 用途:现实世界中的持续时间(秒)
- 转换:自动乘以 20 以转换为 Minecraft 刻
配置示例:
| 用例 |
cooldown-seconds |
实际时间 |
适用场景 |
| 快节奏 PvP |
30 |
30 秒 |
快速重生服务器 |
| 平衡 PvP |
60 |
1 分钟 |
竞技场/决斗 |
| 默认 |
120 |
2 分钟 |
通用用途 |
| 高难度生存 |
180 |
3 分钟 |
具有挑战性的 PvE |
| Boss 战 |
300 |
5 分钟 |
史诗级遭遇战 |
? 命令与权限
命令:
| 命令 |
别名 |
描述 |
权限 |
/macecooldown reload |
/mcd reload |
重新加载 config.yml |
macecooldown.admin |
权限:
| 权限 |
默认值 |
描述 |
macecooldown.admin |
OP |
访问重新加载命令和管理功能 |
命令用法:
编辑 config.yml 后重新加载配置
/macecooldown reload
/mcd reload 较短的别名
输出示例:
✓ MaceCooldown 配置重新加载成功!
冷却已启用:true
冷却持续时间:120 秒
? 安装指南
步骤 1:下载
- 使用 Maven 从源代码编译:
mvn clean package
- 或者从 releases 页面下载预编译的
.jar 文件
步骤 2:安装
- 停止服务器
- 将
MaceCooldown-1.0.0.jar 复制到 plugins/ 文件夹
- 启动服务器
步骤 3:配置
- 找到
plugins/MaceCooldown/config.yml(自动生成)
- 根据需要编辑设置
- 运行
/macecooldown reload(无需重启!)
步骤 4:测试
- 加入服务器
- 获取战锤:
/give @s mace
- 攻击任意生物/玩家
- 观察冷却触发
? 优势与特点
对于服务器管理员:
- ✅ 易于设置:即插即用,立即生效
- ✅ 无需数据库:轻量级,无需 SQL 或存储
- ✅ 零依赖:无需外部插件
- ✅ 可定制:可根据服务器需求进行调整
- ✅ 高性能:对 TPS 的影响微乎其微
对于玩家:
- ✅ 公平战斗:防止武器滥用刷屏
- ✅ 策略深度:促使更慎重的战斗决策
- ✅ 视觉反馈:清晰的冷却指示器
- ✅ 平衡 PvP:技巧比狂点鼠标更重要
对于开发者:
- ✅ 代码整洁:文档完善,易于修改
- ✅ 现代 API:遵循 Paper/Spigot 最佳实践
- ✅ 开源:完全可定制
- ✅ Java 21:面向未来的实现
?️ 系统要求
服务器要求:
- Minecraft 版本:1.21.1, 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.7, 1.21.8, 1.21.9, 1.21.10, 1.21.11
- 服务端软件:Paper(推荐)或 Spigot
- Java 版本:Java 21 或更高
- 内存:极低 (< 1MB)
- 存储空间:< 100KB
客户端要求:
- 无需客户端模组:兼容原版客户端
- 版本:必须与服务端版本一致
? 插件行为详情
触发冷却的条件:
✅ 在主手使用战锤击中任何实体
✅ 任何成功的攻击(造成伤害)
✅ PvP 攻击(玩家对战玩家)
✅ PvE 攻击(玩家对战生物)
不触发冷却的情况:
❌ 副手持有战锤(仅主手计数)
❌ 未命中攻击(未击中任何目标)
❌ 在配置文件中禁用冷却时进行攻击
❌ 使用其他武器进行攻击
❌ 用战锤破坏方块
冷却范围:
- ? 按玩家独立计算:每个玩家拥有独立的冷却时间
- ? 基于材质:冷却适用于背包中的所有战锤
- ? 持久性:死亡、传送、维度切换后依然有效
- ⏱️ 计时制:在配置的持续时间结束后自动过期
? 性能指标
| 指标 |
数值 |
| 事件监听器 |
1 (EntityDamageByEntityEvent) |
| 内存占用 |
< 1 MB |
| CPU 影响 |
微乎其微 (< 0.1% TPS) |
| 磁盘占用 |
< 100 KB |
| 启动时间 |
< 50ms |
| 配置重载时间 |
< 10ms |
? 安全与稳定
- ✅ 无漏洞:无已知的复制或利用绕过方法
- ✅ 权限控制:命令受权限系统保护
- ✅ 输入验证:加载时验证配置值
- ✅ 错误处理:配置无效时优雅回退到默认值
- ✅ 无外部连接:完全离线,无遥测数据
? 与其他替代品对比
| 功能 |
MaceCooldown |
通用冷却插件 |
手动配置 |
| 针对战锤优化 |
✅ 已优化 |
⚠️ 通用型 |
❌ 复杂 |
| 易于设置 |
✅ 单个文件 |
⚠️ 多个配置文件 |
❌ 需要专业知识 |
| 性能 |
✅ 轻量级 |
⚠️ 因插件而异 |
✅ 不适用 |
| 1.21+ 支持 |
✅ 原生支持 |
⚠️ 可能滞后 |
✅ 如果支持 |
| 热重载 |
✅ 内置 |
⚠️ 因插件而异 |
❌ 需要重启 |
? 示例场景
场景 1:PvP 竞技场
设置:60 秒冷却
效果:玩家在战斗中每分钟只能使用一次战锤
结果:鼓励武器切换和战术规划
场景 2:生存服务器
设置:120 秒冷却(默认)
效果:战锤成为一种强大但受限的工具
结果:玩家将战锤留用于对抗强力生物,使用其他武器进行采集
场景 3:Boss 战活动
设置:300 秒冷却(5 分钟)
效果:每场 Boss 战可使用一两次战锤
结果:使 Boss 战更具挑战性和策略性
场景 4:临时禁用
设置:设置 cooldown-enabled: false
效果:插件保留但不起作用
结果:快速为特殊活动禁用,活动结束后重新启用
❓ 常见问题
问:这能与其他插件提供的自定义战锤配合吗?
答:可以,只要物品类型是 Material.MACE。
问:我可以为不同玩家设置不同的冷却时间吗?
答:当前版本不支持,但您可以修改代码以添加基于权限的层级。
问:它支持副手战锤吗?
答:不支持,只有主手攻击会触发冷却(出于平衡性的设计选择)。
问:如果我将冷却时间设置为 0 会发生什么?
答:冷却将即时完成(本质上在该玩家攻击后对该玩家禁用)。
问:有最大冷却时间限制吗?
答:没有硬性限制,但极高的值(> 1 小时)并不实用。
问:这会影响战锤耐久度吗?
答:不会,正常的耐久度损耗仍然适用。
问:玩家可以通过携带多个战锤来绕过冷却吗?
答:不能,冷却基于材质类型生效,影响所有战锤。
? 支持与更新
获取帮助:
- 查看
config.yml 中的注释以了解设置说明
- 检查控制台日志以查找错误信息
- 确保已安装 Java 21 和 Paper/Spigot 1.21.x
? 为什么选择 MaceCooldown?
- ✅ 专为战锤打造:专门用于战锤平衡性调整
- ✅ 现代化:使用最新的 Minecraft 和 Java 版本
- ✅ 简单:一个插件,一个配置文件,一个命令
- ✅ 可靠:使用原生 Minecraft API(无黑客手段)
- ✅ 免费:开源,无隐藏费用
- ✅ 高效:对性能影响极小
- ✅ 灵活:可根据您的确切需求进行定制
MaceCooldown - 平衡你的战斗,提升你的服务器 ⚔️
** ? MaceCooldown Plugin - Complete Description
? Overview
MaceCooldown is a lightweight, performance-optimized Minecraft plugin designed for Paper/Spigot 1.21.1-1.21.11 servers. It introduces a strategic cooldown mechanic to the Mace weapon, preventing spam attacks and adding tactical depth to PvP and PvE combat scenarios.
When a player attacks any entity using a Mace, the weapon is placed on cooldown for a configurable duration, during which the player cannot use the Mace again. This creates balanced gameplay and prevents overpowered Mace spamming.
✨ Key Features
1. Cooldown System
- ⏱️ Configurable Duration: Set cooldown time in seconds (default: 120 seconds / 2 minutes)
- ? Native Minecraft API: Uses official
Player.setCooldown() method for seamless integration
- ? Automatic Conversion: Seconds automatically converted to Minecraft ticks (1 second = 20 ticks)
- ? Player Feedback: Visual messages inform players when cooldown is applied
2. Smart Detection
- ? Entity Attack Trigger: Activates only when a player actually hits an entity
- ✋ Main Hand Detection: Only triggers when Mace is in the main hand slot
- ?️ Entity-Agnostic: Works with all entity types (players, mobs, bosses, custom entities)
3. Configuration System
- ? Fully Customizable: Edit
config.yml to suit your server needs
- ? Toggle On/Off: Completely disable the plugin without uninstalling
- ? Hot Reload: Apply config changes without server restart using
/macecooldown reload
- ? Well-Documented: Config file includes clear comments for each setting
4. Administration
- ? Admin Commands:
/macecooldown reload for managing the plugin
- ? Permission System:
macecooldown.admin permission (OP by default)
- ? Status Feedback: Command shows current configuration when reloading
5. Performance & Compatibility
- ⚡ Lightweight: Minimal resource usage, optimized event handling
- ? Modern Minecraft: Supports 1.21.1 through 1.21.11
- ☕ Java 21: Built with the latest Java LTS for maximum performance
- ? Paper/Spigot: Compatible with both server platforms
? Use Cases & Applications
PvP Servers
- Balance Combat: Prevent Mace spam in duels and arenas
- Strategic Gameplay: Players must time their Mace attacks carefully
- Weapon Diversity: Encourages switching between different weapons
- Skill-Based Fighting: Rewards tactical thinking over button mashing
Survival/SMP Servers
- Boss Fights: Make boss battles more challenging and engaging
- Mob Grinding: Prevent trivializing mob farms with Mace spam
- Resource Balance: Encourages varied weapon use and durability management
RPG/Adventure Servers
- Class Systems: Integrate with class-based systems for warrior cooldowns
- Quest Balance: Make quests more challenging by limiting powerful weapons
- Progression Control: Gate powerful Mace usage behind cooldown mechanics
Mini-Games
- PvP Arenas: Add strategic depth to combat mini-games
- Custom Events: Create timed challenges with weapon cooldowns
- Tournament Balance: Ensure fair fights in competitive events
? How It Works
Technical Flow:
1. Player attacks entity with Mace in main hand
↓
2. Plugin detects EntityDamageByEntityEvent
↓
3. Checks if cooldown-enabled = true
↓
4. Validates attacker is a Player
↓
5. Checks if weapon is Material.MACE
↓
6. Converts config seconds to ticks (seconds × 20)
↓
7. Applies cooldown using player.setCooldown(Material.MACE, ticks)
↓
8. Player receives feedback message
↓
9. Mace cannot be used until cooldown expires
Visual Player Experience:
- ✅ Before Cooldown: Mace works normally
- ⚔️ Attack Entity: Player hits any mob/player with Mace
- ⏳ Cooldown Activates: Mace icon shows cooldown animation
- ? Message Appears: "Mace cooldown applied for 120 seconds!"
- ⏱️ Wait Period: Player must wait (or switch weapons)
- ✅ Cooldown Expires: Mace becomes usable again
⚙️ Configuration Details
config.yml Breakdown:
cooldown-enabled: true
- Type: Boolean (
true or false)
- Default:
true
- Purpose: Master toggle for the entire plugin
- Effect: When
false, plugin does nothing (useful for temporary disabling)
cooldown-seconds: 120
- Type: Integer (whole number)
- Default:
120 (2 minutes)
- Range: Any positive number (recommended: 10-300)
- Purpose: Duration in real-world seconds
- Conversion: Automatically multiplied by 20 for Minecraft ticks
Configuration Examples:
| Use Case |
cooldown-seconds |
Real Time |
Best For |
| Fast-Paced PvP |
30 |
30 seconds |
Quick respawn servers |
| Balanced PvP |
60 |
1 minute |
Arena/duels |
| Default |
120 |
2 minutes |
General use |
| Hard Survival |
180 |
3 minutes |
Challenging PvE |
| Boss Battles |
300 |
5 minutes |
Epic encounters |
? Commands & Permissions
Commands:
| Command |
Aliases |
Description |
Permission |
/macecooldown reload |
/mcd reload |
Reloads config.yml |
macecooldown.admin |
Permissions:
| Permission |
Default |
Description |
macecooldown.admin |
OP |
Access to reload command and admin functions |
Command Usage:
Reload configuration after editing config.yml
/macecooldown reload
/mcd reload Shorter alias
Output example:
✓ MaceCooldown configuration reloaded successfully!
Cooldown enabled: true
Cooldown duration: 120 seconds
? Installation Guide
Step 1: Download
- Compile from source using Maven:
mvn clean package
- Or download pre-compiled
.jar from releases
Step 2: Install
- Stop your server
- Copy
MaceCooldown-1.0.0.jar to plugins/ folder
- Start your server
Step 3: Configure
- Find
plugins/MaceCooldown/config.yml (auto-generated)
- Edit settings as desired
- Run
/macecooldown reload (no restart needed!)
Step 4: Test
- Join your server
- Get a Mace:
/give @s mace
- Attack any mob/player
- Observe cooldown activation
? Benefits & Advantages
For Server Owners:
- ✅ Easy Setup: Drop-in installation, works immediately
- ✅ No Database: Lightweight, no SQL or storage needed
- ✅ Zero Dependencies: No external plugins required
- ✅ Customizable: Adjust to your server's needs
- ✅ Performance: Negligible impact on TPS
For Players:
- ✅ Fair Combat: No weapon spam abuse
- ✅ Strategic Depth: More thoughtful combat decisions
- ✅ Visual Feedback: Clear cooldown indicator
- ✅ Balanced PvP: Skill matters more than spam-clicking
For Developers:
- ✅ Clean Code: Well-documented, easy to modify
- ✅ Modern API: Uses Paper/Spigot best practices
- ✅ Open Source: Fully customizable
- ✅ Java 21: Future-proof implementation
?️ System Requirements
Server Requirements:
- Minecraft Version: 1.21.1, 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.7, 1.21.8, 1.21.9, 1.21.10, 1.21.11
- Server Software: Paper (recommended) or Spigot
- Java Version: Java 21 or higher
- RAM: Minimal (< 1MB)
- Storage: < 100KB
Client Requirements:
- No Client Mods Needed: Works with vanilla clients
- Version: Must match server version
? Plugin Behavior Details
What Triggers Cooldown:
✅ Hitting any entity with Mace in main hand
✅ Any successful attack (damage dealt)
✅ PvP attacks (player vs player)
✅ PvE attacks (player vs mob)
What Does NOT Trigger:
❌ Mace in off-hand (only main hand counts)
❌ Missing attacks (not hitting anything)
❌ Attacking while cooldown is disabled in config
❌ Attacking with other weapons
❌ Breaking blocks with Mace
Cooldown Scope:
- ? Per-Player: Each player has their own independent cooldown
- ? Material-Based: Cooldown applies to ALL Maces in inventory
- ? Persistent: Lasts through death, teleports, dimension changes
- ⏱️ Timed: Expires automatically after configured duration
? Performance Metrics
| Metric |
Value |
| Event Listeners |
1 (EntityDamageByEntityEvent) |
| Memory Footprint |
< 1 MB |
| CPU Impact |
Negligible (< 0.1% TPS) |
| Disk Usage |
< 100 KB |
| Startup Time |
< 50ms |
| Config Reload Time |
< 10ms |
? Security & Safety
- ✅ No Exploits: No known duplication or bypass methods
- ✅ Permission-Based: Commands protected by permission system
- ✅ Input Validation: Config values validated on load
- ✅ Error Handling: Graceful fallback to defaults on invalid config
- ✅ No External Connections: Completely offline, no telemetry
? Comparison with Alternatives
| Feature |
MaceCooldown |
Generic Cooldown Plugins |
Manual Config |
| Mace-Specific |
✅ Optimized |
⚠️ Generic |
❌ Complex |
| Easy Setup |
✅ 1 file |
⚠️ Multiple configs |
❌ Requires knowledge |
| Performance |
✅ Lightweight |
⚠️ Varies |
✅ N/A |
| 1.21+ Support |
✅ Native |
⚠️ May lag behind |
✅ If supported |
| Hot Reload |
✅ Built-in |
⚠️ Varies |
❌ Requires restart |
? Example Scenarios
Scenario 1: PvP Arena
Setup: 60-second cooldown
Effect: Players can use Mace once per minute in fights
Result: Encourages weapon switching and tactical planning
Scenario 2: Survival Server
Setup: 120-second cooldown (default)
Effect: Mace becomes a powerful but limited tool
Result: Players save Mace for tough mobs, use other weapons for farming
Scenario 3: Boss Battle Event
Setup: 300-second cooldown (5 minutes)
Effect: Mace usable once or twice per boss fight
Result: Makes boss fights more challenging and strategic
Scenario 4: Temporarily Disable
Setup: Set cooldown-enabled: false
Effect: Plugin stays installed but does nothing
Result: Quickly disable for special events, re-enable after
❓ FAQ
Q: Does this work with custom Maces from other plugins?
A: Yes, as long as the item type is Material.MACE.
Q: Can I set different cooldowns for different players?
A: Not in this version, but you can modify the code to add permission-based tiers.
Q: Does it work with off-hand Maces?
A: No, only main hand attacks trigger cooldown (design choice for balance).
Q: What happens if I set cooldown to 0?
A: The cooldown will be instant (essentially disabled for that player after attack).
Q: Is there a maximum cooldown limit?
A: No hard limit, but extremely high values (> 1 hour) are impractical.
Q: Does this affect Mace durability?
A: No, normal durability loss still applies.
Q: Can players bypass with multiple Maces?
A: No, cooldown applies to the Material type, affecting all Maces.
? Support & Updates
Getting Help:
- Check
config.yml comments for setting explanations
- Review console logs for error messages
- Ensure Java 21 and Paper/Spigot 1.21.x are installed
? Why Choose MaceCooldown?
- ✅ Purpose-Built: Specifically designed for Mace balancing
- ✅ Modern: Uses latest Minecraft and Java versions
- ✅ Simple: One plugin, one config, one command
- ✅ Reliable: Uses native Minecraft API (no hacks)
- ✅ Free: Open source, no hidden costs
- ✅ Efficient: Minimal performance impact
- ✅ Flexible: Customize to your exact needs
MaceCooldown - Balance Your Combat, Enhance Your Server ⚔️**
评论 0
登录后参与评分
还没有评论,来抢沙发吧