**---

Plugin Overview

Property	Value
Name	PaperLuckyBlocks
Version	1.0.0
API	Paper 1.21.1 - 1.21.8
Java Version	21
Dependencies	None (standalone)

What This Plugin Does

PaperLuckyBlocks faithfully recreates the classic Lucky Block Mod experience for Paper servers. Players can craft, place, and break Lucky Blocks to trigger random outcomes ranging from treasure drops to dangerous traps. The plugin also includes three special Lucky Items with unique combat abilities.

Core Mechanics

┌─────────────────────────────────────────────────────────────┐
│                    LUCKY BLOCK FLOW                        │
├─────────────────────────────────────────────────────────────┤
│  Craft Lucky Block  →  Place Block  →  Break Block         │
│        ↓                    ↓              ↓                │
│  8 Gold + Dropper     Stores Luck    Triggers Outcome       │
│                        Level          Based on Luck         │
└─────────────────────────────────────────────────────────────┘

Lucky Block System

The Lucky Block Item

Property	Description
Material	Player Head (Skull)
Texture	Custom Base64 yellow question mark skin
Stackable	Yes (64)
Craftable	Yes
Data Storage	PersistentDataContainer

Visual Appearance

┌─────────────────────────┐
│    ★ Lucky Block ★      │  ← Gold bold title
│                         │
│    Luck: +50            │  ← Color-coded luck value
│    [████████████░░░░░░] │  ← Visual luck bar
│                         │
│    "Feeling lucky..."   │  ← Dynamic description
│                         │
│    Break to reveal!     │  ← Action hint
└─────────────────────────┘

Luck Levels Explained

Range	Color	Description	Outcome Tendency
+75 to +100	Dark Green	Fortune favors you greatly!	Almost always positive
+50 to +74	Green	The odds are in your favor	Mostly positive
+25 to +49	Yellow	Feeling a bit lucky...	Slightly positive
0 to +24	White	Balanced between fortune and fate	Neutral
-25 to -1	Gold	Tread carefully...	Slightly negative
-50 to -26	Red	Misfortune looms ahead	Mostly negative
-100 to -51	Dark Red	Cursed by terrible luck!	Almost always negative

Crafting Recipe

┌─────┬─────┬─────┐
│   │   │   │    = Gold Ingot
├─────┼─────┼─────┤
│   │   │   │    = Dropper
├─────┼─────┼─────┤
│   │   │   │    Result: Lucky Block (Luck: 0)
└─────┴─────┴─────┘

Placement & Breaking

When Placed:

Block location and luck level are stored in memory
Enchantment particles appear
Chime sound plays
Block becomes a player head with custom texture

When Broken:

Normal drops are cancelled
Break effects play (golden particles, level-up sound)
Title appears showing outcome name
Random outcome executes after 0.5 second delay
Luck level influences outcome selection

⚔️ Lucky Items

Lucky Sword

Property	Value
Base Material	Golden Sword
Attack Damage	6.0 (configurable via attributes)
Attack Speed	Standard sword speed
Enchantments	Unbreaking V (hidden glow)
Trigger	Hit any living entity

Lucky Sword Effects

Effect	Chance	Description
Arrow Stream	5%	Fires 5 arrows at the victim with slight spread
Vampirism	5%	Heals attacker for 3 hearts (6 half-hearts)
Blindness	5%	Applies Blindness + Slowness to victim

┌──────────────────────────────────────────────────────┐
│              ✦ Lucky Sword ✦                         │
├──────────────────────────────────────────────────────┤
│  A blade blessed by fortune itself!                  │
│                                                      │
│  ⚔ Attack Damage: 6                                 │
│                                                      │
│  Random Effects (5% chance):                         │
│   ➤ Arrow Stream - Fires 5 arrows                   │
│   ➤ Vampirism - Heal 3 hearts                       │
│   ➤ Blindness - Blind the enemy                     │
└──────────────────────────────────────────────────────┘

Arrow Stream Mechanics

Spawns 5 arrows with 2-tick delay between each
Arrows home toward victim's center mass
Each arrow deals 4.0 damage
Arrows cannot be picked up
Arrows glow for visibility
Critical hit particles on each arrow

Vampirism Mechanics

Heals based on config value (default: 6 half-hearts)
Cannot exceed max health
Red dust particles flow from victim to attacker
Heart particles around attacker
Satisfying sound effect

Blindness Mechanics

Blindness I for 5 seconds (100 ticks)
Slowness II for 3 seconds (60 ticks)
Witch and smoke particles on victim
Illusioner spell sound

Lucky Bow

Property	Value
Base Material	Bow
Enchantments	Infinity I, Unbreaking V, Power III
Trigger	Shoot an arrow

Lucky Bow Effects

Effect	Chance	Description
Explosive	10%	Arrow becomes primed TNT
Molten	10%	Arrow becomes falling magma block
Meteorite	10%	Arrow becomes large fireball

┌──────────────────────────────────────────────────────┐
│              ✦ Lucky Bow ✦                           │
├──────────────────────────────────────────────────────┤
│  A bow infused with chaotic energy!                  │
│                                                      │
│  Random Effects (10% chance):                        │
│   ➤ Explosive - Arrow becomes TNT                   │
│   ➤ Molten - Arrow becomes lava                     │
│   ➤ Meteorite - Launches fireball                   │
│                                                      │
│  ∞ Infinity                                          │
└──────────────────────────────────────────────────────┘

Explosive Arrow Mechanics

Original arrow cancelled, TNT spawned instead
TNT inherits 80% of arrow velocity
3-second fuse (60 ticks)
Yield: 3.0 (or 0 if destructive disabled)
Flame and smoke particle trail
TNT primed sound

Molten Arrow Mechanics

Falling magma block with 120% arrow velocity
Deals 5.0 damage per block
Sets entities on fire for 3 seconds
On impact:
- If destructive enabled: Creates fire in 3x3 area
- If destructive disabled: Visual only + fire damage
Lava and flame particle trail

Meteorite Mechanics

Large fireball entity
50% of arrow velocity (slower but dramatic)
Yield: 2.0 (or 0 if destructive disabled)
Incendiary based on destructive setting
Epic flame/smoke/lava particle trail
Ghast shoot + blaze shoot + dragon growl sounds

Lucky Potion

Property	Value
Base Material	Splash Potion
Potion Type	Luck (visual only)
Enchantments	Unbreaking I (hidden glow)
Trigger	Splash on impact

┌──────────────────────────────────────────────────────┐
│              ✦ Lucky Potion ✦                        │
├──────────────────────────────────────────────────────┤
│  A potion of pure, concentrated luck!                │
│                                                      │
│  ⚗ Effect:                                          │
│    Triggers a random Lucky Block                    │
│    outcome at the impact location!                  │
│                                                      │
│  Throw wisely...                                     │
└──────────────────────────────────────────────────────┘

Lucky Potion Mechanics

Normal potion effects completely cancelled
Triggers OutcomeManager at splash location
Uses neutral luck (0) for outcome selection
Expanding witch particle ring on impact
Totem, end rod, and enchant particles
Can trigger ANY outcome (including structures, mobs, etc.)

Outcomes System

Outcome Categories

Category	Count	Description
Items	2	Drop valuable items
Mobs	2	Spawn creatures
Structures	2	Build block structures
Explosions	2	Explosive effects
Special	1	Unique mechanics

Outcome Properties

Every outcome has these properties:

Property	Type	Description
`name`	String	Unique identifier
`displayName`	String	Shown to players
`weight`	int	Selection probability
`isPositive`	boolean	Good for player?
`isDestructive`	boolean	Modifies world?
`luckModifier`	int	Luck influence (-100 to +100)

Weight & Luck Formula

// Base selection weight
adjustedWeight = baseWeight * (1 + (playerLuck * outcomeLuckModifier) / 10000)

// Example: Diamond outcome (luckModifier: +60) with player luck +80
adjustedWeight = 50 * (1 + (80 * 60) / 10000)
adjustedWeight = 50 * 1.48 = 74

Item Outcomes

Diamond Outcome

Property	Value
Name	`diamonds`
Weight	50
Luck Modifier	+60
Destructive	No

What it does:

Spawns 1-5 diamonds (configurable)
Each diamond has upward velocity with spread
Diamonds glow and have custom name "★ Diamond ★"
Ring of falling dust particles
Experience orb pickup sound per diamond

Netherite Armor Outcome

Property	Value
Name	`netherite_armor`
Weight	10 (rare)
Luck Modifier	+90
Destructive	No

What it does:

Spawns invisible armor stand with full netherite set
Armor stand rotates and bobs for 3 seconds
After display, armor drops with velocity
Each piece has custom name and lore
All pieces enchanted with Protection IV, Unbreaking III, Mending

Armor enchantments:

Helmet: Respiration III, Aqua Affinity
Chestplate: Thorns III
Leggings: (standard)
Boots: Feather Falling IV, Depth Strider III, Soul Speed III

Mob Outcomes

Giant Bob Outcome

Property	Value
Name	`giant_bob`
Weight	30
Luck Modifier	-40
Destructive	No

What it does:

Spawns Giant zombie named "★ BOB THE GIANT ★"
Bob has 100 HP (50 hearts)
Bob deals 15 damage per hit
Bob has fire resistance and glows
Bob performs special attacks:
- Ground Pound (every 5s): AoE damage + knockback
- Roar (every 10s): Slowness to nearby players

On Bob's Death:

5 diamonds
10 gold blocks
32 experience bottles
"Bob's Heart" (Nether Star trophy)
Victory sound + totem particles

Bee Swarm Outcome

Property	Value
Name	`bee_swarm`
Weight	40
Luck Modifier	-20
Destructive	No

Two variants (70/30 chance):

Angry Swarm (70%):

10 bees spawn angry
Bees target and chase player
Queen Bee and Elite Guard Bees named
Bees pursue for 30 seconds

Friendly Swarm (30%):

10 bees spawn passive
Bees orbit player
Grant Regeneration II every 10 seconds
Player receives 16 honeycomb + 8 honey bottles
Bees fly away after 60 seconds

️ Structure Outcomes
Cage Trap Outcome

Property	Value
Name	`cage_trap`
Weight	25
Luck Modifier	-60
Destructive	Yes

What it does:

Builds 3x3x4 iron bar cage around player
Construction is animated layer by layer
Iron block floor, iron bar walls
Water source on ceiling (drowning hazard)
Player gets Mining Fatigue II
Cage disappears after 30 seconds or if player escapes

Structure:

Layer 4:  [Water Source Blocks]
Layer 3:  ███   (Iron Bars Ceiling + Waterlogged)
          █ █
          ███
Layer 1-2:███   (Iron Bars Walls)
          █ █
          ███
Layer 0:  ███   (Iron Block Floor)
          ███
          ███

Chest Tower Outcome

Property	Value
Name	`chest_tower`
Weight	35
Luck Modifier	+40
Destructive	No

What it does:

Builds tower of 5 levels (configurable)
Each level has gold block platform + chest
Ladders connect levels
Higher chests = better loot

Loot tiers:

Tier	Items	Max Stack
Common	Coal, Raw Iron, Wheat, Bread, Arrows, etc.	16
Uncommon	Iron Ingot, Gold Ingot, Experience Bottles, etc.	8
Rare	Diamond, Emerald, Enchanted Golden Apple, Elytra, etc.	3

Loot probability by height:

Bottom chest: Mostly common
Top chest: High rare chance + guaranteed valuable

Explosion Outcomes

TNT Outcome

Property	Value
Name	`tnt`
Weight	20
Luck Modifier	-70
Destructive	Yes

Four random patterns:

Pattern	Description
Single TNT	One powerful TNT with countdown
TNT Rain	5 TNT falling from 15 blocks up
TNT Circle	6 TNT in ring moving inward
TNT Volley	3 TNT shot toward player

If destructive disabled:

Visual explosion only
Player knockback
No block damage

Explosion Outcome

Property	Value
Name	`explosion`
Weight	15
Luck Modifier	-80
Destructive	Yes

Three random patterns:

Pattern	Description
Instant	Brief charge, immediate explosion
Delayed	3-second dramatic buildup with particles
Chain	7 small explosions + 1 big finale

Features:

Configurable power (default: 4.0)
Shockwave ring particle effect
Rising smoke column
Player knockback even if non-destructive

✨ Special Outcomes

Wishing Well Outcome

Property	Value
Name	`wishing_well`
Weight	25
Luck Modifier	+30
Destructive	No

What it does:

Builds decorative wishing well structure
Gold nuggets fountain from center (20 total)
Occasional special items (ingots, gems)
Bonus gold ingots at end

Structure includes:

Cobblestone wall ring
Oak fence posts
Oak slab roof
Glowstone top
Chain + lantern
Water in center
Decorative flowers around base

Commands & Permissions
Commands

Command	Arguments	Description
`/luckyblock give`	`[player] [luck]`	Give Lucky Block
`/luckyblock givesword`	`[player]`	Give Lucky Sword
`/luckyblock givebow`	`[player]`	Give Lucky Bow
`/luckyblock givepotion`	`[player]`	Give Lucky Potion
`/luckyblock reload`	-	Reload configuration

Aliases: /lb, /luckyblockspin

Permissions

Permission	Default	Description
`luckyblocks.admin`	OP	All admin commands
`luckyblocks.craft`	true	Craft Lucky Blocks
`luckyblocks.break`	true	Break Lucky Blocks
`luckyblocks.use.sword`	true	Lucky Sword effects
`luckyblocks.use.bow`	true	Lucky Bow effects
`luckyblocks.use.potion`	true	Lucky Potion effects

⚙️ Configuration

config.yml Structure

settings:
  destructive-outcomes: true     Toggle TNT/explosions/lava
  max-luck: 100                 Maximum luck value
  min-luck: -100                 Minimum luck value
  default-luck: 0                Crafted block luck
  particles-enabled: true        Visual effects
  sounds-enabled: true           Audio effects

lucky-sword:
  arrow-stream-chance: 0.05      5% chance
  vampirism-chance: 0.05         5% chance
  blindness-chance: 0.05         5% chance
  vampirism-heal: 6              Half-hearts healed
  arrow-count: 5                 Arrows per stream

lucky-bow:
  explosive-chance: 0.10         10% chance
  molten-chance: 0.10            10% chance
  meteorite-chance: 0.10         10% chance

outcomes:
  treasure:
    diamonds:
      weight: 50
      enabled: true
      min-amount: 1
      max-amount: 5
    netherite-armor:
      weight: 10
      enabled: true
   ... more outcomes

Key Configuration Options

Option	Effect
`destructive-outcomes: false`	Disables TNT, explosions, lava placement
`particles-enabled: false`	Disables all particle effects
`sounds-enabled: false`	Disables all sound effects
Outcome `enabled: false`	Removes outcome from pool
Outcome `weight: 0`	Effectively disables outcome

️ Technical Architecture

Data Flow

┌─────────────┐     ┌──────────────────┐     ┌───────────────┐
│   Player    │────▶│  BlockListener   │────▶│OutcomeManager │
│ Breaks Block│     │ Validates Block  │     │Selects Outcome│
└─────────────┘     └──────────────────┘     └───────┬───────┘
                                                     │
                    ┌──────────────────┐             │
                    │  LuckyOutcome    │◀────────────┘
                    │   .execute()     │
                    └────────┬─────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                    ▼
   ┌─────────┐         ┌──────────┐         ┌─────────┐
   │ Spawns  │         │  Builds  │         │ Drops   │
   │  Mobs   │         │Structure │         │ Items   │
   └─────────┘         └──────────┘         └─────────┘

PersistentDataContainer Keys

Key	Type	Used For
`lucky_block`	Boolean	Identify Lucky Blocks
`luck_level`	Integer	Store luck value
`lucky_sword`	Boolean	Identify Lucky Swords
`lucky_bow`	Boolean	Identify Lucky Bows
`lucky_potion`	Boolean	Identify Lucky Potions

Thread Safety

All block modifications run on main thread
Scheduled tasks use BukkitRunnable
ThreadLocalRandom for random values
No async operations that modify world state

Class-by-Class Breakdown

Main Classes

Class	Purpose
`PaperLuckyBlocks`	Plugin main, commands, lifecycle
`LuckyBlockManager`	Item creation, recipes, validation
`OutcomeManager`	Outcome registration, weighted selection

Listener Classes

Class	Events Handled
`BlockListener`	BlockPlaceEvent, BlockBreakEvent
`ItemListener`	EntityDamageByEntityEvent, EntityShootBowEvent, PotionSplashEvent

Outcome Classes

Class	Category	Positive	Destructive
`DiamondOutcome`	Items	✅	❌
`NetheriteArmorOutcome`	Items	✅	❌
`GiantBobOutcome`	Mobs	❌	❌
`BeeSwarmOutcome`	Mobs	❌	❌
`CageTrapOutcome`	Structures	❌	✅
`ChestTowerOutcome`	Structures	✅	❌
`TNTOutcome`	Explosions	❌	✅
`ExplosionOutcome`	Explosions	❌	✅
`WishingWellOutcome`	Special	✅	❌

Base Classes

Class	Purpose
`LuckyOutcome`	Interface defining outcome contract
`AbstractOutcome`	Base implementation with utilities

---**

PaperLuckyBlock

📖About PaperLuckyBlock