Configuration Reference

Steal-A-Block separates runtime player data from administrative tuning. All human-editable settings live in YAML files within the plugins/StealABlock/ directory, while dynamic player progress, inventories, and statistics are stored in an asynchronous SQLite database (stealablock.db).

Most configuration changes can be reloaded instantly without restarting the server by running /sab reload or /asb reload.

Configuration File Ecosystem

flowchart TD
    subgraph Core Configuration Files
        C["config.yml<br>Economy, Rebirth, Prestige, Drone, Limits"]
        D["defenses.yml<br>Traps, Sirens, Bank Vault"]
        E["events.yml<br>Conveyor Modifiers, Mystery Blocks"]
        K["contracts.yml<br>Daily Heist Board, Objectives, Rewards"]
        A["arenas.yml<br>Plot Bounds, Gates, Conveyor Points"]
        S["scoreboard.yml<br>Scoreboard HUD, Tablist, MiniMessage"]
        M["messages.yml<br>Player Text, Prefixes, Error Prompts"]
    end
    C & D & E & K & S & M -->|"/sab reload"| LiveEngine["Live Server Engine"]
    A -->|"Server Shutdown"| OfflineStorage["Disk Persistence"]

Configuration File	Primary Role	Reload Command	Requires Restart?
`config.yml`	Economy base values, rebirth scaling, prestige limits, drone parameters, world rules	`/sab reload`	No
`defenses.yml`	Slime stun trap potion effects, siren beep intervals, bank vault rules	`/sab reload`	No
`events.yml`	Mystery block unboxing odds, conveyor event multipliers (`OVERDRIVE`, `REVERSE_RUSH`)	`/sab reload`	No
`contracts.yml`	Daily heist board targets, credit rewards, reroll and instant finish costs	`/sab reload`	No
`arenas.yml`	Low-level plot coordinates, conveyor trajectories, gate bounding boxes	`/asb reload`	Yes (for manual edits)
`scoreboard.yml`	Scoreboard sidebar layout, tablist header/footer, update frequencies	`/sab reload`	No
`messages.yml`	In-game notifications, action bar text, chat formats, color codes	`/sab reload`	No

Warning

Never hand-edit arenas.yml while the server is running. The plugin serializes arena states on server shutdown, which will overwrite any external changes you made while online. Always stop the server before manually modifying arenas.yml, or use the in-game setup commands (/asb checklist or /asb setup).

Core Settings (`config.yml`)

The primary configuration file governs economic constants, progression reset costs, premium credit items, and visual presentation systems.

License Configuration

Every instance requires a valid license key registered through the official community portal.

# License configuration
license:
  # The license key purchased for this plugin
  # To get a license and support join https://discord.yowsef.xyz
  key: "YOUR_LICENSE_KEY_HERE"

Economy & Holograms

Controls the starter balance for new players and visibility distances for plot display tags.

# Starting balance for new players, rebirthed players, and prestiged players.
# Changing this value applies globally across all reset routines.
starting-balance: 50.0

# Hologram view range multiplier (1.0 = 16 blocks; 3.0 = 48 blocks)
hologram-view-range: 3.0

starting-balance: The default liquid cash assigned to any player entering their first plot, or resetting during rebirth/prestige.
hologram-view-range: Controls the client-side packet visibility range for floating price and rate displays. Setting this to 3.0 renders holograms up to 48 blocks away.

Rebirth Progression Ladder

Rebirth resets current liquid cash and plot blocks in exchange for permanent account multipliers.

$$\text{Cost}(\text{level}) = \text{base-cost} + (\text{level} - 1) \times \text{cost-per-level}$$

rebirth:
  max-level: 30
  base-cost: 500000.0             # Rebirth 1 costs $500,000
  cost-per-level: 1000000.0       # Each subsequent level adds $1,000,000
  boost-per-level: 0.5            # +0.5x income multiplier per level (1.0x -> 1.5x -> 2.0x)
  starting-cash-per-level: 100.0  # Reset cash = level * 100.0 (Level 0 uses starting-balance)

Parameter	Type	Default	Description
`max-level`	Integer	`30`	Highest rebirth level achievable by players.
`base-cost`	Double	`500000.0`	Cash required to complete Rebirth 1 ($500k).
`cost-per-level`	Double	`1000000.0`	Cost increase added per additional rebirth level ($1.0M).
`boost-per-level`	Double	`0.5`	Permanent income multiplier bonus added to all plot anvils per rebirth.
`starting-cash-per-level`	Double	`100.0`	Starter cash provided upon reset ($100 $\times$ Rebirth Level).

Prestige Requirements

Prestige represents vertical plot growth, unlocking additional floors, fortified gates, and vault security.

prestige:
  rebirths-per-prestige: 10       # Requires 10 rebirths per prestige tier
  base-money: 100000000.0         # Prestige 1 requires $100,000,000
  money-per-prestige: 100000000.0 # Each tier adds $100,000,000

Formula: $\text{Cash}(\text{target}) = \text{target} \times $100,000,000$ and $\text{Rebirths}(\text{target}) = \text{target} \times 10$.
Prestige also requires holding or consuming 1 GOAT-tier block per ascension.

Credits Store (Premium Utility)

Credits are earned via daily heist contracts and milestone achievements. They purchase summons and server boosters.

credits:
  summon-epic: 25        # Cost to force-spawn an Epic block on your plot
  summon-legendary: 50   # Cost to force-spawn a Legendary block
  summon-mythic: 250     # Cost to force-spawn a Mythic block
  summon-goat: 500       # Cost to force-spawn a GOAT block
  server-luck: 200       # Cost to trigger a 15-minute 2x rare block conveyor booster

Gear Price Overrides

Allows administrators to adjust shop prices for tactical raiding gear without editing compiled defaults.

gear-prices:
  swift_boots: 50000
  income_booster_iii: 3000000
  # fortune_pick: 250000
  # guardian_shield: 750000

Cinematic Drone Showcase

Configures the Catmull-Rom spline camera flythrough that welcomes new players to arena plots.

cinematic:
  enabled: true
  flight-speed: 0.45       # Blocks traveled per tick along spline (0.1 to 2.0)
  hover-seconds: 6         # Seconds paused at each waypoint station
  skippable: true          # Enables jumping or sneaking to skip
  directed-camera: false   # false = 360-degree free look; true = lock to focal point
  bossbar: true            # Displays top segmented progress bar
  actionbar-ticker: true   # Shows instructional gameplay hints on action bar
  sound-effects: true      # Plays station arrival chimes
  only-first-join: true    # Plays automatically only on first plot join

World Management & Performance Toggles

Keeps arena environments clean without impacting separate survival or creative worlds on the server.

# Opt-in world locking (arena worlds only)
manage-world-time: true
manage-weather: true
world-time: 6000

# Rainbow glow team scoreboard isolation
rainbow-teams-on-main-scoreboard: false

# Conveyor entity limit per arena
conveyor:
  max-blocks: 24

manage-world-time & manage-weather: When enabled, the plugin pins time to midday (6000) and suppresses rain inside arena worlds only.
rainbow-teams-on-main-scoreboard: Keeps rainbow block glowing teams on per-player virtual scoreboards instead of the global server board, preventing compatibility conflicts with TAB or DeluxeHub.
conveyor.max-blocks: Caps simultaneous display entity blocks on the conveyor belt to 24 per arena.

Base Defenses (`defenses.yml`)

Defensive traps, auditory sirens, and bank vaults protect plots from rival heists. All mechanical settings live in defenses.yml.

# Slime Stun Trap Configuration
slime-stun-trap:
  enabled: true
  price: 5000.0             # Purchase price from plot gear vendor
  max-per-plot: 3           # Hard limit per plot
  slowness:
    duration-ticks: 60      # 60 ticks = 3.0 seconds
    amplifier: 3            # Amplifier 3 = Slowness IV
  blindness:
    duration-ticks: 50      # 50 ticks = 2.5 seconds
    amplifier: 0            # Amplifier 0 = Blindness I
  particles:
    type: "ITEM_SLIME"
    count: 30
    spread-x: 0.3
    spread-y: 0.2
    spread-z: 0.3
    speed: 0.1

# Intruder Siren Configuration
intruder-siren:
  enabled: true
  beep-interval-ticks: 20   # Audio alarm chime frequency (20 ticks = 1.0 second)

# Bank Vault Pedestal Configuration
bank-vault:
  enabled: true
  min-prestige: 2           # Requires Prestige 2 OR Rebirth 1
  min-rebirth: 1            # Unlocks vault access
  max-vaulted-blocks: 1     # Number of simultaneous protected anvils
  immune-to-theft: true     # Prevents all theft channeling on the vaulted block
  hologram-text: "&#FFD700★ &#FFF275[VAULT SECURED] &#FFD700★"

Defense Tuning Mechanics

Channel Interruption: When an intruder steps on a Slime Stun Trap while channeling a theft, their channel timer is instantly aborted.
Siren Pacing: The beep-interval-ticks: 20 parameter controls how often the directional alarm pulses toward the plot owner during an active raid.
Theft Immunity: Setting immune-to-theft: true completely disables raid interactions on the vaulted anvil. Intruders who right-click receive an error message and a deflection sound cue.

Events & Conveyor Dynamics (`events.yml`)

Controls spontaneous server modifiers and mystery block unboxing odds.

# Mystery Block Spawn & Unboxing
mystery-blocks:
  enabled: true
  spawn-chance: 0.03          # 3% chance for any conveyor block to spawn as Mystery
  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

  # Probability distribution when placed on plot anvil
  unboxing:
    mutations:
      rainbow-chance: 0.02    # 2% chance for Rainbow (15x income)
      diamond-chance: 0.08    # 8% chance for Diamond (6x income)
      golden-chance: 0.25     # 25% chance for Golden (2.5x income)
      # Remaining 65% unboxes as Normal base block

# Real-time Conveyor Modifiers
conveyor-events:
  OVERDRIVE:
    speed-multiplier: 3.0     # 3.0x conveyor velocity
    duration-seconds: 180     # 3 minutes
    boss-bar:
      color: "YELLOW"
      style: "SOLID"

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

# Automatic Event Rotation Scheduler
auto-events:
  enabled: true
  interval-minutes: 60        # Triggers a random event every 60 minutes
  event-duration-seconds: 300 # Default event duration (5 minutes)
  events:
    - DOUBLE_INCOME
    - LIGHTNING_STORM
    - FUSION_FRENZY
    - OVERDRIVE
    - REVERSE_RUSH

Mystery Unboxing Table

Mutation Outcome	Probability	Income Multiplier	Visual Effects
Rainbow Mutation	2.0%	$15.0\times$	Cycling RGB animated glowing outline
Diamond Mutation	8.0%	$6.0\times$	Aqua shimmer particles with cyan outline
Golden Mutation	25.0%	$2.5\times$	Gold sparkle particles with yellow outline
Normal Base Block	65.0%	$1.0\times$	Standard block appearance

Heist Contracts (`contracts.yml`)

The daily bounty board assigns three tiered objectives every 24 hours. Completing tasks provides cash and credits.

# Board Action Sinks
reroll-cost: 15              # Credits to reroll an unwanted contract
finish-cost: 40              # Credits to immediately autocomplete a contract
clear-bonus-credits: 15      # Extra credits awarded when clearing all 3 daily jobs

# Target thresholds per objective: [Tier 1, Tier 2, Tier 3]
targets:
  steal: [2, 4, 8]                           # Rival plot blocks stolen
  earn: [100000, 500000, 2000000]            # Passive income accumulated ($)
  deposit: [1, 3, 6]                         # Conveyor blocks carried to deposit zone
  fuse: [1, 2, 4]                            # Successful fusion chamber combinations

# Reward distribution: [Tier 1, Tier 2, Tier 3]
rewards:
  credits: [6, 16, 32]
  money: [15000, 100000, 450000]

Daily Heist Reward Matrix

Tier	Objective Difficulty	Cash Reward	Credit Reward	Notes
Tier 1	Casual starter task	$15,000	6 Credits	Accessible to any new plot owner
Tier 2	Active arena gameplay	$100,000	16 Credits	Requires moderate raiding or earning
Tier 3	High-intensity heist challenge	$450,000	32 Credits	Requires 8 steals, 4 fusions, or $2M income
Clear Bonus	Clear all 3 daily tasks	—	+15 Bonus Credits	Awarded automatically upon claiming Job 3

$$\text{Total Daily Earning Potential} = 6 + 16 + 32 + 15 = \mathbf{69\text{ Credits}}$$

Arena Storage & Coordinate Schemas (`arenas.yml`)

arenas.yml stores structural bounds, plot allocations, and conveyor trajectories. While created through the guided setup tools (/asb checklist or /asb setup), administrators can inspect and verify raw coordinates.

Coordinate Serialization Format

Locations are serialized as comma-separated values:

$$\text{\texttt{world,x,y,z,yaw,pitch}}$$

Example: arena_world,124.50,65.00,-88.50,90.0,0.0

Annotated Arena Schema

arenas:
  alpha:
    world: "arena_world"
    enabled: true
    pos1: "arena_world,100,60,-100,0,0"         # Arena bounding box corner 1
    pos2: "arena_world,250,90,100,0,0"          # Arena bounding box corner 2
    conveyor:
      start: "arena_world,120.5,65.0,-80.5,0,0" # Conveyor block spawn origin
      end: "arena_world,230.5,65.0,-80.5,0,0"   # Conveyor block despawn terminal
    balance_top: "arena_world,175.5,67.0,-95.5,0,0"   # Richest player leaderboard
    rebirth_top: "arena_world,179.5,67.0,-95.5,0,0"   # Highest rebirth leaderboard
    goal_hologram: "arena_world,177.5,68.0,-95.5,0,0" # Community goal status
    plots:
      plot_1:
        spawn: "arena_world,130.5,65.0,-50.5,180.0,0.0"
        pos1: "arena_world,122,64,-60,0,0"
        pos2: "arena_world,138,75,-44,0,0"
        # Perimeter Security Gates
        gate_pos1: "arena_world,129,65,-44,0,0"
        gate_pos2: "arena_world,131,67,-44,0,0"
        gate_plate: "arena_world,130.5,65.0,-46.5,0,0"
        # Prestige Expansion Gates
        gate2_pos1: "arena_world,129,65,-41,0,0"
        gate2_pos2: "arena_world,131,67,-41,0,0"
        gate2_plate: "arena_world,130.5,65.0,-43.5,0,0"
        gate3_pos1: "arena_world,129,65,-38,0,0"
        gate3_pos2: "arena_world,131,67,-38,0,0"
        gate3_plate: "arena_world,130.5,65.0,-40.5,0,0"
        # Plot Infrastructure
        conveyor_center: "arena_world,130.5,65.0,-80.5,0,0"
        gear_shop: "arena_world,124.5,65.0,-55.5,90.0,0.0"
        storage_anvil: "arena_world,130.5,65.0,-55.5,0.0,0.0"
        hologram: "arena_world,130.5,67.0,-55.5,0.0,0.0"
        rate_hologram_location: "arena_world,130.5,66.4,-55.5,0.0,0.0"
        deposit_pos1: "arena_world,135,64,-58,0,0"
        deposit_pos2: "arena_world,137,66,-56,0,0"
        # Prestige Tower Vertical Volumes
        prestige1_pos1: "arena_world,122,76,-60,0,0"
        prestige1_pos2: "arena_world,138,87,-44,0,0"
        prestige2_pos1: "arena_world,122,88,-60,0,0"
        prestige2_pos2: "arena_world,138,99,-44,0,0"

Tip

When adding new arenas, use /asb duplicate <source> <target> rather than writing YAML coordinates manually. FastAsyncWorldEdit copies the physical arena geometry while Steal-A-Block calculates offset coordinate entries automatically.

Scoreboard & Display HUD (`scoreboard.yml`)

The scoreboard and tablist display real-time player statistics and server status.

scoreboard:
  enabled: true
  update-interval-ticks: 20   # Updates once per second (20 ticks)
  title: "<shadow:#000000FF>&#00FF12StealABlock"
  lines:
    - ""
    - "<shadow:#000000FF>&#FFFFFFStats"
    - "<shadow:#000000FF>&#808080Money: &#00FF12$%balance_formatted%"
    - "<shadow:#000000FF>&#808080Rebirth: &#00FF12%rebirth%"
    - "<shadow:#000000FF>&#808080Credits: &#00FF12%credits%"
    - "<shadow:#000000FF>&#808080Money Boost: &#00FF12%money_boost%x"
    - "<shadow:#000000FF>&#808080Prestige: &#00FF12%prestige%"
    - ""
    - "<shadow:#000000FF>&#00FF12Information"
    - "<shadow:#000000FF>&#808080Online: &#00FF12%online%&#808080/&#00FF12%max_players%"
    - "<shadow:#000000FF>&#808080Store: &#FFAA00/credits"
    - "<shadow:#000000FF>&#808080Discord: &#55FFFFdiscord.gg/yourinvite"
    - ""
    - "<shadow:#000000FF>&#FFFFFFyourdomain.xyz"

tablist:
  enabled: true
  update-interval-ticks: 20
  header:
    - ""
    - "<shadow:#000000FF>&#00FF12StealABlock"
    - "<shadow:#000000FF>&#808080Online: &#00FF12%online%"
    - ""
  footer:
    - ""
    - "<shadow:#000000FF>&#808080TPS: &#00FF12%tps%"
    - "<shadow:#000000FF>&#FFAA00Support the server with &#FF77FF/credits&#FFAA00!"
    - ""
    - "<shadow:#000000FF>&#808080-------- &#FFFFFFyourdomain.xyz &#808080--------"
    - ""

Color Formatting Standards

Hex Color Codes: Use &#RRGGBB format (e.g. &#FFFFFF for pure white, &#FFAA00 for orange).
Brand Emerald Gradient: &#00FF12 is recognized by the internal color engine and automatically renders as a smooth emerald-to-lime gradient.
MiniMessage Shadow Tags: Wrap lines in <shadow:#000000FF> to render high-contrast text shadows on modern 1.21+ clients.

HUD Placeholder Reference

Placeholder	Replaced Value	Example Output
`%player%`	Viewer's username	`Alex`
`%online%`	Current online player count	`42`
`%max_players%`	Server player slot limit	`100`
`%tps%`	Current server ticks per second	`20.0`
`%balance%`	Unformatted numeric cash balance	`1540250.0`
`%balance_formatted%`	Human-readable abbreviated cash	`1.5M`
`%rebirth%`	Current player rebirth level	`4`
`%credits%`	Available premium credit currency	`135`
`%money_boost%`	Current total income multiplier	`3.0`
`%prestige%`	Current player prestige tier	`1`

Localization & In-Game Messaging (`messages.yml`)

All user-facing messages, title alerts, and sound associations are customized in messages.yml.

prefix: "&#555555[&#00FF12StealABlock&#555555] "

arena:
  joined: "%prefix%&#00FF12You joined the arena!"
  left: "%prefix%&#FF0000You left the arena!"
  full: "%prefix%&#FF0000Arena is full!"
  already_have_plot: "%prefix%&#FF0000You already have a plot! Leave your current arena first."

block:
  collected: "%prefix%&#00FF12Block collected! It's heading to your plot."
  sold: "%prefix%&#00FF12Block sold for &#FFFFFF$%amount%&#00FF12!"
  collected_income: "&#00FF12+$%amount%"

defense:
  trap:
    intruder_title: "&#FF0000STUN TRAP TRIGGERED!"
    intruder_subtitle: "&#FFAA00You stepped into sticky slime!"
    owner_title: "&#00FF12TRAP TRIGGERED!"
    owner_subtitle: "&#FFAA00%intruder% stepped on your defense trap!"
  siren:
    intruder_title: "&#FF0000⚠ INTRUDER ALERT! ⚠"
    intruder_subtitle: "&#FFAA00Someone is stealing your %block%!"
    stolen_alert: "&#FF0000✘ YOUR %block% WAS STOLEN BY %thief%!"
  vault:
    locked: "&#00FF12Block successfully locked in your Bank Vault! It cannot be stolen."
    cannot_steal: "&#FF0000This block is secured inside a Bank Vault and cannot be stolen!"

Dynamic Tokens: Never rename placeholder tokens like %amount%, %block%, %thief%, or %intruder%. The engine substitutes these values before parsing color formatting.

Performance Optimization (40+ Concurrent Players)

Running high-capacity tycoon minigames with dozens of players active across multiple arenas requires careful resource allocation. Steal-A-Block is built specifically to eliminate traditional server lag sources.

flowchart TD
    subgraph Traditional Lag Vectors
        A1["Legacy Armor Stands / Falling Blocks<br>Server Physics & Hitbox Calculations"]
        A2["Synchronous YAML Writes<br>Main Thread File I/O Freezes"]
    end
    subgraph StealABlock Solutions
        B1["Modern Display Entities<br>Zero Server Physics • Client Packet Interpolation"]
        B2["Asynchronous SQLite WAL<br>Zero Main-Thread Locking • Memory Mapped Writes"]
    end
    A1 -. Replace .-> B1
    A2 -. Replace .-> B2

1. Modern Display Entities vs. Legacy Armor Stands

Older minigames used invisible Armor Stands or Falling Sand entities to animate moving blocks. In Minecraft, Armor Stands require server-side ticking, gravity checks, bounding box calculations, and equipment slot tracking. Running 40 moving blocks per arena across 4 arenas meant ticking 320 complex entity objects every tick.

Steal-A-Block uses vanilla 1.21 BlockDisplay and TextDisplay entities:

Zero Physics Overhead: Display entities have no collisions, no gravity calculations, and no server-side ticking logic.
Client-Side Linear Interpolation: Position updates are broadcast via lightweight translation packets. By setting interpolation_duration: 1 and interpolation_delay: -1, client graphics drivers smoothly glide blocks between points without server micro-stutter.
Entity Budget Cap: Setting conveyor.max-blocks: 24 keeps visual conveyor density high while cutting packet volume by 40% compared to legacy setups.

2. Asynchronous SQLite Database & WAL Mode

Rather than serializing hundreds of individual player YAML files, Steal-A-Block records all runtime transactions inside a single SQLite database (stealablock.db).

The database engine is configured with high-performance operational pragmas on initialization:

PRAGMA journal_mode=WAL;: Write-Ahead Logging allows background writer threads to execute without blocking read operations.
PRAGMA synchronous=NORMAL;: Synchronizes critical transactions during checkpoints while letting normal updates stream without waiting on physical disk platters.
PRAGMA busy_timeout=5000;: Waits up to 5 seconds if a write lock occurs, preventing database busy exceptions during traffic spikes.
Indexed Queries: Dedicated B-tree indexes (idx_players_balance, idx_players_rebirth, idx_player_blocks_uuid) accelerate top leaderboard queries from $O(N)$ full table scans down to instant $O(\log N)$ lookups.

3. High-Density Production Recommendations

For production networks hosting 40 or more concurrent players per server instance:

Configuration Setting	Recommended Production Value	Performance Rationale
`conveyor.max-blocks`	`20` – `24`	Caps moving entities at 48 per active arena, keeping network traffic minimal.
`hologram-view-range`	`1.5` – `2.0`	Restricts floating text packets to within 24–32 blocks of the viewer.
`scoreboard.update-interval-ticks`	`20` (1 second)	Prevents packet flooding from high-frequency text changes.
`tablist.update-interval-ticks`	`40` (2 seconds)	Halves tablist packet broadcasts with negligible visual difference.
`rainbow-teams-on-main-scoreboard`	`false`	Keeps team glows isolated to individual player scoreboards.
Java Garbage Collector	Aikar's G1GC Flags	Mitigates stop-the-world GC pauses during heavy schematic duplication.
FAWE Disk Caching	Enabled	Prevents memory allocation spikes during vertical prestige tower building.

With these settings applied, Steal-A-Block easily maintains a steady 20.0 TPS with sub-1ms tick execution times under heavy 40+ player loads.