Logo
PaperLuckyBlock
PluginLicenseRef-All-Rights-Reserved

PaperLuckyBlock

A plugin that converts lucky block mod into plugin......

122
Downloads
1
Followers
4 months ago
Updated
📦
1
Versions
utilitypaper
Download Latestv1.0.0View on Modrinth

📖About PaperLuckyBlock

**---

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:

  1. Spawns 1-5 diamonds (configurable)
  2. Each diamond has upward velocity with spread
  3. Diamonds glow and have custom name "★ Diamond ★"
  4. Ring of falling dust particles
  5. 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:

  1. Spawns invisible armor stand with full netherite set
  2. Armor stand rotates and bobs for 3 seconds
  3. After display, armor drops with velocity
  4. Each piece has custom name and lore
  5. 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:

  1. Spawns Giant zombie named "★ BOB THE GIANT ★"
  2. Bob has 100 HP (50 hearts)
  3. Bob deals 15 damage per hit
  4. Bob has fire resistance and glows
  5. 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:

  1. Builds 3x3x4 iron bar cage around player
  2. Construction is animated layer by layer
  3. Iron block floor, iron bar walls
  4. Water source on ceiling (drowning hazard)
  5. Player gets Mining Fatigue II
  6. 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:

  1. Builds tower of 5 levels (configurable)
  2. Each level has gold block platform + chest
  3. Ladders connect levels
  4. 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:

  1. Builds decorative wishing well structure
  2. Gold nuggets fountain from center (20 total)
  3. Occasional special items (ingots, gems)
  4. 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

---**