Skip to content

L‐Bedwars Wiki

Jump to bottom
squezsaz edited this page Jun 23, 2026 · 2 revisions

L-BedWars Wiki

Table of Contents

  1. Overview
  2. Installation
  3. Configuration
  4. Commands
  5. Permissions
  6. Arena Setup
  7. Game Modes
  8. Shop System
  9. Team Upgrades
  10. Generator System
  11. Compass Tracker
  12. TabList System
  13. Scoreboard System
  14. Chat System
  15. Spectator System
  16. Party System
  17. Level & XP System
  18. Daily Rewards
  19. Cosmetics
  20. Proxy Mode
  21. Database
  22. PlaceholderAPI
  23. API
  24. Language System
  25. Performance
  26. Troubleshooting

Overview

L-BedWars is a feature-rich BedWars plugin for Paper/Spigot 1.19+ servers.It supports Folia's regionized threading and can operate in standalone mode or multi-server proxy mode via the companion L-BedWarsProxy plugin.

Key Features

  • Full BedWars Gameplay — Solo, Duo, Trio, and Quad modes with team auto-balancing
  • Dual PvP Mode — CLASSIC (1.8 no attack cooldown) or MODERN (1.9+ mechanics)
  • Shop — 6 categories, tiered items, multiple currencies (iron, gold, diamond, emerald)
  • Team Upgrades — Sharpness, Protection, Haste, Forge, Heal Pool, Dragon Buff, and traps
  • Auto-Generators — Iron, Gold, Diamond, Emerald with timed tier upgrades
  • Compass Tracker — Purchase enemy tracking when few teams remain; actionbar shows distance and direction
  • Proxy Mode — Multi-server support via TCP socket communication; queue system, shared MySQL stats, leaderboard holograms
  • TabList — Colored team-sorted player names, configurable header/footer
  • Hologram System — ArmorStand-based leaderboard holograms, configurable per-stat
  • Queue System — Optional auto-queue when arenas are full with priority permissions
  • Cosmetics — Kill effects, victory dances, trails (Vault economy)
  • Level & XP — 100 levels with scaling XP requirements
  • PlaceholderAPI — 30+ placeholders for stats, level, game info, team, cosmetics
  • Folia Support — Region-scheduled tasks for Folia servers
  • Full API — Custom Bukkit events and LBedWarsAPI for external plugin integration

Components

Component Description
L-BedWars Core plugin running on game servers. Handles arena logic, shop, combat, upgrades.
L-BedWarsProxy Optional companion for BungeeCord/Velocity. Provides queue, shared stats, holograms, cross-server spectate.

Installation

Standalone Mode (Single Server)

  1. Download the latest L-BedWars.jar
  2. Place it in your server's plugins/ folder
  3. Restart the server
  4. Edit plugins/L-BedWars/config.yml to your preferences
  5. Set up arenas using the setup commands
  6. Enable arenas with /bwa enable <arena>

Proxy Mode (Multi-Server)

  1. Install L-BedWarsProxy.jar on your proxy server (BungeeCord/Velocity)
  2. Install L-BedWars.jar on each game server
  3. Configure config.yml on the proxy:
    • Set socket-token to a secure random string
    • Configure database section for MySQL
    • Set queue.enabled: true if desired
  4. Configure config.yml on each game server:
    • proxy-mode: true
    • proxy-socket-address: <proxy-ip>:<port>
    • socket-token: <matching-token>
  5. Restart all servers (proxy first, then game servers)

Requirements

Dependency Required Notes
Paper/Spigot 1.19+ Yes Folia also supported
Vault No Required for economy features
PlaceholderAPI No Required for placeholders
Parties API No Required for party integration
MySQL No Required for proxy mode stats

Configuration

config.yml — Main Configuration

# --- LANGUAGE ---
language: en
# Available: "en" (English), "tr" (Turkish)

# --- PVP MODE ---
pvp-mode: CLASSIC
# CLASSIC = 1.8 style (no attack cooldown), MODERN = 1.9+

# --- PROXY MODE ---
proxy-mode: false
proxy-socket-address: "127.0.0.1:5000"
socket-token: "change-me"

# --- STORAGE ---
storage:
  type: YAML
  # Available: YAML, SQLite, MySQL
  mysql:
    host: localhost
    port: 3306
    database: lbedwars
    username: root
    password: ""

# --- GAME SETTINGS ---
game:
  start-countdown: 15
  max-game-time: 1800
  end-lobby-delay: 20
  hunger: false
  blocked-blocks:
    - LAVA_BUCKET
    - WATER_BUCKET
  diamond-upgrade-times:
    - 480
    - 1200
  emerald-upgrade-times:
    - 600
    - 1440

# --- COMPASS TRACKER ---
compass-tracker:
  enabled: true
  cost: 2
  currency: EMERALD
  min-teams: 2
  update-interval: 10

# --- TABLIST ---
tablist:
  enabled: true
  sort-by-team: true
  header: "&6&lL-BedWars"
  footer: "&7play.example.com"

# --- SCOREBOARD ---
scoreboard:
  date-format: "dd/MM/yyyy"
  date-locale: "en"

# --- CHAT ---
chat:
  enabled: true
  global-prefix: "!"
  team-format: "{player}&f: {message}"
  global-format: "&a[G] {player}&f: {message}"
  waiting-format: "&7[Lobby] {player}&f: {message}"

shop.yml — Shop Configuration

Defines items, prices, categories, and upgrade paths. Each category has slots, icons, and item definitions with currency types and amounts.

upgrades.yml — Team Upgrades

Defines upgrade tiers, diamond costs, and effects for Sharpness, Protection, Haste, Forge, Heal Pool, Dragon Buff, and traps.

cosmetics.yml — Cosmetic Prices

Defines prices for kill effects, victory dances, and trails.

rewards.yml — Daily & Game Rewards

Configures daily reward cooldown, XP amounts, and coin rewards.

Commands

Player Commands

Command Aliases Permission Description
/bedwars help /bw help bedwars.play Display help menu
/bedwars join <arena> /bw join bedwars.play Join a specific arena
/bedwars leave /bw leave bedwars.play Leave current game
/bedwars randomjoin <mode> /bw randomjoin bedwars.play Join random arena of given mode
/bedwars list /bw list bedwars.play List available arenas
/bedwars stats [player] /bw stats bedwars.play Show stats for you or another player
/bedwars cosmetics /bw cosmetics bedwars.play Open cosmetics menu
/bedwars dailyreward /bw dailyreward bedwars.play Claim daily reward
/bedwars vote <map> /bw vote bedwars.play Vote for a map
/bedwars rejoin /bw rejoin bedwars.play Rejoin last game (bed must be alive)

Admin Commands

Command Aliases Permission Description
/bedwarsadmin help /bwa help bedwars.admin Admin help menu
/bedwarsadmin forcestart <arena> /bwa forcestart bedwars.admin Force start countdown
/bedwarsadmin addxp <player> <amount> /bwa addxp bedwars.admin Add XP to player
/bedwarsadmin setlobby <arena> /bwa setlobby bedwars.admin Set arena lobby spawn
/bedwarsadmin setspectator <arena> /bwa setspectator bedwars.admin Set spectator spawn
/bedwarsadmin setmainlobby /bwa setmainlobby bedwars.admin Set main lobby location
/bedwarsadmin setmode <arena> <mode> /bwa setmode bedwars.admin Set arena game mode
/bedwarsadmin addteam <arena> <name> <color> <max> /bwa addteam bedwars.admin Add a team to arena
/bedwarsadmin removeteam <arena> <name> /bwa removeteam bedwars.admin Remove a team from arena
/bedwarsadmin enable <arena> /bwa enable bedwars.admin Enable an arena
/bedwarsadmin disable <arena> /bwa disable bedwars.admin Disable an arena
/bedwarsadmin reload /bwa reload bedwars.admin Reload configuration
/bedwarsadmin tp <player> /bwa tp bedwars.admin Teleport to player as spectator
/bedwarsadmin hologram set <stat> — bedwars.admin Create leaderboard hologram
/bedwarsadmin hologram remove <id> — bedwars.admin Remove a hologram
/bedwarsadmin hologram list — bedwars.admin List all holograms

Setup Commands

Command Permission Description
/setup bedwars.setup Enter/exit arena setup mode
/setup setregion bedwars.setup Save selected world region
/setup setspawn <team> bedwars.setup Set team spawn location
/setup setbed <team> bedwars.setup Set team bed location (look at bed)
/setup setgenerator <type> bedwars.setup Add a generator point
/setup setshop bedwars.setup Set shop NPC location
/setup setupgrade bedwars.setup Set upgrades NPC location
/setup done bedwars.setup Finish arena setup

Proxy Commands (L-BedWarsProxy)

Command Permission Description
/bw join <mode> bedwars.play Join a mode (queues if full)
/bw rejoin bedwars.play Rejoin last game server
/bw stats [player] bedwars.play View MySQL stats
/bwa gui [filter] lbedwarsproxy.admin Open arena status GUI
/bwa tp <player> lbedwarsproxy.admin Cross-server spectate
/bwa leaderboard <stat> lbedwarsproxy.admin Open leaderboard GUI
/bwa hologram set <stat> lbedwarsproxy.admin Create hologram
/bwa hologram remove [id] lbedwarsproxy.admin Remove hologram
/bwa hologram list lbedwarsproxy.admin List holograms

Permissions

Permission Default Description
bedwars.play true Use player commands
bedwars.admin op Use admin commands
bedwars.setup op Use setup commands
bedwars.bypass op Bypass block break protection
lbedwarsproxy.play true Use proxy player commands
lbedwarsproxy.admin op Use proxy admin commands

Arena Setup

Step-by-Step Guide

  1. Enter Setup Mode

    /setup

    You will receive a blaze rod. Left-click and right-click to mark two corners of the arena region.

  2. Save Region

    /setup setregion

  3. Set Game Mode

    /bwa setmode <arena> <mode>

    Available modes: solo (1 player), duo (2), trio (3), quad (4)

  4. Add Teams

    /bwa addteam <arena> <name> <color> <max-players>

    Example: /bwa addwa addteam myarena Red RED 4

    Available colors: RED, BLUE, GREEN, YELLOW, AQUA, WHITE, PINK, GRAY

  5. Set Team Spawns

    Stand at the spawn point:

    /setup setspawn Red

  6. Set Team Beds

    Look directly at the bed block:

    /setup setbed Red

  7. Add Generators

    Stand at the generator location:

    /setup setgenerator IRON
/setup setgenerator GOLD
/setup setgenerator DIAMOND
/setup setgenerator EMERALD

  8. Add NPCs

    Stand at the NPC location:

    /setup setshop
/setup setupgrade

  9. Set Lobby Spawn

    /bwa setlobby <arena>

  10. Set Spectator Spawn

    /bwa setspectator <arena>

  11. Set Main Lobby (global, for all arenas)

    /bwa setmainlobby

  12. Finish and Enable

    /setup done
/bwa enable <arena>

Arena File Structure

Arenas are stored as YAML files in plugins/L-BedWars/arenas/. Each file contains:

  • Region corners (min/max coordinates)
  • Team definitions (spawn, bed, color, max players)
  • Generator locations and types
  • NPC locations
  • Game mode
  • Lobby and spectator spawns

Game Modes

Available Modes

Mode Players per Team Team Count Total Players
Solo 1 8 8
Duo 2 8 16
Trio 3 8 24
Quad 4 4-8 16-32

Game Flow

  1. WAITING — Players join, select teams, vote for maps
  2. STARTING — Countdown (configurable, default 15s), players are frozen
  3. PLAYING — Game active, generators spawn resources, shop/upgrades available
  4. ENDED — Winner announced, players sent to lobby after delay

PvP Mode

Configured via pvp-mode in config.yml:

  • CLASSIC — Removes attack cooldown, disables shield blocking (1.8 style combat)
  • MODERN — Default 1.9+ combat with attack cooldown

Game End Conditions

  • All teams except one eliminated (bed broken + all players eliminated)
  • Maximum game time reached (configurable, default 30 minutes)
  • Sudden death: after max time, all players take damage until one team remains

Diamond & Emerald Upgrade Times

Diamond and Emerald generators automatically upgrade at configured game times (in seconds):

diamond-upgrade-times:
  - 480   # Tier II at 8 minutes
  - 1200  # Tier III at 20 minutes

emerald-upgrade-times:
  - 600   # Tier II at 10 minutes
  - 1440  # Tier III at 24 minutes

Shop System

Categories

Category Slot Icon Items
Blocks 10 White Wool Wool, Hardened Clay/Stained Glass, End Stone, Wood, Obsidian, Ladders
Melee 11 Iron Sword Stone Sword, Iron Sword, Diamond Sword, Knockback Stick
Armor 12 Chainmail Boots Leather, Chainmail, Iron, Diamond (with upgrade paths)
Tools 13 Stone Pickaxe Pickaxe, Axe, Shears, Silk Touch (all upgradable)
Ranged 14 Bow Bow (Power I, II, III), Arrows, Fireballs
Potions 15 Potion Speed II (45s), Jump V (45s), Invisibility (30s)

Currencies

Currency Source
Iron Ingot Base generators (continuous)
Gold Ingot Base generators (continuous)
Diamond Diamond generators (mid map)
Emerald Emerald generators (mid map, tiered)

Armor Progression

Armor is purchased as a permanent upgrade for the game:

  1. Leather → Chainmail (40 iron)
  2. Chainmail → Iron (40 iron, requires Chainmail)
  3. Iron → Diamond (4 emeralds, requires Iron)

Each tier also has a protection level upgrade (purchased via upgrades NPC):

  • Protection I (5 diamonds)
  • Protection II (10 diamonds, requires Protection I)
  • Protection III (20 diamonds, requires Protection II)

Tool Progression

Tools are permanent upgrades within a game:

  • Pickaxe: Wooden → Iron → Diamond
  • Axe: Wooden → Iron → Diamond
  • Shears: Permanent
  • Silk Touch: One-time purchase, applied to current pickaxe

Team Upgrades

Upgrade Table

Upgrade Icon Max Level Cost (Diamonds) Effect Per Level
Sharpness Diamond Sword 3 4 / 8 / 16 +1 damage to all melee weapons
Protection Diamond Chestplate 3 5 / 10 / 20 +1 protection level to all armor
Haste Golden Pickaxe 2 4 / 8 +1 efficiency level to tools
Forge Furnace 4 2 / 4 / 6 / 8 Multiplies generator output
Heal Pool Beacon 1 3 Regeneration II at base
Dragon Buff Dragon Egg 1 5 Increases dragon damage

Forge Upgrade Details

Level Cost Output Multiplier
I 2 diamonds 1.5x
II 4 diamonds 2x
III 6 diamonds 3x
IV 8 diamonds 4x

Traps

Traps are triggered when an enemy enters the team's base area.

Trap Cost Duration Effect
It's a Trap 2 diamonds 30 seconds Blindness II, Slowness I, Glowing
Miner Trap 1 diamond 20 seconds Mining Fatigue III
  • Only one trap can be active per team at a time
  • Purchasing a new trap replaces the previous one
  • Trap is consumed on trigger; a new one must be purchased

Generator System

Generator Types

Type Location Start Tier Max Tier Initial Rate
Iron Each team base I — 1 every 2 seconds
Gold Each team base I — 1 every 8 seconds
Diamond Center/mid map I III 1 every 8 seconds
Emerald Center/mid map I III 1 every 16 seconds

Diamond/Emerald Tier Progression

Diamond and Emerald generators upgrade automatically at configurable game times:

Tier Diamond Rate Emerald Rate Upgrade Time
I 1 per 8s 1 per 16s 0 (start)
II 1 per 6s 1 per 12s Configurable (default: 8min dia, 10min em)
III 1 per 4s 1 per 8s Configurable (default: 20min dia, 24min em)

Generator Holograms

Generators display floating holograms showing:

  • Generator type icon and name
  • Current tier
  • Time until next tier upgrade (for diamond/emerald)

Compass Tracker

Overview

When only min-teams teams remain (default: 2), all alive players receive a Tracking Compass in inventory slot 8. Right-clicking the compass opens a GUI showing all alive enemy players.

How It Works

  1. Automatic — Compass appears in slot 8 when the team count drops to min-teams or below
  2. GUI — Shows each enemy player head with:
    • Player name and team color
    • Distance from your position
    • Status: owned/unowned/currently tracking
  3. Purchase — Click an unowned enemy to buy tracking (costs currency, configurable)
  4. Select — Click an owned (previously purchased) enemy to switch tracking target for free
  5. Deselect — Click the currently tracked enemy to stop tracking
  6. Actionbar — Shows direction arrow (↑ ↗ → ↘ ↓ ↙ ← ↖) + distance to tracked target
  7. Persistence — Tracking survives player death; compass is re-given on respawn
  8. Cleanup — Tracking is removed when the tracked enemy is eliminated (final kill)

Configuration

compass-tracker:
  enabled: true
  cost: 2
  currency: EMERALD
  min-teams: 2
  update-interval: 10
Option Default Description
enabled true Enable or disable the tracker system
cost 2 Number of currency items to pay per tracked enemy
currency EMERALD Material used as payment
min-teams 2 Tracker becomes available when this many or fewer teams remain
update-interval 10 Actionbar update interval in ticks (20 ticks = 1 second)

Direction Arrow

The actionbar displays a Unicode arrow indicating the direction of the tracked enemy relative to the player's view direction:

Angle Range Arrow
0° ± 22.5° (ahead) ↑
45° ± 22.5° ↗
90° ± 22.5° (right) →
135° ± 22.5° ↘
180° ± 22.5° (behind) ↓
225° ± 22.5° ↙
270° ± 22.5° (left) ←
315° ± 22.5° ↖

Known Limitations

  • Compass is locked to slot 8 (cannot be moved or dropped)
  • Only one player can be actively tracked at a time
  • Tracking is per-game; data is cleared when the game ends

TabList System

Features

  • Colored player names based on team color
  • Players sorted by team group
  • Configurable header and footer
  • PlaceholderAPI support in header/footer

Configuration

tablist:
  enabled: true
  sort-by-team: true
  header: "&6&lL-BedWars\n&7play.example.com"
  footer: "&eKills: &f%lbedwars_kills% &8| &eWins: &f%lbedwars_wins%"

Player Name Format

Players are displayed as:

{team-color}{player-name}

Team sorting groups players by their team, making it easy to see who is on which team at a glance. When sort-by-team is disabled, players are listed in default order.

Scoreboard System

Scoreboard Types

Type When Active Content
Lobby In main lobby Player stats, level, K/D, coins (configurable worlds)
Waiting In arena lobby Player count, start timer, arena name, team list
Game During active game Kills, final kills, beds alive, diamond/emerald tiers, game time, date

Game Scoreboard Layout

+---------------------------+
|     &6&lL-BedWars         |
|                           |
|  &fDate: &a01/01/2026    |
|  &fMap: &aMapName        |
|                           |
|  &fKills: &a5            |
|  &fFinal Kills: &a2      |
|  &fBeds: &a✔            |
|                           |
|  &6Diamonds: &eTier II   |
|  &aEmeralds: &aTier I    |
|                           |
|  &fGame Time: &a12:30    |
|                           |
|  &7play.example.com      |
+---------------------------+

Date Configuration

The date on the scoreboard is configurable via language files:

scoreboard:
  date-format: "dd/MM/yyyy"
  date-locale: "en"

The date format uses Java's SimpleDateFormat patterns. The locale affects month/day names. The date line text itself is defined in language files as scoreboard.date: "&7{date}".

Chat System

Behavior

Context Default Behavior
Waiting lobby All messages public with [Lobby] prefix
Active game (team) Messages only visible to team members
Active game (global) Messages starting with ! visible to all players

Configuration

chat:
  enabled: true
  global-prefix: "!"
  team-format: "{player}&f: {message}"
  global-format: "&a[G] {player}&f: {message}"
  waiting-format: "&7[Lobby] {player}&f: {message}"
Option Default Description
enabled true Enable chat formatting
global-prefix ! Prefix for global messages
team-format "{player}&f: {message}" Format for team chat
global-format "&a[G] {player}&f: {message}" Format for global chat
waiting-format "&7[Lobby] {player}&f: {message}" Format for lobby chat

Placeholders:

  • {player} — Player name (colored by team in game)
  • {message} — Message text

Spectator System

Features

  • Automatic spectate mode on final death
  • Compass GUI for teleporting to players
  • Bed item to leave spectate mode
  • Admin spectate via /bwa tp <player>
  • Player visibility management (spectators see all, players see only teammates)

Spectator Items

Item Slot Function
Compass 4 Opens teleport GUI (click player to spectate)
Red Bed 8 Leave spectate mode

Admin Spectate (/bwa tp)

In proxy mode, /bwa tp <player> works across servers:

  1. The proxy sends a BungeeCord Forward message to the target's game server
  2. The game server puts the admin in spectate mode at the target's location
  3. Works with LBedWars.PENDING_SPECTATES for cross-server teleport on join

Party System

Overview

L-BedWars integrates with the Parties API (alessiodp/parties) as a soft dependency. When the Parties plugin is installed, party features are automatically enabled.

How It Works

Game Server Side:

  • PartyIntegration wraps the Parties API with exception-safe calls
  • BedWarsCommand.joinPartyMembers() adds all party members to the same arena when the leader joins
  • Party members are individually added to the same arena, skipping the leader's UUID

Proxy Side:

  • PartyIntegration checks if a player is in a party and if they are the leader
  • On /bw join, if the player is a party leader, all members are sent to the same game server via BungeeCord Connect messages
  • Party system is fully optional — if Parties plugin is missing, all party calls are silently skipped

Party Commands (from Parties plugin)

These commands are provided by the Parties plugin, not L-BedWars:

  • /party invite <player> — Invite to party
  • /party accept <player> — Accept invitation
  • /party leave — Leave party
  • /party kick <player> — Remove from party
  • /party list — List members

Configuration

No additional configuration needed. L-BedWars detects the Parties plugin automatically at startup.

Level & XP System

Overview

100 levels with progressively increasing XP requirements. Players earn XP through gameplay activities.

XP Sources

Activity XP Amount
Kill 10 XP
Final Kill 25 XP
Win 100 XP
Bed Break 50 XP
Daily Reward Configurable

XP Requirements

XP requirements scale exponentially with a multiplier of 1.15x per level:

  • Level 1: 100 XP
  • Level 2: 115 XP
  • Level 3: 132 XP
  • ...
  • Level 100: ~2,670,000 XP

Formula: base_xp * (multiplier ^ (level - 1))

Level-Up Effects

  • Title/subtitle announcement to the player
  • Configurable via language files

Daily Rewards

Features

  • Claimable once per cooldown period (default: 24 hours)
  • Rewards: XP and/or coins (Vault money)
  • Configurable reward amounts
  • Admin command to manage rewards

Configuration (rewards.yml)

daily-reward:
  cooldown-hours: 24
  xp: 500
  coins: 100
  money: 0

Commands

  • /bw dailyreward — Claim daily reward
  • /bwa reward — Admin reward management

Cosmetics

Kill Effects

When you eliminate a player, a visual effect spawns at their death location:

Effect Default Price Description
Explosion 1000 coins Explosion particles
Lightning 2000 coins Lightning strike
Flame 1500 coins Flame particles
Heart 2000 coins Floating hearts
Note 2500 coins Note particles + sound
Slime 3000 coins Slime particles
Snow 3500 coins Snowball particles
Blood 4000 coins Redstone block crack

Victory Dances

When your team wins, a celebration effect plays:

Dance Default Price Description
Fireworks 5000 coins Firework rockets
Lightning 4000 coins Multiple lightning strikes
Explosion 3000 coins Multiple explosions
Rainbow 6000 coins Colored dust particles

Trails

Particles follow behind your player while moving:

Trail Default Price Description
Flame 1500 coins Flame trail
Enchantment 2000 coins Enchantment glyphs
Cloud 1000 coins Cloud particles
Snow 1500 coins Snowball trail
Heart 2500 coins Floating hearts
Lava 2000 coins Drip lava
Critical 1000 coins Critical hit particles
Speed 3000 coins Witch spell particles

Purchasing Cosmetics

  1. Open cosmetics menu: /bw cosmetics
  2. Select category (Kill Effects, Victory Dances, Trails)
  3. Click the cosmetic to purchase
  4. Once purchased, click to activate

All prices are configurable in cosmetics.yml. Economy requires Vault.

Proxy Mode

How It Works

  1. Each game server establishes a TCP connection to the proxy
  2. Game servers authenticate with a shared token (HMAC-SHA256)
  3. Game servers periodically send JSON UPDATE messages with arena status
  4. The proxy maintains a real-time registry of all servers and their states
  5. Players use /bw join <mode> on the proxy, which selects the best available server
  6. The proxy sends players to game servers via BungeeCord plugin channel Connect

Queue System

When no arena is available for a mode, players are placed in a queue:

  • Queue is optional (disabled by default)
  • Priority permissions: players with lbedwarsproxy.queue.priority (configurable) get priority
  • When an arena becomes available, queued players are automatically connected
  • Queue position can be displayed to players

Configuration:

queue:
  enabled: false
  priority-permissions:
    - "lbedwarsproxy.queue.priority"

Health Check

The proxy periodically checks that game servers are still sending updates:

health-check:
  enabled: true
  timeout-seconds: 15

If a server hasn't sent an update within timeout-seconds, it's marked as offline and removed from arena selection.

Cross-Server Spectate

/bwa tp <player> allows admins to spectate any player across servers:

  1. Proxy finds which server the target is on
  2. Proxy sends a BungeeCord Forward message with channel lbedwars:spectate
  3. The target game server puts the admin in spectate mode at the target's location

Database

Storage Types

Type File/Connection Best For
YAML plugins/L-BedWars/stats.yml Single-server, testing
SQLite plugins/L-BedWars/data.db Single-server, production
MySQL Remote database via HikariCP Multi-server, proxy mode

MySQL Configuration

storage:
  type: MySQL
  mysql:
    host: localhost
    port: 3306
    database: lbedwars
    username: root
    password: ""

Table Structure

The player_stats table (used in both standalone MySQL and proxy mode):

CREATE TABLE IF NOT EXISTS player_stats (
  uuid VARCHAR(36) PRIMARY KEY,
  kills INT DEFAULT 0,
  deaths INT DEFAULT 0,
  final_kills INT DEFAULT 0,
  final_deaths INT DEFAULT 0,
  wins INT DEFAULT 0,
  losses INT DEFAULT 0,
  beds_broken INT DEFAULT 0,
  games_played INT DEFAULT 0,
  level INT DEFAULT 1,
  xp INT DEFAULT 0
);

Table prefix is configurable via database.table-prefix in proxy config.

Stats Cache

The game server maintains an in-memory stats cache that batches writes to the database. This reduces database load during active games. Stats are flushed:

  • Periodically on a configurable interval
  • On player quit
  • On game end

PlaceholderAPI

Registration

L-BedWars registers the %lbedwars_*% expansion when PlaceholderAPI is present on the server. The proxy plugin also registers its own expansion.

Player Stats

Placeholder Returns
%lbedwars_kills% Total kills
%lbedwars_deaths% Total deaths
%lbedwars_kdr% Kill/death ratio (2 decimal places)
%lbedwars_finalkills% Final kills
%lbedwars_finaldeaths% Final deaths
%lbedwars_finalkdr% Final kill/death ratio
%lbedwars_wins% Total wins
%lbedwars_losses% Total losses
%lbedwars_wlr% Win/loss ratio
%lbedwars_bedsbroken% Beds broken
%lbedwars_gamesplayed% Games played

Level & XP

Placeholder Returns
%lbedwars_level% Current level (default: 1)
%lbedwars_xp% Current XP
%lbedwars_xp_required% XP needed for next level
%lbedwars_xp_percent% Progress to next level (0-100%)
%lbedwars_xp_progress% Progress bar

Economy

Placeholder Returns
%lbedwars_balance% Vault balance (integer)
%lbedwars_balance_formatted% Formatted balance (e.g. "1,234")

Cosmetics

Placeholder Returns
%lbedwars_active_killeffect% Active kill effect name
%lbedwars_active_victorydance% Active victory dance name
%lbedwars_active_trail% Active trail name

Game / Arena

Placeholder Returns
%lbedwars_arena% Arena name
%lbedwars_gamestate% Arena state (WAITING/STARTING/PLAYING/ENDED)
%lbedwars_gametime% Game time in mm:ss
%lbedwars_isplaying% YES or NO
%lbedwars_isspectating% YES or NO
%lbedwars_players% Current player count
%lbedwars_maxplayers% Max player capacity
%lbedwars_arena_online% Total online players across all arenas (proxy only)

Team

Placeholder Returns
%lbedwars_team% Team name
%lbedwars_teamcolor% Color code (e.g. &c)
%lbedwars_team_colored% Colored team name
%lbedwars_teammates% Total teammates
%lbedwars_teammates_alive% Alive teammates
%lbedwars_hasbed% YES if bed is alive, NO if destroyed

API

Custom Events

L-BedWars fires standard Bukkit events that other plugins can listen to:

ArenaStateChangeEvent

Fired when an arena changes state (WAITING → STARTING → PLAYING → ENDED).

@EventHandler
public void onArenaStateChange(ArenaStateChangeEvent event) {
    Arena arena = event.getArena();
    ArenaState oldState = event.getOldState();
    ArenaState newState = event.getNewState();
}

GameStartEvent

Fired when a game starts (arena enters PLAYING state after countdown).

@EventHandler
public void onGameStart(GameStartEvent event) {
    Arena arena = event.getArena();
}

GameEndEvent

Fired when a game ends (winner determined).

@EventHandler
public void onGameEnd(GameEndEvent event) {
    Arena arena = event.getArena();
    Team winner = event.getWinner();
}

PlayerJoinArenaEvent

Fired when a player joins an arena.

@EventHandler
public void onPlayerJoinArena(PlayerJoinArenaEvent event) {
    Arena arena = event.getArena();
    Player player = event.getPlayer();
}

PlayerLeaveArenaEvent

Fired when a player leaves an arena.

@EventHandler
public void onPlayerLeaveArena(PlayerLeaveArenaEvent event) {
    Arena arena = event.getArena();
    Player player = event.getPlayer();
}

PlayerKillEvent

Fired when a player is killed in-game.

@EventHandler
public void onPlayerKill(PlayerKillEvent event) {
    Arena arena = event.getArena();
    Player killer = event.getKiller();
    Player victim = event.getVictim();
    boolean isFinal = event.isFinal();
}

BedBreakEvent

Fired when a team's bed is destroyed.

@EventHandler
public void onBedBreak(BedBreakEvent event) {
    Arena arena = event.getArena();
    Team team = event.getTeam();
    Player breaker = event.getBreaker();
}

LBedWarsAPI

The public API class provides access to L-BedWars internals:

LBedWarsAPI api = LBedWarsAPI.getInstance();

// Arena access
Arena arena = api.getArenaByName("myarena");
Collection<Arena> allArenas = api.getAllArenas();

// Player lookup
Arena playerArena = api.getArenaByPlayer(playerUUID);
boolean isPlaying = api.isPlaying(playerUUID);

// Stats
int kills = api.getStats(playerUUID, "kills");
api.addStats(playerUUID, "kills", 1);

// Economy (Vault)
double balance = api.getBalance(playerUUID);

// Party
List<UUID> partyMembers = api.getPartyMembers(playerUUID);

// Leaderboard
List<LeaderboardEntry> topKills = api.getLeaderboard("kills", 10);

Language System

Overview

L-BedWars uses YAML-based language files for all user-facing messages. Two languages are bundled:

  • messages_en.yml — English
  • messages_tr.yml — Turkish

Configuration

Set the language in config.yml:

language: en

Message Format

Messages support:

  • & color codes (e.g., &a = green, &c = red, &l = bold)
  • {placeholder} substitution (e.g., {player}, {cost})
  • Newlines for multi-line messages

Adding Custom Messages

Language files use dot-notation keys:

game:
  died: "&cYou died! &7You were killed by {player}"
  respawn-in: "&aRespawning in {seconds}s"
compass-tracker:
  tracking-started: "&aNow tracking &e{player}&a!"

Fallback

If a message key is missing in the selected language file, an empty string is returned. The plugin never crashes due to missing messages.

Performance

Optimizations

Technique Impact
Map<UUID, Arena> player lookup O(1) arena resolution, no iteration
Stats cache with batched flush Reduces database writes by 90%+
Throttled trap checks (500ms) Limits move-event processing
Generator entity scan getNearbyEntities(2,2,2) instead of full chunk scan
Folia region scheduling Proper task scoping for regionized servers
Dragon target updates Every 20 ticks instead of every tick
Lobby scoreboard World-list check instead of player tracking set

Minimal Tick Impact

  • PlayerMoveEvent: trap check throttle, border warning throttle
  • EntityDamageByEntityEvent: direct O(1) lookups
  • Generator spawning: scheduled tasks per generator, not per tick
  • Scoreboard updates: 20-tick refresh interval

Troubleshooting

Common Issues

Arena not appearing in list

  • Ensure arena is enabled: /bwa enable <arena>
  • Check arena setup is complete: all teams have spawns, beds, region
  • Check console for setup errors

Players can't join

  • Arena may be full (check max-players config)
  • Arena may be in PLAYING state
  • Permission issue: player needs bedwars.play

Socket connection failed (proxy mode)

  • Verify socket-token matches between proxy and game server
  • Check bind-address and socket-port are accessible
  • Verify allowed-ips includes the game server IP
  • Check firewall settings

Database connection failed

  • Verify MySQL host/port/credentials
  • Ensure MySQL is running and accessible
  • Check table-prefix matches between proxy and game server configs

Placeholders not working

  • Verify PlaceholderAPI is installed
  • Use /papi parse me %lbedwars_kills% to test
  • Check console for expansion registration errors

Party not working

  • Verify Parties plugin is installed (3.2.16+)
  • Check that softdepend: [Parties] is in plugin.yml
  • Restart server after installing Parties

Debug Commands

  • /bwa reload — Reload configuration without server restart
  • /bwa list — List all configured arenas
  • Check server console for [L-BedWars] prefixed messages
  • Enable debug mode in config if available

Getting Help

  • Discord: squezsaz
  • GitHub Issues: Report bugs with server version, plugin version, and console logs

Clone this wiki locally