Heists & Conveyor Belts

Steal-A-Block combines automated tycoon income generation with active, high-stakes base infiltration. Players purchase income-generating blocks from a central conveyor river, position them on plot anvils to earn passive $/second, and stage daring stealth heists into enemy bases to seize their highest-earning assets.

This guide covers the end-to-end mechanics of in-arena raiding, client-side display entity conveyor physics, live surge modifiers, and mystery block mutation unboxings.

---

In-Arena Theft (The Heist Loop)

The theft cycle is an active, four-phase PvP mechanic designed for tension, tactical counterplay, and risk management.

flowchart LR
    A["1. Infiltration"] --> B["2. 5s Channeling"]
    B --> C["3. Block Portation"]
    C --> D["4. Base Deposit"]
    B -. Interrupt .-> E["Reset & Neutralized"]
    C -. Thief Killed .-> F["Returned to Victim"]

Phase 1: Infiltration & Target Reconnaissance

Raiders enter rival bases during active arena rounds to identify high-value targets. Before attempting a theft, raiders must evaluate three base defense layers:

1. Security Gate Status: Base gates toggle between open and closed via /lockbase or the plot's gold pressure plate. If a gate is closed, intruders cannot interact with protected anvils.
2. Guardian Shield Gear: If the target base owner has purchased and activated a Guardian Shield from the Tactical Gear Shop (/gear), the base is immune to theft until the shield expires.
3. Server Shield Hour: If the server-wide SHIELD_HOUR event is active, theft is disabled across all plots.

---

Phase 2: The 5-Second Theft Channel

To initiate a heist, an intruder interacts with (left-clicks or right-clicks) an enemy anvil that holds a stored block. This starts the theft countdown timer.

• Base Duration: 5 continuous seconds (baseStealDuration = 5s).
• Gear Modifiers: Wearing a Steal Glove from the gear shop reduces channeling time. However, the system enforces a hard minimum threshold of 1 second (Math.max(1, baseStealDuration - gearReduction)), guaranteeing defenders at least one second of counterplay.
• Plot Tether: The thief must remain strictly inside the victim's plot boundaries (including a ±2 block perimeter buffer). If the thief steps outside this area, channeling instantly cancels with the message You left the plot! Steal cancelled!.
• Disruption & Interruption: Receiving damage, sustaining knockback outside the plot boundaries, logging out, or dying immediately aborts the steal.

Intruder Siren & Defender Alerts

When channeling begins, the victim's base defense system immediately alerts the base owner:

Defense Alert	Trigger & Frequency	Visual / Audio Output	Configuration Key
Siren Alarm	Ticks every 20 ticks (1.0s)	Plays defense_siren_alarm audio to victim	intruder-siren.beep-interval-ticks: 20
Screen Title	Instant upon channel start	Red title BLOCK STOLEN! and subtitle with thief name	messages.yml (defense.siren.intruder_title)
Thief Countdown	Ticks every 20 ticks (1.0s)	Thief sees on-screen title Stealing - X Seconds left...	Internal scheduler (20-tick interval)
Neutralized Cue	Upon interruption or escape	Victim receives chat notification and defense_siren_neutralized	messages.yml (defense.siren.neutralized)

# defenses.yml - Intruder Siren Configuration
intruder-siren:
  enabled: true
  beep-interval-ticks: 20   # How often the siren beeps while a player is channeling theft (20 ticks = 1s)

---

Phase 3: Block Portation & High-Visibility Escape

When the 5-second countdown reaches zero, the block is successfully detached from the victim's anvil:

1. Helmet Mounting: The stolen block material instantly snaps onto the thief's helmet slot (thief.getInventory().setHelmet(helmet)).
2. Lockdown Against Unequip: The thief cannot remove the block from their armor slot (InventoryClickEvent is canceled for slot 39).
3. High-Visibility Nametag: A floating red Stolen! text display entity spawns 2.8 blocks above the thief's head. It billows toward all players within a 3.0-block radius (hologram-view-range: 3.0), rendering the thief easily identifiable across the arena.
4. Base Gate Lockdown: The thief's own base security gate automatically locks shut (lockThiefGate). This prevents thieves from leaving their gate wide open for an effortless, instant escape.
5. Contract Progress: Successful theft completion automatically credits progress toward active Heist Board contracts (ContractType.STEAL).

---

Phase 4: Base Deposit & Anti-Duplication Protection

The thief must sprint across the open arena back to their own claimed plot to secure the block into their income stream:

1. Empty Anvil Deposit: The thief locates an empty anvil on their own plot and right-clicks it.
2. Locking Income: The block is removed from the thief's head and placed onto the anvil as an active StoredBlockData instance, generating passive $/second.
3. Milestone Discovery:
   • If this block is a new discovery for the player, the discovery is registered in PlayerDataManager.
   • Bonus Credits are rewarded based on the block's rarity tier (Common through GOAT).
   • Lifetime stolen block counters increment for milestone rewards (/milestones).
4. Thief Elimination Handling (onPlayerDeath):
   • If an opponent eliminates the thief during the escape, the stolen block material is stripped from the death drops to prevent item duplication.
   • The plugin automatically teleports the stolen block back to the victim's first empty plot anvil.
   • The victim receives a green chat notification: Your stolen <Block> has been returned to your plot because the thief died!.
5. Combat Log Safeguards (onPlayerQuit):
   • If a thief disconnects or crashes while carrying a stolen block, the block is returned to the original owner's plot anvil immediately. Combat-logging raiders cannot delete blocks from the economy.

---

Conveyor Belt Engine & Display Entity Architecture

Steal-A-Block replaces legacy falling block entities and armor stand towers with Minecraft 1.21 Display Entities (BlockDisplay and TextDisplay).

graph TD
    subgraph ConveyorBlock ["Conveyor Block Pair"]
        BD["BlockDisplay (Scale: 0.85, Offset: -0.425)"]
        TD["TextDisplay (+1.1 Y-Offset: Name & $/s)"]
    end
    Scheduler["ConveyorManager (Tick Interval: 1)"] --> ConveyorBlock
    ConveyorBlock --> Packet["Client-Side Packet Interpolation (Duration: 1, Delay: -1)"]
    Packet --> Screen["Zero Server Lag • No Piston Desync • True Silk Motion"]

Display Entity Physics & Performance

Traditional conveyor plugins use falling sand entities or invisible armor stands pushed by pistons. These cause severe TPS drops, entity jitter, and desynchronization. Steal-A-Block's engine operates with pure client-side packet interpolation:

Parameter	Core Value	Architectural Purpose
Block Size	0.85f	Scaled down slightly to prevent clipping along conveyor floor walls.
Centering Offset	-0.425f	Centers the display entity directly over conveyor guide blocks.
Text Offset	+1.1f Y	Positions floating name and $/s rate cleanly above the block.
Update Interval	1 tick	Sends position updates every tick for continuous movement.
Interpolation Duration	1 tick	Instructs the client to transition positions smoothly over 50ms.
Interpolation Delay	-1	Bypasses client-side interpolation lag, eliminating visual stuttering.
Base Velocity	0.068 blocks/tick	Optimized traversal velocity along the arena conveyor spline.
Spawn Cooldown	2400 ms	Enforces spacing between moving blocks (MIN_BLOCKS_DISTANCE = 5).

Capacity Limits for 20.0 TPS

Each moving conveyor item requires two entities (BlockDisplay + TextDisplay). Uncapped entities across multiple arenas will degrade server performance. Steal-A-Block enforces a strict per-arena ceiling:

# config.yml - Conveyor Performance Settings
conveyor:
  # Max moving blocks per arena. Capped at 24 blocks (48 display entities total)
  # to guarantee steady 20.0 TPS under 40+ concurrent player load.
  max-blocks: 24

Asynchronous SQLite Storage Engine

All block ownership, accumulated anvil balances, and plot states are recorded in a single SQLite database (stealablock.db).

• Write-Ahead Logging (WAL): The connection executes PRAGMA journal_mode=WAL; on startup, allowing concurrent reads while writes are serialized asynchronously.
• Atomic Transactions: In the event of a sudden server crash or power failure, zero transactions are lost, and YAML configuration files remain untouched and uncorrupted.

---

Live Conveyor Surges

Conveyor belts dynamically adjust their velocity and block distribution during server-wide conveyor surge events:

flowchart TD
    Surge["Conveyor Surge Event"]
    Surge --> Overdrive["OVERDRIVE (3.0x Velocity • 180s • Yellow Boss Bar)"]
    Surge --> ReverseRush["REVERSE_RUSH (2.2x Reverse Velocity • 120s • Purple Boss Bar)"]

Overdrive Surge

• Velocity Multiplier: 3.0x normal conveyor speed.
• Duration: 180 seconds (3 minutes).
• Boss Bar: Solid Yellow boss bar displayed to all players in the arena.
• Gameplay Dynamics: Blocks travel three times faster along the central river. Players must react quickly to claim high-tier items before they reach the hopper void, while rare block spawn frequencies increase.

Reverse Rush Surge

• Velocity Multiplier: 2.2x reverse conveyor speed.
• Duration: 120 seconds (2 minutes).
• Boss Bar: Solid Purple boss bar displayed to all players in the arena.
• Gameplay Dynamics: The conveyor river reverses direction. Blocks move backward past rival plots toward the spawn hopper, disrupting claiming routes and sparking intense player clashes near conveyor turns.

# events.yml - Conveyor Surges Configuration
conveyor-events:
  OVERDRIVE:
    speed-multiplier: 3.0     # 3x conveyor block velocity
    duration-seconds: 180     # 3 minutes
    boss-bar:
      color: "YELLOW"
      style: "SOLID"

  REVERSE_RUSH:
    speed-multiplier: 2.2     # 2.2x reverse surge velocity
    duration-seconds: 120     # 2 minutes
    boss-bar:
      color: "PURPLE"
      style: "SOLID"

---

Mystery Blocks & Mutation Rolls

Every block spawned onto the conveyor belt has a chance to generate as an encrypted Mystery Block.

pie title Mystery Block Unboxing Outcomes
    "Standard Base Block (Normal)" : 65
    "Golden Mutation (2.5x - 10x $/s)" : 25
    "Diamond Mutation (6x - 50x $/s)" : 8
    "Rainbow Mutation (15x - 200x $/s)" : 2

Visual Characteristics on the River

• Spawn Probability: 0.03 (3% chance per conveyor block spawn).
• Aura Particles: Continuous FIREWORK trail (count: 2, spread: 0.15, speed: 0.02) orbiting the block.
• Encrypted Hologram: Displays obfuscated pricing and mystery indicators:

  ★ Mystery [Block] ★
  ??? Hidden Mutation ???
  $???/s / $???
  

The Anvil Unboxing Ceremony

When a player purchases and delivers a Mystery Block to their plot anvil, the plugin triggers an unboxing roll. An unbox ceremony plays with sound cue event_mystery_claim, launching a color-coded firework above the anvil:

Mutation Tier	Roll Chance	Income Multiplier	Firework Color	Visual Style
Rainbow Mutation	2.0% (0.02)	15x to 200x $/s	Fuchsia (#FF00FF)	Shifting chromatic RGB text, high-value particle ring
Diamond Mutation	8.0% (0.08)	6x to 50x $/s	Aqua (#00FFFF)	Cyan crystalline sheen with enhanced sell value
Golden Mutation	25.0% (0.25)	2.5x to 10x $/s	Orange (#FFAA00)	Gilded gold particle glint
Standard Base Block	65.0% (0.65)	1.0x (Standard)	Yellow (#FFFF00)	Standard block definition and baseline income rate

# events.yml - Mystery Block Configuration
mystery-blocks:
  enabled: true
  spawn-chance: 0.03          # 3% chance for any conveyor spawn to become a mystery block
  hologram-text: "&#FFF275★ &#FFAA00&lMystery %block% &#FFF275★\n&#AAAAAA&o??? Hidden Mutation ???\n&#FFAA00$???/s &#808080/ &#00FF12$???"
  particles:
    type: "FIREWORK"
    count: 2
    spread: 0.15
    speed: 0.02

  unboxing:
    mutations:
      rainbow-chance: 0.02    # 2% chance for Rainbow Mutation (15x $/s)
      diamond-chance: 0.08    # 8% chance for Diamond Mutation (6x $/s)
      golden-chance: 0.25     # 25% chance for Golden Mutation (2.5x $/s)
      # Remaining 65% unboxes as Normal base block