⭐ hLuckyBlock ⭐ [1.21.X-26.X] | WG, WE, PAPI, Vault, XSkull and more support!

hLuckyBlock is an automatic lucky block system designed for configured event zones, hot areas, PvP locations and other server regions.
The plugin randomly spawns lucky blocks inside a WorldGuard region or a coordinate-based cuboid. Every block type can have its own material, selection chance, required hit count, TextDisplay hologram, Base64 head texture and reward actions.
Lucky blocks do not have to break after one hit. Each type has configurable durability, while the built-in hologram displays the number of hits remaining. When a player fully breaks a lucky block, the plugin can give money, execute commands, send messages, play sounds, show titles, spawn particles or fireworks and run other configurable actions.
No external hologram plugin is required. hLuckyBlock uses native TextDisplay entities.
Main Features

• Automatic lucky block spawning.
• WorldGuard region or coordinate cuboid zones.
• Unlimited configurable block types.
• Weighted random type selection.
• Custom hit count for every type.
• Dynamic remaining-hit holograms.
• Native TextDisplay holograms.
• Multi-line MiniMessage formatting.
• HEX colors and gradients.
• Base64 head textures.
• Asynchronous texture preparation and caching.
• Separate rewards for every block type.
• 13 configurable action types.
• Optional Vault economy actions.
• Required PlaceholderAPI integration.
• Solid-surface spawn checking.
• Blocked support material list.
• Wildcard material patterns.
• Minimum horizontal distance between blocks.
• Free position and world height validation.
• Configurable active block limit.
• Stop-spawning or delete-all limit behavior.
• Automatic leftover block recovery.
• Orphan hologram and head cleanup.
• Active block reconciliation.
• Safe shutdown cleanup.
• Manual task start and stop.
• Manual zone cleanup.
• Russian and English localization.
• Configurable administrative actions.

How It Works
When the plugin starts, it creates an automatic spawn task.
During every configured interval, hLuckyBlock:

• checks whether the world and zone are available;
• reconciles existing tracked blocks;
• checks the active block limit;
• selects a block type using its configured chance;
• searches for a valid free position;
• checks the surface and minimum distance;
• places the physical block;
• creates its TextDisplay hologram;
• adds the Base64 head visual;
• starts tracking the block's durability.

When a player hits the lucky block, the regular break event is cancelled and its internal health is reduced.
If durability remains, the hologram is updated.
After the final required hit:

• the physical block is removed;
• the hologram is removed;
• the head visual is removed;
• the active entry is cleared;
• the block-specific reward actions are executed.

Zone Modes
REGION
Uses the minimum and maximum boundaries of a configured WorldGuard region.
Example settings:
luckyZone.mode: REGION
luckyZone.region.world: spawn
luckyZone.region.region: hotzone
WorldEdit and WorldGuard are required for this mode.
CUBOID
Uses two coordinate positions in a selected world.
Example settings:
luckyZone.mode: CUBOID
luckyZone.cuboid.world: spawn
luckyZone.cuboid.pos1
luckyZone.cuboid.pos2
The order of the two positions does not matter.
CUBOID mode does not require WorldEdit or WorldGuard.
Spawn Control
The spawn interval is configured in milliseconds.
The default value is 3000 milliseconds, equal to three seconds.
Spawn rules include:

• onlyOnSolidSurface — require a solid supporting block.
• minimumDistance — keep active lucky blocks separated horizontally.
• blockedSupportMaterials — prevent spawning above selected materials.

Wildcard patterns are supported.
Examples:
*_SLAB — every slab.
*_STAIRS — every stair.
*GLASS* — every material containing GLASS.
The plugin also verifies that:

• the new location is empty;
• the support block is solid;
• the support block is not another configured lucky block material;
• the position remains inside the selected zone;
• the height is valid for the world.

Lucky Block Types
Every type is configured inside blocks.yml.
The YAML key is the physical Minecraft material.
Each type supports:

• chance — selection chance from 0.0 to 1.0.
• breakCount — required number of hits.
• hologramY — hologram vertical offset.
• hologram — multi-line MiniMessage text.
• texture — Base64 head texture.

The hologram supports {breakCount}, which is replaced by the current remaining hit count.
The combined chance values should normally total 1.0. When the sum is lower, some spawn attempts may select no type.
Included Block Types
The default configuration contains three examples.
GLASS

• 0.33 chance;
• 3 required hits;
• default reward: 100 Vault currency and a console point command.

WHITE_STAINED_GLASS

• 0.33 chance;
• 4 required hits;
• default reward: 150 Vault currency and a larger point reward.

LIGHT_GRAY_STAINED_GLASS

• 0.34 chance;
• 5 required hits;
• default reward: 200 Vault currency and the largest point reward.

These are editable examples. Materials, chances, durability, appearance and rewards can all be replaced.
Dynamic TextDisplay 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.
The hologram is automatically removed when its lucky block disappears.
Base64 Textures
Every type can display a custom Base64 head texture above the physical block.
This provides a custom appearance without requiring a resource pack.
Texture handling includes:

• a separate texture for every type;
• asynchronous item preparation;
• a bounded texture cache;
• Paper PlayerProfile fallback;
• internal persistent tags for safe cleanup.

The physical material from blocks.yml is still used to identify the block type, durability and rewards.
Active Block Limits
The maximum active count is configurable.
Two limit actions are supported.
STOP_SPAWN
New lucky blocks stop spawning while the limit is reached.
Spawning automatically continues after existing blocks are destroyed.
DELETE_ALL
Every active lucky block, hologram and head visual is removed when the limit is reached.
The zone begins filling again during later spawn cycles.
Reward Action System
Each block type has a separate action list inside actions.yml.
Supported actions:
[MESSAGE]
[ACTIONBAR]
[TITLE]
[SOUND]
[PARTICLE]
[BOSSBAR]
[BROADCAST]
[CONSOLE]
[PLAYER]
[VAULT]
[EFFECT]
[FIREWORK]
[CLOSE]
Actions can:

• send player messages;
• show ActionBars or Titles;
• create temporary BossBars;
• play sounds;
• spawn particles and fireworks at the lucky block;
• broadcast messages;
• execute console commands;
• execute player commands;
• change the player's economy balance;
• close an open inventory.

Internal placeholders:
{player}
{prefix}
PlaceholderAPI values are also processed using the breaking player.
Vault Actions
Supported economy operations:

• give or add — deposit money.
• remove, take or 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.
The rest of hLuckyBlock continues working without Vault.
Recovery and Cleanup
hLuckyBlock uses internal persistent tags for its TextDisplay and ArmorStand entities.
During startup, the plugin can:

• find leftover lucky block head visuals;
• match them with physical blocks;
• recreate block health entries;
• recreate holograms;
• remove stale visual entities;
• recover configured materials left without active tracking.

This helps restore the system after an abnormal server stop or incompatible external modification.
During normal operation, tracked blocks are regularly checked. If another plugin or administrator changes the physical material, the stale tracking data and visual entities are removed.
A clean plugin shutdown removes active lucky blocks and their visuals.
The reload command also cleans current blocks before restarting the system with the new configuration.
PlaceholderAPI
Expansion identifier:
hluckyblock
Available placeholders:
%hluckyblock_count% — current active lucky block count.
%hluckyblock_timetospawn% — milliseconds remaining before the next spawn attempt.
When the spawn task is stopped, the placeholders return 0.
They can be used in TAB, scoreboards, menus, holograms and other PlaceholderAPI-compatible plugins.
Commands
/hluckyblock — show command help.
/hluckyblock reload — reload localization and configuration, refresh integrations, remove current lucky blocks and restart the spawn task.
/hluckyblock start — start automatic spawning.
/hluckyblock stop — stop future spawn attempts without removing existing lucky blocks.
/hluckyblock restore — remove all active lucky blocks, holograms and head visuals from the configured zone.
Command tab completion is included.
Permissions
hluckyblock.admin — access to reload, start, stop and restore commands.
hluckyblock.break — permission to damage lucky blocks and receive rewards.
Both permissions are granted to server operators by default.
Regular players must be given hluckyblock.break before they can use the lucky blocks.
A player without this permission cannot reduce block durability and receives the configured no-permission actions.
Configuration Files
locale.yml — select Russian or English localization.
config.yml — zone, spawning rules, surface checks and active limits.
blocks.yml — materials, chances, durability, holograms and Base64 textures.
actions.yml — block rewards and administrative command actions.
messages.yml — console and fallback messages.
What Can Be Configured?

• localization;
• plugin prefix;
• spawn interval;
• REGION or CUBOID mode;
• world and WorldGuard region;
• two cuboid positions;
• solid surface requirement;
• minimum distance;
• blocked support materials;
• wildcard material patterns;
• active block limit;
• limit behavior;
• block type count;
• materials;
• selection chances;
• required hits;
• hologram offset and lines;
• Base64 textures;
• per-type reward actions;
• economy operations;
• console and player commands;
• messages;
• sounds;
• ActionBars;
• Titles;
• BossBars;
• particles;
• fireworks;
• World effects;
• administrative actions;
• MiniMessage and HEX formatting.

Requirements and Compatibility
Required:

• Java 21
• Paper/Purpur 1.21.x
• PlaceholderAPI

Required only for REGION mode:

• WorldEdit
• WorldGuard

Optional:

• Vault — economy reward actions.
• Any Vault-compatible economy plugin.

Not required:

• database software;
• an external hologram plugin;
• a resource pack;
• ProtocolLib.