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:

1. Checks whether the selected world and zone are available
2. Reconciles currently tracked blocks
3. Checks the active lucky block limit
4. Selects a block type using its configured chance
5. Finds a valid free location
6. Checks the supporting surface and minimum spacing
7. Places the physical block
8. Creates its TextDisplay hologram
9. Adds its Base64 head visual
10. 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:

• WorldEdit
• WorldGuard

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

• WorldEdit
• WorldGuard

Optional

• Vault
• Any Vault-compatible economy plugin