ChallengeUtil

ChallengeUtil - Advanced Speedrunning & Challenge Plugin

Dependencies: Minecraft 1.21.11 (Paper/Spigot) Dependencies: PlaceholderAPI (optional, for team chat prefixes)

---

Overview

ChallengeUtil is a comprehensive Minecraft plugin designed for speedrunning servers and challenge gamemodes. It features instant world resets (~30 seconds, no server restart!), a built-in timer system, multiple game modes, and various challenge mechanics to create unique and engaging gameplay experiences.

Perfect for Velocity/BungeeCord proxy networks - players stay connected during world regeneration!

---

Key Features

Instant World Reset System - Async world deletion without server restart - Async world deletion: Players are smoothly transferred to a waiting room while the speedrun world regenerates - Async world deletion for each reset - Async world deletion: Full Velocity/BungeeCord support with auto-reconnect - Async world deletion: Players remain connected throughout the entire reset process - Async world deletion: Zero lag during world regeneration

Advanced Timer System - Real-time timer display above the hotbar (action bar) - Format: `HH:MM:SS` with visual indicators - Color-coded states: - Light Purple when running - Red with pause symbol (⏸) when paused - Start, pause, reset, and resume functionality - Persistent through pause/resume cycles - PlaceholderAPI support for external plugins

Multiple Game Modes

Dynamic Spawning Classic speedrunner vs hunters gameplay: - Dynamic Spawning: 1+ speedrunners trying to defeat the Ender Dragon - Dynamic Spawning: 1+ hunters trying to stop the runners - Dynamic Spawning: Hunters receive a compass that tracks the nearest runner - Dynamic Spawning: Friendly fire protection within teams (configurable) - Dynamic Spawning: Spectators can watch without interfering - Dynamic Spawning: Hunters spawn 10 minutes after `/start` for balanced gameplay

Scoreboard Integration Competitive team-based speedrunning: - Scoreboard Integration: Customizable team count with German names and colors - Scoreboard Integration: Rot, Blau, Grün, Gelb, Lila, Aqua, Weiß, Orange, Pink, Grau - Scoreboard Integration: Each team tracks the nearest enemy team member - Scoreboard Integration: Team names appear in their respective colors - Scoreboard Integration: First team to defeat the Ender Dragon wins - Scoreboard Integration: Real-time team tracking and status

Challenge Modes

Default Exclusions - Receive random items when entering new chunks - Default Exclusions: Different players get different items from the same chunk - Default Exclusions: Each chunk gives the same item to a player on re-entry - Default Exclusions: Hunters receive items only after 10 minutes - Default Exclusions: Customize which items can drop - Default Exclusions: Overpowered items (Elytra, Netherite gear, Totems) excluded by default

Team Integration Damage teammates, get rewards: - Team Integration: Both attacker and victim take the same damage - Team Integration: Natural health regeneration disabled - Team Integration: Lower health = better items - Team Integration: Basic items (Golden Apples, Arrows, Iron) - Team Integration: Medium items (Diamonds, Enchanted Iron gear) - Team Integration: Strong items (Diamond gear with Sharpness V, Totems) - Team Integration: Extremely OP items (Netherite, fully enchanted diamond gear, multiple totems) - Team Integration: Works with both Manhunt and Team Race modes

Advanced Configuration

Smart Teleportation - Smart Teleportation: Lobby world where players wait during resets (peaceful, frozen time) - Smart Teleportation: Main world that gets regenerated with new seeds - Smart Teleportation: Different gamerules for each world - Smart Teleportation: Surface-detection spawn system

World Generation Settings - World types: NORMAL, FLAT, LARGE_BIOMES, AMPLIFIED - Structure generation toggle - Configurable difficulty - Random or fixed seed generation - Custom spawn coordinates

Proxy Integration - Full BungeeCord/Velocity support - Auto-reconnect during world resets - Configurable server names - Companion proxy plugin included

---

Commands

Main Commands

| Command | Aliases | Description | Permission | |---------|---------|-------------|------------| | `/start` | - | Start or resume the timer | `challenge.start` | | `/pause` | - | Pause the timer | `challenge.pause` | | `/reset` | - | Reset timer only (no world reset) | `challenge.reset` | | `/fullreset` | `/resetworld`, `/worldreset` | Holodeck reset - regenerate world instantly (3-5 sec) | `challenge.fullreset` | | `/join` | `/play`, `/go` | Join the speedrun world from waiting room | `challenge.join` | | `/settings` | `/config`, `/cfg` | Open settings GUI (waiting room only) | `challenge.settings` | | `/team <name>` | - | Join a team (Manhunt or Team Race) | `challenge.team` |

Team Command Examples Manhunt Mode: - `/team runner` - Join the runner team - `/team hunter` - Join the hunter team - `/team spectator` - Join spectators

Team Race Mode: - `/team` - List all available teams and member counts - `/team Rot` - Join Team Rot (Red) - `/team Blau` - Join Team Blau (Blue) - `/team Grün` - Join Team Grün (Green) - etc.

---

Permissions

Main Permissions

| Permission | Description | Default | |------------|-------------|---------| | `challenge.host` | Master permission - grants all admin commands | OP | | `challenge.start` | Start/resume the timer | OP | | `challenge.pause` | Pause the timer | OP | | `challenge.reset` | Reset timer only | OP | | `challenge.fullreset` | Execute Holodeck reset (world regeneration) | OP | | `challenge.settings` | Open settings GUI | OP | | `challenge.join` | Join speedrun world from waiting room | True (all players) | | `challenge.team` | Join teams in Manhunt/Team Race | True (all players) | | `challenge.*` | Grant all permissions | OP |

Permission Hierarchy The `challenge.host` permission includes: - `challenge.start` - `challenge.pause` - `challenge.reset` - `challenge.fullreset` - `challenge.settings`

---

Host Control Features

Players with the `challenge.host` permission receive special tools:

Right-click - Right-click automatically given on join - Right-click to open Host Control GUI - Quick access to all host commands without typing

⚠ FULL RESET ⚠ Interactive menu with three options: 1. ⚠ FULL RESET ⚠ (Green Wool) - Executes `/start` 2. ⚠ FULL RESET ⚠ (Comparator) - Opens `/settings` GUI 3. ⚠ FULL RESET ⚠ (Barrier) - Executes `/fullreset` with warning

---

Configuration

The plugin features extensive configuration through `config.yml`:

Proxy Settings ```yaml proxy: lobby-server: lobby1 # Lobby server name in proxy config this-server-name: challenge1 # This server's name in proxy config ```

World Settings ```yaml world: waiting-room: waiting_room # Fallback world (lobby) speedrun-world: speedrun_world # World that gets regenerated

generation: type: NORMAL # NORMAL, FLAT, LARGE_BIOMES, AMPLIFIED generate-structures: true random-seed: true

difficulty: NORMAL # PEACEFUL, EASY, NORMAL, HARD

teleport: waiting-room-spawn: x: 0 y: 65 z: 0 speedrun-spawn: x: 0 y: 100 # Auto-finds surface z: 0 ```

Gamerules Separate gamerule configurations for waiting room (peaceful, frozen time) and speedrun world (normal gameplay).

Challenge Settings ```yaml challenge: allow-respawn: true # false = hardcore mode (spectator on death)

chunk_items: excluded: # Items to exclude from random rewards

- DIAMOND

- EMERALD

friendly_fire_item: enabled: false # Toggle via GUI ```

---

PlaceholderAPI Integration (optional)

Available Placeholders

| Placeholder | Description | Example Output | |-------------|-------------|----------------| | `%ch_prefix%` | Team prefix with color | `[RUNNER]`, `[HUNTER]`, `[Red]` | | `%ch_suffix%` | Team suffix (reserved) | - | | `%ch_team%` | Raw team name | `runner`, `hunter`, `Rot` | | `%ch_team_color%` | Legacy team color code | `§d`, `§6`, `§c` |

Usage Example EssentialsX Chat: ```yaml format: '{ch_prefix}{DISPLAYNAME}{ch_suffix}§r: {MESSAGE}' ```

---

Game Modes Comparison

Mode Compatibility Matrix

| Feature | Manhunt | Team Race | Solo | |---------|---------|-----------|------| | Timer System | ✅ | ✅ | ✅ | | Instant Reset | ✅ | ✅ | ✅ | | Team System | ✅ | ✅ | ❌ | | Tracking Compass | ✅ (Hunters only) | ✅ (All teams) | ❌ | | Chunk Items Challenge | ✅ | ✅ | ✅ | | Friendly Fire Challenge | ✅ | ✅ | ❌ | | Multiple Teams | ❌ (2 teams) | ✅ (2-10 teams) | ❌ | | Can Run Simultaneously | ❌ | ❌ | ✅ |

Note: Manhunt and Team Race cannot be enabled simultaneously.

---

Technical Details

Performance - Compass Updates: 10-30 seconds typical - Compass Updates: Async (non-blocking) - Compass Updates: Sync (main thread, optimized) - Compass Updates: Every second (20 ticks) - Compass Updates: Every second (20 ticks)

---

Installation

Basic Installation 1. Download `ChallengeUtil.jar` 2. Place in your server's `plugins` folder 3. Configure `server.properties`: ```properties level-name=waiting_room ``` 4. Restart your server 5. Configure `plugins/ChallengeUtil/config.yml` 6. Reload or restart

Optional: PlaceholderAPI 1. Install PlaceholderAPI from SpigotMC 2. Restart server 3. Placeholders automatically register 4. Use in chat plugins (EssentialsX, ChatControl, etc.)

---

Usage Examples

Basic Speedrun Setup 1. Server starts with players in waiting room 2. Admin: `/settings` - Configure challenge settings 3. Players: `/join` - Enter speedrun world 4. Admin: `/start` - Begin timer 5. Players: Complete speedrun 6. Admin: `/fullreset` - Instant 3-5 second reset for next run

Manhunt Setup 1. Enable Manhunt mode in `/settings > Challenges` 2. Players join teams: - `/team runner` (speedrunners) - `/team hunter` (hunters) 3. Admin: `/start` 4. Runners get 10-minute head start 5. Hunters spawn and receive tracking compass 6. First team to defeat Ender Dragon wins

Team Race Setup 1. Enable Team Race in `/settings > Challenges` 2. Players: `/team` to see available teams 3. Players join teams: `/team Rot`, `/team Blau`, etc. 4. Admin: `/start` 5. All teams receive tracking compasses 6. Race to defeat the Ender Dragon 7. First team wins!

---

Troubleshooting

Common Issues

"Waiting room not found" - Verify `level-name=waiting_room` in server.properties - Ensure waiting room world folder exists

Slow resets (>60 seconds) - Use Paper instead of Spigot - Use SSD instead of HDD - Reduce world size/pregenerate less - Check server TPS

Players fall into void - Increase `speedrun-spawn.y` to 120+ in config.yml - Plugin auto-finds surface, but high Y helps

Same seed every reset - Set `random-seed: false` in config.yml

Compass not working - Ensure players are in the same dimension - Check that target players are online - Verify team assignments with `/team`

Chat prefixes not showing - Install PlaceholderAPI - Check if expansion is registered: `/papi list` - Reload PlaceholderAPI: `/papi reload` - Verify chat plugin configuration

---

Perfect For

- Proxy Networks: Instant resets for practice or races - Proxy Networks: Unique gameplay mechanics - Proxy Networks: Classic hunter vs speedrunner - Proxy Networks: Multi-team races - Proxy Networks: Quick reset for skill improvement - Proxy Networks: Streamers and YouTubers - Proxy Networks: Multiple parallel speedrun instances

---

License

MIT License - Free to use for any server!

---

Active Development Active Development - 10-30 seconds, no server restart Active Development - Chunk Items, Friendly Fire Active Development - Perfect for networks Active Development - Customize everything Active Development - Full integration Active Development - Optimized and tested Active Development - GUI-based configuration Active Development - Regular updates

---

Built with ❤️ for the Minecraft speedrunning community

Download now and revolutionize your speedrunning server!