🎤 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.