🎤 KaraokePlugin

A full-featured karaoke event management plugin for PaperMC servers.

KaraokePlugin lets you run live karaoke nights directly on your Minecraft server. Assign singers, manage a judge panel with live scoring displays, drop the stage floor for dramatic effect, teleport the crowd, handle a singer queue — all from a clean in-game GUI without touching a single command by hand.

---

✨ Features

• GUI Control Panel — open with /karaoke or /k; every action has a dedicated button
• LuckPerms Integration — singer, judge, and listener roles are applied and removed automatically via fully configurable console commands
• Live Scoring — judges and audience vote yes/no; scores are tracked separately and displayed on the leaderboard
• Judge Display Blocks — concrete blocks in the world flip from yellow → green or red as judges vote
• Judge Suffixes — judges automatically receive a coloured [J1] [J2] etc. suffix via LP meta
• Singer Queue — add multiple players to a waiting list; advance through them one-by-one
• Round Timer — optional per-singer time limit with title countdowns; auto-advance queue when it expires
• Stage Drop — removes the floor under the singer's feet; restores it automatically after a configurable delay; teleports the singer back to stage on respawn if they die
• Execution Chamber — teleport the singer to a separate chamber via a redstone trigger
• Top-3 Winner Announcement — broadcasts a formatted results banner with judge and audience score breakdown
• Spawn Return — sends every player to a configured spawn point when the event ends
• Event Commands — run any commands on behalf of every player (with * permissions) when the event starts or ends
• PlaceholderAPI Support — 9 placeholders for scoreboards and displays
• Fully Configurable — all LuckPerms commands, messages, scoring weights, timers, and locations are set in config.yml
• Persistent Setup — captured locations and scores are saved to data.yml and survive restarts

---

📦 Installation

1. Drop KaraokePlugin.jar into your server's plugins/ folder.
2. Start the server once to generate plugins/KaraokePlugin/config.yml.
3. Set your LuckPerms group names under roles: if they differ from the defaults (singer, judge, listener).
4. Optionally edit luckperms-commands: to customise exactly what LP commands are run.
5. In-game, run /karaoke setup to capture all required locations (stage, judge bench, listener deck, spawn, trapdoor region, execution chamber).
6. Done — run /karaoke start to begin your first event.

Requirements

Dependency	Version	Required
Paper	1.21.1	✅ Yes
LuckPerms	Any	⚠️ Soft (roles won't apply without it)
PlaceholderAPI	Any	⚠️ Soft (placeholders won't work without it)

---

🎛️ Commands

All management commands require karaoke.host. Aliases: /k

Command	Description
/karaoke	Open the admin control panel GUI
/karaoke start	Start the event immediately
/karaoke stop	Stop the event and return all players to spawn
/karaoke time <duration>	Set and start a countdown (e.g. 5m, 2m 30s, 90s)
/karaoke setup	Open the location setup GUI
/karaoke add singer <player>	Assign a player as the active singer
/karaoke add judge <player>	Add a player to the judge panel
/karaoke remove singer <player>	Remove the active singer and return them to audience
/karaoke remove judge <player>	Remove a player from the judge panel
/karaoke singer clear	Clear the stage (no singer)
/karaoke queue add <player>	Add a player to the singer queue
/karaoke queue remove <player>	Remove a player from the queue
/karaoke queue next	Advance the queue — assign the next waiting singer
/karaoke queue clear	Empty the queue
/karaoke queue list	List all players in the queue
/karaoke drop	Drop the stage floor under the current singer
/karaoke execute	Teleport the singer to the execution chamber
/karaoke winner	Announce the top-3 winner results
/karaoke status	Show a summary of the current event state
/karaoke leaderboard	Open the leaderboard GUI
/karaoke reload	Reload config.yml without restarting
/vote	Open the voting GUI (available to all players)

---

🔑 Permissions

Permission	Default	Description
karaoke.host	op	Full event management
karaoke.judge	op	Judge-level interactions (status, leaderboard)
karaoke.execute	op	Access to /karaoke drop and /karaoke execute
karaoke.vote	true	Open the /vote GUI

---

📊 PlaceholderAPI Placeholders

Requires PlaceholderAPI to be installed.

Placeholder	Returns
%karaoke_event_active%	true / false
%karaoke_singer%	Name of the current singer, or None
%karaoke_judge_count%	Number of active judges
%karaoke_queue_size%	Number of players waiting in queue
%karaoke_countdown%	Formatted countdown remaining (e.g. 4m 30s)
%karaoke_my_score%	Viewing player's total score (judge + audience)
%karaoke_my_judge_score%	Viewing player's judge-sourced score
%karaoke_my_audience_score%	Viewing player's audience-sourced score
%karaoke_is_judge%	true / false — whether the viewer is a judge

---

⚙️ Configuration Overview

config.yml is read-only at runtime. data.yml is written by the plugin and holds all captured locations and runtime state.

luckperms-commands:

The exact console commands dispatched for every role action. Supports {player}, {group}, and {ordinal} placeholders. Set any entry to "" to skip it entirely.

luckperms-commands:
  singer-add:       "lp user {player} parent add {group}"
  singer-remove:    "lp user {player} parent remove {group}"
  listener-add:     "lp group default parent add {group}"
  listener-remove:  "lp group default parent remove {group}"
  judge-add:        "lp user {player} parent add {group}"
  judge-remove:     "lp user {player} parent remove {group}"
  judge-suffix-set:   'lp user {player} meta addsuffix 1000 " &6[&eJ{ordinal}&6]&r"'
  judge-suffix-clear: "lp user {player} meta removesuffix 1000"

event-commands:

Commands run for every online player on event start/stop. Each player executes them with temporary * permissions, so warps and other permission-gated commands work for everyone.

event-commands:
  on-start:
    - "warp karaoke"
  on-stop:
    - "warp spawn"

Other notable settings

Key	Default	Description
countdown-auto-start	true	Auto-start event when countdown hits zero
round-duration-seconds	0	Per-singer time limit (0 = disabled)
round-auto-advance-queue	false	Auto-assign next singer when round timer expires
stage-drop-restore-delay-seconds	10	Seconds before dropped floor restores

---

🗺️ Setup Guide

Open /karaoke setup and click each button while standing at (or looking at) the relevant position:

Button	What to capture
Stage Teleport	Where the singer spawns when assigned
Judge Bench	Where judges teleport on event start
Listener Deck	Where the audience teleports on event start
Spawn Point	Where everyone returns when the event ends
Trap Region Pos 1 & 2	Two corners of the stage floor (for /karaoke drop)
Execution Chamber	The room the singer is sent to on execution
Execution Trigger	Block that becomes a redstone block during execution
Judge Display Blocks 1–4	Blocks that show each judge's vote (yellow → green/red)

All captures are saved to data.yml and persist through restarts.