EggHolder is a Paper plugin for running a high-pressure End PvP event where one player carries the Dragon Egg and becomes the main target for the entire server.
This README is written for people who:
- have never used this plugin before
- may not know the End War event format
- need to understand what the plugin does without someone explaining it live
This plugin turns a normal Minecraft End fight into a structured event.
The core idea is simple:
- A Dragon Egg becomes the most important objective in the match.
- Whoever gets the egg becomes the
EggHolder. - The EggHolder becomes globally visible, tracked, and mu 8000 ch more dangerous.
- Everybody else hunts them, steals the egg, or survives the event.
The plugin adds:
- automatic EggHolder detection
- live coordinate tracking with a bossbar
- custom EggHolder gear and effects
- death spectator/ghost mode
- team system
- hunter kits
- match start flow
- side objectives and event modifiers
- admin live controls
It is built for competitive, event-style gameplay on a Paper server.
End War is an event style where players or teams enter the End and fight over the Dragon Egg after the Ender Dragon dies.
In this plugin:
- the Dragon Egg is the central objective
- the player holding it is heavily announced to everyone
- the event keeps pressure high with systems like End Storm, anti-camp punishments, supply drops, hotspots, overtime, revenge mark, no-build zones, and spectator audience voting
So even if someone does not know the event beforehand, they can think of it like this:
One player has the objective. Everyone knows it. That player is powerful, but also hunted. The match gets more dangerous over time until someone wins.
Paper 1.20.6through1.21.11(API compatibility checks run against both endpoints)Java 21- Maven only if you want to build from source
- GitHub release 2.2.3 — includes
EggHolder.jar. - Modrinth 2.2.3 jar. The existing Modrinth project is still being reviewed, so its public listing may not appear in search yet.
EggHolder is a Paper API plugin, not a mod-loader mod. Compatibility depends on the server providing the Paper APIs used by the plugin and behaving like a normal single-threaded Bukkit/Paper server.
| Server software | Support status | Notes |
|---|---|---|
| Paper | Supported | API compatibility is compiled in CI against 1.20.6 and 1.21.11. |
| Purpur | Supported as a Paper-compatible fork | Use a Minecraft version in the supported range. |
| Pufferfish, Leaf, Gale | Paper-fork compatible; not separately runtime-tested | These are included as best-effort compatible software. Report issues with the exact server build and version. |
| Spigot | Not supported yet | This build directly uses Paper-only API classes and methods (including registry and Adventure integrations). Listing Spigot as supported would be misleading; it needs a compatibility port and Spigot runtime tests first. |
| Folia | Not supported | The plugin uses Bukkit's standard scheduler and has not been adapted to Folia's region and entity schedulers. Setting a Folia support flag alone would not make it safe. |
| Forge / NeoForge / Fabric / Quilt | Not directly supported | These are mod loaders, not Bukkit/Paper plugin runtimes. A hybrid server that embeds Bukkit may load some plugins, but EggHolder is not tested or supported on those hybrids. |
Paper and Purpur are the recommended supported choices. Leaf, Gale, and Pufferfish are now explicitly included as best-effort Paper-fork compatible software, but EggHolder has not been run on them. Plain Spigot is not yet supported because this build uses Paper-only APIs; the required compatibility port and live tests have not been done. CI compiles against Paper API 1.20.6 and 1.21.11; this is API compilation coverage, not live-server runtime testing. Optional newer gear adapts on older supported versions: Netherite Spears fall back to tridents, Maces fall back to Netherite axes if unavailable, and unknown enchantments are skipped.
This plugin can now manage its own custom world_the_end from a bundled schematic.
That means the jar can:
- ship with the End island map inside the plugin itself
- create or load the configured End world automatically
- paste the bundled map into that world on startup
- use the map center as the event center
- detect crystal tower pedestals from the schematic layout
- reuse those tower anchors for dragon crystals and optional event objectives
The bundled schematic is:
maps/ScarworldEndIsland.schem
Important operator note:
- the managed End system is controlled in
config.ymlundermanaged-end-world - if enabled, the plugin treats the configured End as an event map world rather than a normal vanilla End
- startup preparation edits the configured world; with
clear-region-first: true, blocks inside the schematic bounds are cleared before the map is pasted - set
prepare-on-startup: falseto defer preparation until the match starts, and setclear-region-first: falseto overlay the schematic without clearing its bounds - admins can rebuild or inspect the managed map in-game with
/endwar world ...
- Replaced the generic falling supply-drop display with the nine-part BDEngine Airdrop model by Yirf; the visual remains after landing and is removed with the cache.
- Bundled the display model locally, with per-drop entity tracking so movement and cleanup are limited to that drop.
- Documented the model attribution and BDL BY-NC terms.
- Fixed Paper 1.21.11 scoreboard exceptions caused by copying named team colors into player-specific sidebars; colored team prefixes remain visible.
- Fixed legacy
minecraft:chainblock states in the bundled End schematic by mapping them tominecraft:iron_chainon modern servers. - Consolidated push CI and GitHub Packages publishing into one workflow. The package publishes only after both Paper API compatibility builds pass, and its CI version follows the release version in
pom.xml.
- Fixed routine managed-map preparation so
clear-region-firstis respected;/endwar world prepareremains an explicit clean rebuild. - Audience vote close/resolve commands now report when no vote is open.
- EggHolder assignment uses exact online player names to avoid selecting the wrong target from an ambiguous partial name.
- Command usage messages now show the required player and team arguments more clearly.
- Eliminated players can no longer damage living players with melee or player-fired projectiles, or trigger actions through stale kit/team/audience menus.
- Cancelled block events no longer enter or corrupt the bridge-collapse tracker, and extracted schematic paths are constrained to the plugin data folder.
Players join the server and receive:
- a
Team Menuitem - a
Hunter Kitsitem
Before the match starts, players can:
- create teams
- invite players
- join teams
- select a kit
If a player never joins a team, the plugin can still place them into a solo team when the event starts.
When an admin runs:
/start
the plugin:
- spawns a large End portal structure at the configured overworld center
- prepares End spawn platforms for teams
- scatters teams around the configured End center
- locks building and combat briefly after entry
- starts the event phase systems
Once somebody gets the Dragon Egg:
- they automatically become the
EggHolder - everyone gets chat and title announcements
- a global bossbar tracks their live coordinates
- their name/tag/tab styling changes
- they receive event gear and effects
- an item display appears above their head
If the EggHolder dies, logs out too long, or loses the egg, the plugin reacts automatically based on config.
When a normal player dies:
- they enter a dead/spectator-style event state
- they are hidden from living players
- they can fly
- they remain in the tab list with italic styling
- they receive a
Recovery Compassteleporter - they can teleport to alive players using a GUI
Dead players can also participate through Audience Tools when enabled.
As the match continues, the plugin can intensify the event with:
OvertimeMercyless EndgameNo Escape TimerPanic PhaseBridge CollapseEnd StormHotspot RotationEgg Burn Timer
This is designed to stop slow, boring endings and force action.
The EggHolder is the current player carrying the Dragon Egg.
By default, the plugin can auto-detect the holder by inventory scanning. Manual assignment also exists for admin control.
When a player becomes EggHolder, the plugin can:
- announce them globally in chat
- announce them with titles
- show a live bossbar
- give them special weapons
- apply potion effects
- glow them with a colored team
- change tab and nametag prefix
- show a Dragon Egg or other configured item above their head
The bossbar is shown globally and updates in real time.
Default format:
EGGHOLDER <Player> X: <x> Y: <y> Z: <z>
Configurable:
- enabled/disabled
- color
- style
- update speed
- text format
- hidden coordinate text
By default, the holder receives:
Netherite SpearMace
Everything about these items is editable:
- enable/disable
- item material
- amount
- slot
- name
- lore
- enchantments
- enchant levels
- unbreakable state
Dead players are not fully removed from the match experience.
Instead, they become a ghost/audience role with:
- flight
- vanish from alive players
- no interaction with normal gameplay
- italic list name
- teleporter compass GUI
- optional admin revival
If a dead player is revived:
- they are restored to normal player state
- their spectator protections are cleared
- they can take damage again
- void deaths in the End can revive at a safe platform instead of instantly dying again
The plugin includes a full team system.
Players can:
- create teams
- invite players
- accept invites
- rename teams
- leave teams
- kick members
- disband teams
- use the GUI menu instead of commands
Team features:
- configurable max team size
- automatic unique team names
- leader rename support with
/team rename <name> - unique hex color per team tag
- unique personal color per player name inside the team display
- team prefix formatting
- team kill tracking
- scoreboard integration
By default, friendly fire is disabled between teammates.
Important gameplay note:
- teams lock once the active match is running
This prevents last-second abuse during live combat.
Players can choose a hunter kit before fighting.
Default included kits:
DuelistTitanScoutSaboteur
Every kit is defined in kits.yml, including:
- icon
- description
- potion effects
- items
- enchantments
- hotbar slot placement
Players can open the kit GUI using the provided menu item.
Important gameplay note:
- kits are meant to be chosen before real fighting starts
- kit switching is blocked once a living player is actively inside the End during a running match
The plugin supports a configurable sidebar scoreboard in scoreboard.yml.
Default sidebar information includes:
- match phase
- current EggHolder
- player kills
- kill streak
- team name
- team kills
- online teammate list
- teammate health
This is fully editable through scoreboard lines.
Dead players can still influence the match through timed audience voting.
Admins can also control this live.
Default audience effects include:
- instant storm burst
- forced supply drop
- forced hotspot rotation
- holder reveal
- holder heal burst
The plugin includes many optional pressure systems.
Creates periodic End chaos with lightning and harmful pressure on players in the End.
Punishes an EggHolder who stays in the same area too long.
When the egg drops, pickup can be delayed briefly so the drop becomes a contested moment.
The player who grabs the dropped egg can receive a short buff burst.
After enough time passes, the EggHolder starts taking ongoing pressure damage so the round cannot stall forever.
If someone kills the EggHolder, they can be publicly marked as the next visible target.
Prevents building near the configured center objective area.
If a dropped egg sits untouched too long, it can burn out and respawn at center.
Killing the EggHolder can grant effects and optional commands/rewards.
Damaging the holder can give hunters short pressure buffs.
Picking up the egg can trigger a knockback shockwave around the new holder.
A temporary buff zone appears and rotates around the End to force movement and map control.
Teams can capture End crystal points for reward effects.
Triggers when the EggHolder drops below a configured health threshold.
Player-built End bridges outside the core zone can start collapsing in waves.
The killer of the EggHolder can receive brief protection against instant cleanup.
A late phase where revives are disabled and the event becomes final.
If the holder keeps the egg long enough, escape tools like pearls and wind charges can be blocked.
The plugin can call in public loot drops from the sky.
Default implementation:
- a falling, multi-part Block Display airdrop model
- publicly announced coordinates
- protected until landing
- configurable loot table
The bundled airdrop appearance is Airdrop by Yirf, model 8073 on Block Display Models. It is adapted from the model's published display transforms and distributed under BDL BY-NC (attribution required, non-commercial use, derivatives allowed). The model license applies to this asset; it does not change the license of EggHolder itself.
Manually assigns a player as the EggHolder.
Removes EggHolder status and cleans up effects, bossbar, display, and role items.
Reloads:
config.ymlmessages.ymlkits.ymlscoreboard.yml
without restarting the server.
Revives a dead player.
If Mercyless Endgame is active, revives are blocked.
Starts the event flow and opens the overworld portal.
Alternate admin start command.
Stops the match and cleans up runtime systems.
Shows the current match phase, EggHolder, elapsed match time, enabled event features, and scheduled or active event timers.
Live real-time control for event features.
Examples:
/endwar feature end-storm on
/endwar feature supply-drops trigger
/endwar feature anti-camp-detector off
Opens, closes, or resolves audience voting in real time.
Rebuilds the managed End map from the bundled schematic and refreshes its crystal anchors.
Use this while the match is stopped if you want a clean event map again.
Shows the current managed End world status, center point, and detected crystal anchor count.
Creates a team.
Invites a player to your team.
Accepts a team invite.
Leaves your team.
Kicks a player from your team if you are the leader.
Disbands your team if you are the leader.
Opens the GUI team menu.
This plugin is intentionally very editable.
Text in messages.yml, config.yml, kits.yml, and scoreboard.yml accepts legacy & color/style codes, section-sign codes, &#RRGGBB and #RRGGBB hex colors, and extended legacy RGB codes such as &x&F&F&0&0&A&A. Adventure MiniMessage tags are also supported, including named colors, <#RRGGBB>, gradients such as <gradient:#8B5CF6:#22D3EE>text</gradient>, bold, italic, underline, strikethrough, obfuscation, reset, and standard click/hover tags in component-rendered text. Placeholders such as %player% remain supported.
Main gameplay configuration.
This file controls:
- bossbar settings
- EggHolder visuals
- holder gear
- holder effects
- death state
- teleporter settings
- team settings
- match start settings
- feature toggles
- feature timings
- audience vote behavior
- supply drop loot
On startup and /eggholder reload, EggHolder validates feature switches, known timing values, materials, and potion effects. Invalid feature switches are reset to their documented defaults in memory, timing values are clamped to safe bounds, and item/effect loaders use their fallback behavior. Validation warnings are written to the server console. Validation does not rewrite the YAML files.
All visible text shown to players.
This includes:
- prefix
- command feedback
- event announcements
- titles
- subtitles
- kill and egg messages
- admin control messages
If you want to translate or re-theme the plugin, this is the first file to edit.
Defines all hunter kits.
Each kit can customize:
- name
- icon
- description
- potion effects
- items
- enchantments
- slots
Defines the sidebar scoreboard layout.
You can fully change:
- scoreboard title
- each line
- what information is visible
If you are hosting the event, a simple workflow is:
- Configure
config.yml,messages.yml,kits.yml, andscoreboard.yml. - If you use the bundled custom End map, verify it with
/endwar world status. - Start the server and let players join.
- Tell players to choose teams and kits.
- Run
/start. - Let teams enter the overworld portal.
- Monitor the event using:
/endwar feature .../endwar audience .../endwar world status/revive <player>/eggholder reload
If you are a participant:
- Join the server.
- Open the Team Menu and choose your team.
- Open the Kit Menu and choose your hunter kit.
- Wait for the admin to start the match.
- Enter the End portal.
- Fight for the Dragon Egg.
- Hunt the EggHolder or defend your teammate if they become the holder.
- If you die, use ghost mode and teleporter tools until revived or until the event ends.
mvn clean packageThis also runs the automated resource and configuration contract tests. To run the tests without packaging:
mvn testThe final jar will be created at:
target/EggHolder.jar
The Maven artifact is published to GitHub Packages for developers who want to consume EggHolder as a Maven dependency. A push runs one workflow: it builds against Paper API 1.20.6 and 1.21.11, then publishes a unique CI package only after both builds pass. Pull requests run both builds but do not publish. CI versions follow the release version in pom.xml, for example 2.2.3-ci.42.1. To publish a stable Maven version, run EggHolder CI and Package from GitHub Actions using Run workflow and enter the release version (for example 2.2.3); leave it blank to publish a unique CI version.
Coordinates for the current release:
<dependency>
<groupId>me.tasfiq</groupId>
<artifactId>eggholder</artifactId>
<version>2.2.3</version>
</dependency>Repository URL: https://maven.pkg.github.com/TasfiqSami/EggHolder.
GitHub Packages requires Maven authentication to download artifacts. Create a GitHub Personal Access Token (classic) with read:packages, then add it to your local Maven ~/.m2/settings.xml (do not commit this file or token):
<settings>
<servers>
<server>
<id>github</id>
<username>YOUR_GITHUB_USERNAME</username>
<password>YOUR_TOKEN</password>
</server>
</servers>
</settings>The server ID must match the repository ID github. GitHub's Maven registry requires authentication for package downloads; see GitHub's Maven registry documentation.
For a Minecraft server installation, download EggHolder.jar from GitHub Releases instead.
- Build the jar or use the packaged one.
- Place
EggHolder.jarinto your serverplugins/folder. - Start the server once so the config files generate.
- Edit the YAML files if needed.
- Restart the server or run
/eggholder reload.
- This plugin is designed for competitive event play, not vanilla survival balance.
- Most behavior is configurable, but bad configs can still create unfair matches.
- If you plan to host large events, test your chosen settings on a staging server first.
- The plugin is built around Paper APIs and should not be treated as a generic Bukkit/Spigot drop-in.
The current player holding the Dragon Egg.
An End-based PvP event centered around control of the Dragon Egg.
The plugin's spectator/ghost mode for eliminated players.
Voting powers available to dead players when enabled.
A temporary buff zone in the End.
Late match phase where revives stop and the event becomes final.
If you only remember one thing, remember this:
EggHolder is a full event-control plugin for running a Dragon Egg PvP war in the End, with automatic tracking, teams, kits, dead-player audience tools, live admin controls, and strong late-game pressure systems.