Enhanced UHC

-# This text is from my github repositorie, avoid all the maven building help.

UHC plugin for Minecraft Paper servers. It covers the full match lifecycle:
configuration, scenarios, teams, scatter, timers, borders, statistics, scoreboard,
Discord announcements, and match ending.

Features

• UHC match management: player scatter, countdown, final heal, PvP activation,
  timed Nether access, progressive borders, late scatter, 2-minute reconnect
  grace, and winner announcement.
• FFA and team modes with invitations, team chat, cross-team merging for
  incomplete teams, kick, leave, and disband.
• Admin GUIs for configuration and scenarios.
• Dedicated uhc and uhc_nether worlds with automatic creation, configured borders,
  center PvP cleanup, and internal pre-generation or Chunky integration.
• Dynamically toggleable scenarios: CutClean, Timber, FlowerPower, Randomizer,
  NoFall, SafeMining, Bowless, TimeBomb, Golden Head, SafeLoot, and more.
• Configurable scoreboard with match, team, border, and Do Not Disturb placeholders,
  plus a below-name health and absorption indicator.
• Gameplay controls for apple/flint rates, cobweb limits, potions, explosives,
  anti-burn drops, achievements, hidden commands, and whitelist state.
• Optional TAB tablist formatting and Lunar Client Apollo TeamView integration.
• Persistent MySQL statistics: kills, deaths, assists, wins, games played,
  points, Elo, and leaderboards.
• Discord announcements for openings and results through a webhook or bot + target channel.
• Optional MiniPlaceholders support for exposing statistics and match information.

Requirements

Component	Version / note
Java	21
Maven	3.9+ recommended
Server	Paper 1.21.x (api-version: 1.21)
Database	Optional MySQL, enabled by default in database.yml
Optional plugins	MiniPlaceholders, TAB, Apollo, Chunky, WorldEdit / FastAsyncWorldEdit

The plugin is compiled against paper-api:1.21.11-R0.1-SNAPSHOT.

Build

mvn clean package

The production jar is generated in target/, for example:

target/uhc-1.0.4-SNAPSHOT.jar

Installation

1. Build the project with Maven.
2. Place the jar in the Paper server's plugins/ directory.
3. Start the server once to generate the files in plugins/UHC/.
4. Configure the generated YAML files, then restart the server.
5. If needed, pre-generate the worlds with /pregen.

The plugin automatically creates and configures the uhc and uhc_nether worlds.

Configuration

File	Purpose
uhc.yml	Timers, teams, borders, Nether, drops, potions, scatter, late scatter, spectator spawn, gameplay flags, tablist, border wall, and Elo.
database.yml	MySQL connection, assist window, leaderboard size, and refresh interval.
discordwebhook.yml	Discord webhook, bot/channel target, role mention, opening and victory embeds.
scoreboard.yml	Scoreboard title, objectives, and solo/team lines.
joinitems.yml	Items given in the lobby.
guis.yml	Interface labels and slots.
items.yml	Custom item names and lore.
messages.yml	Prefixes and shared messages.
language.yml	Localizable text used by commands and listeners.
plugin.yml	Commands, main permission, and Bukkit/Paper metadata.

By default, database.yml contains mysql.enabled: true. If no MySQL server is
available, either provide valid credentials or set this value to false. In memory mode,
stats work for the current session but are not persisted.

Commands

The administration permission is uhc.host and defaults to op.

Administration

Command	Description
/start	Starts the match, scatters players, and starts timers.
/finish <player>	Ends the match with a player winner.
/finish team <id>	Ends the match with a team winner. Also accepts /finish team:<id>.
/configurationAdmin	Opens the admin configuration GUI.
/scenariosadmin	Opens the scenario administration GUI.
/pregen [radiusBlocks] [chunksPerTick]	Pre-generates the UHC Overworld and Nether.
/pregen stop	Stops the current pre-generation task.
/announce <opening>	Sends the Discord announcement. Accepted formats: 16h01m, 16h01min, 16:01.
/hidden [player]	Applies an anonymous identity to a player.
/hidden reset [player]	Restores the original identity.
/statsadmin clear	Deletes all statistics.
/statsadmin undo	Reverts statistics from the last match. Alias: /statsadmin undolastgame.
/statsadmin get <player>	Shows a player's statistics.
/statsadmin add <player> <stat> <amount>	Adds a value to a statistic.
/statsadmin remove <player> <stat> <amount>	Removes a value from a statistic.
/statsadmin set <player> <stat> <value>	Sets a statistic value.
/revive <player>	Revives a player and restores them to the alive counter when possible.
/heal [player|all]	Heals one player, yourself, or everyone.
/feed [player|all]	Restores food for one player, yourself, or everyone.
/head <skin> [target] [amount]	Gives a player head.

Players

Command	Description
/team create	Creates a team if team mode is enabled.
/team inv <player>	Invites a player.
/team invite <player>	Alias for /team inv <player>.
/team accept	Accepts an invitation.
/team chat	Toggles team chat.
/team info	Shows team members.
/team leave	Leaves the current team.
/team kick <player>	Kicks a member, leader only.
/team disband	Disbands the team, leader only.
/crossteam <player>	Merges two alive incomplete teams during a running game.
/configuration	Opens the public configuration GUI.
/scenarios	Shows active scenarios. Aliases: /scen, /scenario.
/kills [player]	Shows match kills.
/assists [player]	Shows match assists.
/fight	Broadcasts your position when looking for a fight.

Useful aliases: /party for /team, /config and /cfg for /configuration,
/anonymous and /nick for /hidden, /endgame and /forcewin for /finish,
/uhcstats, /statadmin, /statsmanage for /statsadmin.

Available Scenarios

Scenario	Effect
Bowless	Bows and crossbows cannot be used.
Chest	A dead player's inventory is stored in a chest.
Cobble Only	Non-ore cave blocks drop cobblestone.
Cold Weapons	Flame and Fire Aspect are disabled.
CutClean	Ores and food directly drop smelted.
DoubleHealth	Players have 20 hearts.
FlowerPower	Breaking flowers drops a random legal item or loot-table reward.
Golden Head	Players drop their head, craftable into a golden apple-looking Golden Head. It consumes like a vanilla golden apple and keeps the custom Regeneration III + Absorption effects.
Hastey Boys	Pickaxes are unbreakable and have Efficiency III.
Horseless	Players cannot mount horses.
Maceless	Maces cannot be crafted or used.
NoClean	Grants 30 seconds of invincibility after a kill.
NoFall	Fall damage is disabled.
NoPoison	Poison effect is blocked.
Randomizer	Block and mob drops are randomized into legal survival items.
SafeLoot	Only the killer can open a death chest for the first 20 seconds.
SafeMining	Damage is blocked during the mining phase.
Shieldless	Shields cannot be crafted or used.
Spearless	Spears cannot be crafted or used.
Timber	Breaks a whole tree at once.
TimeBomb	Death chests explode after 60 seconds.

MiniPlaceholders

If MiniPlaceholders is installed, the uhc expansion is registered automatically.

Player placeholders:

• kills, deaths, assists, wins, games_played, elo, elo_rank
• match_kills, match_assists, team_kills
• alive, elapsed_time, time_status, next_event, winner, mode
• team, team_id, team_display, team_color
• do_not_disturb_link, do_not_disturb_players, do_not_disturb_time

Global leaderboard placeholders:

• top_kills_name, top_kills_value
• top_deaths_name, top_deaths_value
• top_assists_name, top_assists_value
• top_wins_name, top_wins_value
• top_games_played_name, top_games_played_value
• top_elo_name, top_elo_value

Leaderboard placeholders accept a rank argument according to MiniPlaceholders syntax.

Match Flow

1. Adjust the configuration with /configurationAdmin and /scenariosadmin.
2. Check uhc.yml, especially teams.size, timers, borders, and Nether settings.
3. Pre-generate with /pregen, or let Chunky handle it if the plugin is installed.
4. Let players create teams with /team.
5. Send the Discord announcement with /announce <opening>.
6. Start the match with /start.
7. During the game, use /crossteam <player> to merge incomplete teams if needed.
8. Let victory conditions end the match automatically or end it manually with /finish.
9. Manage statistics with /statsadmin if a correction is needed.

Project Structure

src/main/java/xyz/pyxismc/uhc/
  commands/      Bukkit/Paper commands
  config/        UHC configuration loading
  discord/       Discord embed sending
  game/          Match state, worlds, borders, teams, match ending
  gui/           Configuration and scenario interfaces
  listeners/     Gameplay and configuration listeners
  scenarios/     Scenario registry and activation
  scoreboard/    Scoreboard and internal placeholders
  stats/         MySQL, cache, leaderboards, Elo
  utils/         Message and language helpers

Release Verification

mvn clean package

Then test the jar on a local Paper server with at least:

• plugin startup without console errors;
• YAML file generation;
• /configurationAdmin, /scenariosadmin, /pregen, /start;
• /crossteam, late scatter, reconnect grace, and spectator hiding;
• match ending with /finish;
• stats read/write if MySQL is enabled.