**---

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

```java
// 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

```yaml
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 |

---**

Need a server to run PaperLuckyBlock?
Get 24/7 high-performance hosting from reliable hosting for your community!
Click here to get started with KCB Hosting