hLuckyBlock
hLuckyBlock 是一款适用于 Paper 和 Purpur 服务器的自动幸运方块系统。
无需玩家放置特殊物品,该插件会在配置好的事件区域内自动生成幸运方块。区域可以基于 WorldGuard 区域 或简单的 坐标长方体。
每种幸运方块类型都可以拥有独立的:
- 物理 Minecraft 材质
- 随机选择概率
- 所需击打次数
- 动态 TextDisplay 全息图
- Base64 头像纹理
- 奖励动作列表
当玩家完全破坏一个幸运方块时,hLuckyBlock 会执行配置的奖励并移除所有相关的视觉实体。
功能特性
- 自动生成幸运方块
- WorldGuard 区域与坐标长方体区域
- 无限自定义幸运方块类型
- 加权随机方块选择
- 可配置的多击耐久度
- 动态剩余击打次数全息图
- 原生 Paper TextDisplay 实体
- 多行 MiniMessage 全息图
- HEX 颜色与渐变
- Base64 头像纹理
- 异步纹理准备
- 有界纹理缓存
- 每种方块类型的独立奖励
- 13 种可配置的动作类型
- 可选的 Vault 经济奖励
- PlaceholderAPI 扩展
- 坚实表面验证
- 被阻止的支持材质
- 通配符材质模式
- 活跃方块之间的最小间距
- 可配置的活跃方块上限
- 停止生成或删除全部上限行为
- 残留幸运方块回收
- 孤立实体清理
- 安全关闭清理
- 手动开始、停止和清理命令
- 俄语和英语本地化
- 无需外部全息图插件
- 无需资源包
- 无需数据库
机制
hLuckyBlock 在插件启用时会启动一个自动生成任务。
在每个配置的间隔期间,插件会执行以下操作:
- 检查选定的世界和区域是否可用
- 核对当前跟踪的方块
- 检查活跃幸运方块的上限
- 使用其配置的概率选择一种方块类型
- 寻找有效的空闲位置
- 检查支撑表面和最小间距
- 放置物理方块
- 创建其 TextDisplay 全息图
- 添加其 Base64 头像视觉效果
- 开始跟踪其耐久度
对于已配置的幸运方块,常规方块破坏会被取消。
每次成功击打都会使内部耐久度减一。如果还有剩余耐久度,全息图会更新。在最后一次击打后,插件会移除方块并执行其奖励动作。
区域
REGION(区域)
使用配置的 WorldGuard 区域的最小和最大边界。
settings:
luckyZone:
mode: REGION
region:
world: "spawn"
region: "hotzone"
此模式需要:
CUBOID(长方体)
使用选定世界中的两个坐标位置。
settings:
luckyZone:
mode: CUBOID
cuboid:
world: "spawn"
pos1:
x: -50
y: 60
z: -50
pos2:
x: 50
y: 100
z: 50
两个位置的顺序无关紧要。
CUBOID 模式不需要 WorldEdit 或 WorldGuard。
配置
生成间隔以毫秒为单位进行配置:
settings:
timeToSpawn: 3000
3000 的默认值意味着每三秒尝试生成一次。
其他规则:
settings:
spawn:
onlyOnSolidSurface: true
minimumDistance: 1
blockedSupportMaterials:
- "*_TRAPDOOR"
- "*_SIGN"
- "*_CORAL*"
- "BARREL"
- "*_SLAB"
- "COBWEB"
- "*_STAIRS"
- "*GLASS*"
表面
要求新幸运方块下方必须有坚实的方块。
距离
定义活跃幸运方块之间的水平间距。
设置为 0 可禁用间距检查。
方块列表
防止幸运方块在选定的材质上方生成。
支持通配符模式:
*_SLAB — 所有台阶
*_STAIRS — 所有楼梯
*GLASS* — 包含 GLASS 的所有材质
*_CORAL* — 匹配的珊瑚材质
插件还会验证目标位置是否为空、高度是否有效以及支撑方块不是另一种幸运方块材质。
类型
幸运方块类型在 blocks.yml 中配置。
节键是物理 Minecraft 材质。
blocks:
GLASS:
chance: 0.33
breakCount: 3
hologramY: 1.1
hologram:
- "<gold>Fragile Lucky Block</gold>"
- "<white>Break it <gold>{breakCount}</gold> more times!</white>"
texture: "BASE64_TEXTURE"
每种类型都支持:
| 设置项 |
描述 |
chance |
从 0.0 到 1.0 的随机选择概率 |
breakCount |
所需的击打次数 |
hologramY |
垂直全息图偏移量 |
hologram |
多行 MiniMessage 全息图 |
texture |
Base64 头像纹理 |
{breakCount} 占位符会动态替换为当前的剩余击打次数。
所有 chance 值的总和通常应等于 1.0。当总和较低时,某些生成尝试可能会未选择任何方块。
内置示例
默认配置包含三个示例:
GLASS(玻璃)
- 概率:
0.33
- 所需击打次数:
3
- 默认奖励:100 Vault 货币和控制台点命令
White(白色)
- 概率:
0.33
- 所需击打次数:
4
- 默认奖励:150 Vault 货币和更大的点数奖励
LightGray(浅灰色)
- 概率:
0.34
- 所需击打次数:
5
- 默认奖励:200 Vault 货币和最大的点数奖励
每个默认类型均可完全编辑。
全息图
hLuckyBlock 使用原生的 Paper TextDisplay 实体。
无需外部全息图插件。
全息图支持:
- 多行文本
- MiniMessage 语法
- HEX 颜色
- 渐变效果
- Adventure 格式化
- 按类型的垂直偏移
- 动态剩余耐久度显示
{breakCount} 的值会在每次成功击打后更新。
当方块被移除时,其全息图也会自动移除。
Base64
每种类型都可以在其物理方块上方显示自定义的 Base64 头像纹理。
无需使用资源包即可提供自定义视觉效果。
纹理处理包括:
- 每种类型都有独立的纹理
- 异步准备
- 有界缓存
- Paper PlayerProfile 回退机制
- 用于清理和恢复的持久化内部标签
blocks.yml 中配置的物理材质仍用于识别类型、耐久度和奖励。
限制
settings:
limit:
count: 35
action: STOP_SPAWN
支持的操作:
STOP_SPAWN
当达到活动上限时,停止生成新的幸运方块。
在现有方块被破坏后,生成将自动继续。
DELETE_ALL
当达到上限时,移除所有活动的幸运方块及其视觉实体。
区域将在后续的生成周期中重新开始填充。
奖励
每种方块类型在 actions.yml 中都有其独立的奖励列表。
actions:
blocks:
GLASS:
- "[VAULT] action:give && count:100"
- "[CONSOLE] p give {player} 10"
支持的操作类型:
[MESSAGE]
[ACTIONBAR]
[TITLE]
[SOUND]
[PARTICLE]
[BOSSBAR]
[BROADCAST]
[CONSOLE]
[PLAYER]
[VAULT]
[EFFECT]
[FIREWORK]
[CLOSE]
操作可以:
- 发送消息
- 显示动作栏(ActionBars)和标题(Titles)
- 创建临时的 BossBar
- 播放声音
- 生成粒子效果和烟花
- 广播消息
- 执行控制台命令
- 执行玩家命令
- 通过 Vault 更改经济余额
- 关闭玩家当前的物品栏
内部占位符:
{player}
{prefix}
PlaceholderAPI 的值也会使用破坏方块的玩家进行处理。
Vault
支持的 Vault 操作:
| 操作 |
结果 |
give, add |
存入金钱 |
remove, take, delete |
取出金钱 |
clear |
将余额设为零 |
set |
设置确切余额 |
仅在使用 [VAULT] 操作时才需要 Vault 和兼容的经济插件。
恢复
hLuckyBlock 使用持久化的内部标签来标识其 TextDisplay 和 ArmorStand 实体。
在启动期间,插件可以通过以下方式恢复遗留的幸运方块:
- 查找带标签的头部视觉实体
- 将其与物理方块匹配
- 重建耐久度条目
- 重建全息图
- 移除过期的视觉实体
- 检测未跟踪的配置方块材质
这有助于在异常停止或不兼容的外部修改后恢复系统。
在正常运行期间,受跟踪的方块会与真实世界进行同步。如果其他插件更改了方块,过期的跟踪信息和视觉实体将被移除。
干净地关闭插件会移除活动的幸运方块及其视觉实体。
重新加载插件还会在重新启动带有新配置的生成任务之前清理当前区域。
PlaceholderAPI
扩展标识符:
hluckyblock
可用的占位符:
| 占位符 |
描述 |
%hluckyblock_count% |
当前活动的幸运方块数量 |
%hluckyblock_timetospawn% |
下次生成尝试前剩余的毫秒数 |
当生成任务停止时,这两个占位符均返回 0。
命令
| 命令 |
描述 |
/hluckyblock |
显示命令帮助 |
/hluckyblock reload |
重新加载配置,刷新集成,清理活动方块并重新启动生成 |
/hluckyblock start |
开始自动生成 |
/hluckyblock stop |
停止未来的生成尝试,但不删除现有方块 |
/hluckyblock restore |
移除所有活动的幸运方块和视觉实体 |
包含命令补全功能。
权限
| 权限 |
描述 |
hluckyblock.admin |
访问所有管理命令 |
hluckyblock.break |
允许破坏幸运方块并获得奖励的权限 |
服务器操作员默认拥有这两种权限。
普通玩家必须获得 hluckyblock.break 权限后才能使用幸运方块。
文件
| 文件 |
用途 |
locale.yml |
选择俄语或英语 |
config.yml |
区域、生成规则、表面和限制 |
blocks.yml |
方块类型、几率、耐久度、全息图和纹理 |
actions.yml |
方块奖励和管理操作 |
messages.yml |
控制台和回退消息 |
要求
必需
- Java 21
- Paper 或 Purpur 1.21.x
- PlaceholderAPI
REGION
可选
hLuckyBlock
hLuckyBlock is an automatic lucky block system for Paper and Purpur servers.
Instead of requiring players to place special items, the plugin automatically spawns lucky blocks inside a configured event zone. The zone can be based on a WorldGuard region or a simple coordinate cuboid.
Every lucky block type can have its own:
- Physical Minecraft material
- Random selection chance
- Required number of hits
- Dynamic TextDisplay hologram
- Base64 head texture
- Reward action list
When a player completely breaks a lucky block, hLuckyBlock executes the configured rewards and removes every related visual entity.
Features
- Automatic lucky block spawning
- WorldGuard region and coordinate cuboid zones
- Unlimited custom lucky block types
- Weighted random block selection
- Configurable multi-hit durability
- Dynamic remaining-hit holograms
- Native Paper TextDisplay entities
- Multi-line MiniMessage holograms
- HEX colors and gradients
- Base64 head textures
- Asynchronous texture preparation
- Bounded texture caching
- Separate rewards for every block type
- 13 configurable action types
- Optional Vault economy rewards
- PlaceholderAPI expansion
- Solid surface validation
- Blocked support materials
- Wildcard material patterns
- Minimum spacing between active blocks
- Configurable active block limit
- Stop-spawning or delete-all limit behavior
- Leftover lucky block recovery
- Orphan entity cleanup
- Safe shutdown cleanup
- Manual start, stop and cleanup commands
- Russian and English localization
- No external hologram plugin required
- No resource pack required
- No database required
Mechanics
hLuckyBlock starts an automatic spawning task when the plugin is enabled.
During every configured interval, the plugin:
- Checks whether the selected world and zone are available
- Reconciles currently tracked blocks
- Checks the active lucky block limit
- Selects a block type using its configured chance
- Finds a valid free location
- Checks the supporting surface and minimum spacing
- Places the physical block
- Creates its TextDisplay hologram
- Adds its Base64 head visual
- Starts tracking its durability
Regular block breaking is cancelled for configured lucky blocks.
Every successful hit reduces the internal durability by one. If durability remains, the hologram is updated. After the final hit, the plugin removes the block and executes its reward actions.
Zones
REGION
Uses the minimum and maximum boundaries of a configured WorldGuard region.
settings:
luckyZone:
mode: REGION
region:
world: "spawn"
region: "hotzone"
This mode requires:
CUBOID
Uses two coordinate positions in a selected world.
settings:
luckyZone:
mode: CUBOID
cuboid:
world: "spawn"
pos1:
x: -50
y: 60
z: -50
pos2:
x: 50
y: 100
z: 50
The order of the two positions does not matter.
CUBOID mode does not require WorldEdit or WorldGuard.
Configuration
The spawn interval is configured in milliseconds:
settings:
timeToSpawn: 3000
The default value of 3000 means one spawn attempt every three seconds.
Additional rules:
settings:
spawn:
onlyOnSolidSurface: true
minimumDistance: 1
blockedSupportMaterials:
- "*_TRAPDOOR"
- "*_SIGN"
- "*_CORAL*"
- "BARREL"
- "*_SLAB"
- "COBWEB"
- "*_STAIRS"
- "*GLASS*"
Surface
Requires a solid block below the new lucky block.
Distance
Defines horizontal spacing between active lucky blocks.
Set it to 0 to disable the spacing check.
BlockList
Prevents lucky blocks from spawning above selected materials.
Wildcard patterns are supported:
*_SLAB — every slab
*_STAIRS — every stair
*GLASS* — every material containing GLASS
*_CORAL* — matching coral materials
The plugin also verifies that the destination is empty, the height is valid and the supporting block is not another lucky block material.
Types
Lucky block types are configured in blocks.yml.
The section key is the physical Minecraft material.
blocks:
GLASS:
chance: 0.33
breakCount: 3
hologramY: 1.1
hologram:
- "<gold>Fragile Lucky Block</gold>"
- "<white>Break it <gold>{breakCount}</gold> more times!</white>"
texture: "BASE64_TEXTURE"
Each type supports:
| Setting |
Description |
chance |
Random selection chance from 0.0 to 1.0 |
breakCount |
Number of required hits |
hologramY |
Vertical hologram offset |
hologram |
Multi-line MiniMessage hologram |
texture |
Base64 head texture |
The {breakCount} placeholder is dynamically replaced with the current remaining hit count.
The total of all chance values should normally equal 1.0. When the total is lower, some spawn attempts may select no block.
Included
The default configuration contains three examples:
GLASS
- Chance:
0.33
- Required hits:
3
- Default reward: 100 Vault currency and a console point command
White
- Chance:
0.33
- Required hits:
4
- Default reward: 150 Vault currency and a larger point reward
LightGray
- Chance:
0.34
- Required hits:
5
- Default reward: 200 Vault currency and the largest point reward
Every default type is fully editable.
Holograms
hLuckyBlock uses native Paper TextDisplay entities.
No external hologram plugin is required.
Holograms support:
- Multiple lines
- MiniMessage
- HEX colors
- Gradients
- Adventure formatting
- Per-type vertical offsets
- Dynamic remaining durability
The {breakCount} value is updated after every successful hit.
When the block is removed, its hologram is removed automatically.
Base64
Every type can display a custom Base64 head texture above its physical block.
This provides a custom visual appearance without requiring a resource pack.
Texture handling includes:
- Separate textures for every type
- Asynchronous preparation
- Bounded caching
- Paper PlayerProfile fallback
- Persistent internal tags for cleanup and recovery
The physical material configured in blocks.yml is still used to identify the type, durability and rewards.
Limits
settings:
limit:
count: 35
action: STOP_SPAWN
Supported actions:
STOP_SPAWN
Stops creating new lucky blocks while the active limit is reached.
Spawning continues automatically after existing blocks are destroyed.
DELETE_ALL
Removes every active lucky block and its visual entities when the limit is reached.
The zone begins filling again during later spawn cycles.
Reward
Every block type has its own reward list in actions.yml.
actions:
blocks:
GLASS:
- "[VAULT] action:give && count:100"
- "[CONSOLE] p give {player} 10"
Supported action types:
[MESSAGE]
[ACTIONBAR]
[TITLE]
[SOUND]
[PARTICLE]
[BOSSBAR]
[BROADCAST]
[CONSOLE]
[PLAYER]
[VAULT]
[EFFECT]
[FIREWORK]
[CLOSE]
Actions can:
- Send messages
- Show ActionBars and Titles
- Create temporary BossBars
- Play sounds
- Spawn particles and fireworks
- Broadcast messages
- Execute console commands
- Execute player commands
- Change economy balances through Vault
- Close the player's current inventory
Internal placeholders:
{player}
{prefix}
PlaceholderAPI values are also processed using the player who broke the block.
Vault
Supported Vault actions:
| Action |
Result |
give, add |
Deposit money |
remove, take, delete |
Withdraw money |
clear |
Set the balance to zero |
set |
Set an exact balance |
Vault and a compatible economy provider are required only when [VAULT] actions are used.
Recovery
hLuckyBlock uses persistent internal tags for its TextDisplay and ArmorStand entities.
During startup, the plugin can recover leftover lucky blocks by:
- Finding tagged head visuals
- Matching them with physical blocks
- Recreating durability entries
- Recreating holograms
- Removing stale visual entities
- Detecting configured block materials left without tracking
This helps restore the system after an abnormal stop or incompatible external modification.
During normal operation, tracked blocks are reconciled with the real world. If another plugin changes a block, stale tracking and visual entities are removed.
A clean plugin shutdown removes active lucky blocks and their visuals.
Reloading the plugin also cleans the current zone before restarting the spawning task with the new configuration.
PlaceholderAPI
Expansion identifier:
hluckyblock
Available placeholders:
| Placeholder |
Description |
%hluckyblock_count% |
Current active lucky block count |
%hluckyblock_timetospawn% |
Milliseconds remaining before the next spawn attempt |
When the spawn task is stopped, both placeholders return 0.
Commands
| Command |
Description |
/hluckyblock |
Show command help |
/hluckyblock reload |
Reload configuration, refresh integrations, clean active blocks and restart spawning |
/hluckyblock start |
Start automatic spawning |
/hluckyblock stop |
Stop future spawn attempts without deleting existing blocks |
/hluckyblock restore |
Remove all active lucky blocks and visual entities |
Command tab completion is included.
Permissions
| Permission |
Description |
hluckyblock.admin |
Access to all administrative commands |
hluckyblock.break |
Permission to damage lucky blocks and receive rewards |
Both permissions are granted to server operators by default.
Regular players must receive hluckyblock.break before they can use the lucky blocks.
Files
| File |
Purpose |
locale.yml |
Select Russian or English |
config.yml |
Zone, spawn rules, surfaces and limits |
blocks.yml |
Block types, chances, durability, holograms and textures |
actions.yml |
Block rewards and administrative actions |
messages.yml |
Console and fallback messages |
Requirements
Required
- Java 21
- Paper or Purpur 1.21.x
- PlaceholderAPI
REGION
Optional
- Vault
- Any Vault-compatible economy plugin
评论 0
登录后参与评分
还没有评论,来抢沙发吧