> For the complete documentation index, see [llms.txt](https://docs.ohalee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ohalee.com/products/modern-bedwars/features.md).

# Features

Modern BedWars is a horizontally scalable BedWars core. Everything player-facing — GUIs, prices, timings, physics constants, cosmetics and every string — is YAML/properties, not compiled into the jar.

## Why it's different

* **Horizontally scalable** — add lobby or game servers without touching the rest of the network's config.
* **Fully config-driven** — reskin GUIs and retune the whole game without a rebuild.
* **Multi-language out of the box** — per-player locale detection with automatic English fallback; add a language by dropping in a file.
* **Multi-version** — the game plugin runs on **both Minecraft 1.8 and 26.1+**.
* **Admin console included** — a live shell on the matchmaking service for queue / server / match inspection and map reloads.

## Gameplay systems (game server)

### Match lifecycle

Each game runs through `WAITING → STARTING → PLAYING → RESTARTING` phases. Game modes are **Solo, Duo, Trio and Squad**, each with independently tunable shop prices, upgrade prices and generator schedules.

### Teams & beds

* Each team has a colour, a shared shop inventory, a base region and its own bed.
* Breaking a team's bed eliminates it — remaining members become spectators, and a configurable bed-break cosmetic and message fire. The breaker is credited with a **final kill** on the last elimination.
* The post-respawn invulnerability window is configurable (default \~3s).

### Shop

* Categorised GUI (blocks, swords, armor, tools, bows, potions, special) driven by `shop.yml`, with per-game-mode pricing (solo/duo vs trio/squad tiers).
* Team-shared resource counters (iron, gold, diamond, emerald).
* An armor-hierarchy guard prevents accidentally buying a downgrade.
* Hotbar quick-buy for instant re-purchase without opening the GUI, plus a shop reset confirmation dialog.

### Generators

* Resource types: Iron, Gold, Diamond, Emerald, plus the team-upgraded **Emerald Forge**.
* Spawn delay, cap and batch size are configured per game mode **and** per upgrade level in `generators.yml`.

### Team upgrades

* Single-purchase upgrades (Sharpened Swords, Reinforced Armor, Heal Pool / Beacon) and multi-level ones (armor I–IV, haste pickaxe I–II, forge), priced per game mode.
* Grants persistent team-wide enchantments and effects for the rest of the match.

### Traps

* Configurable trap catalogue — shipped defaults include Tripwire (blind + slow attackers), Feather (speed + jump for defenders), Alarm / Redstone Torch (reveals invisible intruders) and Mining Fatigue.
* Each trap has a configurable potion effect, duration and target (attacking team vs defending base).
* A **magic-milk** cooldown (default \~30s) grants temporary trap immunity after triggering one.

### Cosmetics

* Categories: arrow trail, fireball trail, victory dance, final-kill effect, kill message, bed-break effect, bed-break message, wood skin.
* Players unlock/purchase cosmetics with in-game currency; unlocks and active selections persist in MariaDB.
* A master on/off toggle plus global particle-count and effect-duration multipliers let admins tune visual load without touching individual cosmetics.
* Paginated selector GUI.

### Disguise

* `/disguise` (game + lobby) backed by a disguise service, tracked in Redis so state follows the player across servers.

### Scoreboard

* Configurable per-phase sidebar; refresh rate is tunable to trade live-ness for tick performance on loaded game servers.

## Lobby systems

* **Queueing** — players join a mode queue; the matchmaking service does the actual matchmaking and tells the lobby to connect them.
* **Private games** — `/private` to host a custom match, `/join` to enter one by code.
* **Rejoin** — `/rejoin` returns a disconnected player to their in-progress match, tracked via Redis rejoin keys with a TTL.
* **Spectate** — `/spectate` to watch a running match.
* **Profile & stats** — `/profile` and `/stats` show win/loss/kill/final-kill records from MariaDB.
* **Leaderboards** — cached and periodically refreshed, with a reset job for seasonal resets.
* **Configurable GUI layout** — slot positions, page size and strings for the lobby GUIs are de-hardcoded; reskinning doesn't require a rebuild.
* **PlaceholderAPI** — optional soft dependency exposes `bedwars_*` placeholders (rank, coins, level, stats).

## Proxy systems

* **Routing** — recognises lobby vs game servers by configurable name prefixes and returns players to the lobby (or their match, via rejoin) on disconnect.
* **Party system** — `/party` with `chat`, `invite`, `join`, `kick`, `leader`, `leave`, `list`, built on a Redis-backed party model shared across the network.
* **Multiplier admin** — an XP/coin multiplier command for events and promotions.
* **Spectate** — cross-server `/spectate` entry point.

## Matchmaking brain (service)

A standalone Spring Boot process — no Minecraft server required, just a JVM with network access to Redis and MariaDB.

* **Queue processing** — one queue per game mode; runs a matchmaking pass on a tunable interval, steals players from under-filled queues, and times out players who wait too long.
* **Server rancher** — tracks live game servers, recomputes player load on an interval, and enforces a max-matches-per-server cap so no single instance gets overloaded.
* **Play-again cooldown** — a short cooldown + cache to stop `/playagain` abuse from hammering the queue.
* **Map distribution** — loads and broadcasts the map list to all game servers over Redis.
* **Admin console** — a Spring Shell prompt (`status queues`, `list matches`, `list servers`, `maps reload`, `log`, `stop`) plus an Actuator health endpoint.

## Party system

Two layers, selected automatically:

1. **Built-in** — Redis-backed, managed on the proxy via `/party`, with GUI support on the lobby.
2. **External plugin adapters** — if **Party and Friends** or **Parties** (AlessioDP) is installed, it's detected at startup and takes over as the read-only source of truth for party membership; the built-in `/party` command is automatically suppressed so there's no conflict. Queueing and party-follow-on-server-switch keep working either way.