☀ SunManhunt

Chase the light.

SunManhunt is a complete manhunt plugin for Paper servers. It gives you a stable, default chase that works immediately, then lets you add social deduction, rotating prey, shops, a shrinking border, and random chaos scenarios when your group wants a different kind of hunt.

One jar. No client mod. No resource pack. No NMS.

Why SunManhunt?

• Ready on first start. The default game is an Ender Dragon hunt with one Runner, a team of Hunters, a 60 second grace period, and one Runner life.
• Easy to run. Start with a command or use the four step setup wizard. The plugin handles roles, compasses, grace freezing, deaths, respawns, disconnects, results, and cleanup.
• Built for variety. Six optional twist modes can be enabled individually or in compatible combinations.
• Admin friendly. Force join all online players, mass assign roles, create presets, pause and resume, and recover a saved active match.
• Configurable without code. Objectives, shops, messages, and most mode tuning live in YAML.
• Paper native. Adventure and MiniMessage are used directly from the platform. There are no shaded libraries and no server internals.

The default hunt

1. At least two players are online.
2. An operator runs /sm start.
3. SunManhunt randomly selects one Runner. Everyone else becomes a Hunter.
4. Hunters are frozen and PvP is disabled during the 60 second grace period. The Runner can move immediately.
5. Every Hunter receives a tracked compass that points to the nearest Runner and shows the distance.
6. The Runner wins by defeating the Ender Dragon. Hunters win by eliminating all Runners.

The default setup uses the current survival world and current inventories. SunManhunt does not create or reset a world and does not teleport players to a lobby.

If no lobby or role assignments exist, /sm start uses all eligible online players. For more control, use /sm setup, /sm join, or the role commands.

Six optional twist modes

Mode	What it adds
Ghost	Fallen Runners become ghosts when another Runner remains. Ghosts cannot interact with the world, but they can pulse to reveal nearby Hunters.
Imposter	One Runner is secretly allied with the Hunters. A Detective among the loyal Runners can expose the Imposter. A wrong accusation kills the Detective.
Rotating Prey	Multiple Runners take turns as the active prey. Inventory, health, and XP can transfer between turns.
Economy	Earn Sun Coins through pressure, hits, and milestones, then buy radar pings, grappling hooks, smoke bombs, and ender pearls. Balances persist between matches.
Shrinking Border	The world border closes over a configurable duration and pauses for key Runner milestones. The original border is restored when the match ends.
Scenario Roulette	Random short events interrupt the hunt. Includes Floor is Lava, Bounty Swap, Supply Drop, No Jump, and Randomizer Recipes.

Mode conflicts are enforced in both the command and GUI. The base mode is always active, and every twist mode is disabled by default.

Some mode details worth knowing:

• Ghost mode works best with multiple Runners. With a single Runner, death ends the hunt as usual.
• Imposter mode requires at least two Runners and disables itself otherwise.
• Rotating Prey can replace the incoming Runner's inventory when inventory transfer is enabled. Review the mode settings before enabling it.
• Shrinking Border affects every loaded world and restores the original borders afterward.

Objective engine

The objective is not limited to the Ender Dragon. Supported objective types include:

• Kill a specific entity: dragon, wither, warden, or another mob.
• Obtain one item or a full set of items.
• Complete an advancement.
• Reach a world, environment, or coordinate.
• Combine objectives with ANY or ALL logic.

New objectives and presets can be added in YAML. No plugin update is required to add a normal objective.

Admin and server tools

• /sm setup opens a four step setup wizard for roles, objective, modes, and launch.
• /sm joinall pulls every online player into the hunt lobby.
• /sm role all hunter force joins every online player and assigns the same role.
• /sm role add Alice runner promotes one player to Runner.
• /sm mode opens the mode selection GUI.
• /sm objective and /sm preset manage the objective and saved configurations.
• /sm pause, /sm resume, /sm reset, and /sm reload cover match management.
• /sm status shows the current state, objective, modes, timer, role counts, and lobby size.

Presets store an objective and a mode selection. They make it easy to keep separate configurations for events, streams, or different playgroups.

The compass updates on a configurable interval, handles cross dimension travel through portal links, and rewrites item text only when the displayed target changes.

Permissions

SunManhunt checks a separate permission for each command path.

Default players receive sunmanhunt.player by default. This covers help, status, joining and leaving, shops, ghost pings, accusations, and the private imposter channel.

Operators receive sunmanhunt.admin by default. This includes the player set plus match management, setup, reload, force join, and roster, mode, objective, and preset management.

Granular leaves are available for every action, including sunmanhunt.joinall, sunmanhunt.role.all, sunmanhunt.mode.enable, sunmanhunt.objective.set, and sunmanhunt.preset.load. A complete permission reference is included in the project documentation.

Compatibility

• Paper is required. Spigot is not supported.
• The jar is built for Paper 1.21.x through 26.3. The primary target is 26.x.
• The artifact is Java 21 bytecode. Use Java 21 for 1.21.x servers and Java 25 for current 26.x servers.
• The code is compiled against the oldest supported 1.21 API, uses capability checks for version-sensitive content, and contains no NMS.
• The current build is boot verified on Paper 26.3 and has automated unit and integration coverage. The full real-server gameplay matrix is documented in the project repository.

Installation

1. Put the SunManhunt jar in your server's plugins folder.
2. Use Java 21 for 1.21.x, or Java 25 for 26.x.
3. Restart the server.
4. Optional: install PlaceholderAPI for the %sunmanhunt_*% placeholders.
5. Run /sm setup, or have at least two players online and run /sm start.

Configuration

SunManhunt generates four files:

• config.yml: match rules, grace, lives, compass interval, default modes, persistence.
• objectives.yml: objective presets.
• modes.yml: mode tuning, shops, border settings, scenarios.
• messages.yml: MiniMessage text and the SunManhunt palette.

Default mode selection lives in config.yml under defaults.modes. /sm mode enable and /sm mode disable update it for you.

Persistence

With active-match persistence enabled, roles, initial roles, objective, mode set, currency, lives, names, original game modes, remaining grace, disconnect deadlines, and match timing are saved periodically and on shutdown. Imposter identity and Shrinking Border state are restored on resume, while Rotating Prey rebuilds its rotation candidates from the saved initial roles. The resume policy can be set to automatic, manual, or disabled.

Player currency and statistics are stored in plugins/SunManhunt/data/players. Economy balances carry across matches.

PlaceholderAPI

Optional placeholders include state, objective, mode list, runners, hunters, elapsed time, role, balance, currency name, distance, lobby size, match ID, and winner.

Credits

SunManhunt is a Paper plugin by Lethargos. It is designed for server events, SMP manhunts, and creators who want a complete baseline without locking every match into a single rule set.