CPVPEvent+ documentation

What CPVPEvent+ does.

CPVPEvent+ is one plugin that handles everything you need to run an event on a Crystal PvP server. The world, the border, the kits, the chat, the spectators, the auto events, the gulag, and the parties. All in one config file.

Drop the jar in, paste your license key, tell it which world is your event world, done. The rest of this page explains how each piece works. If you just want to get it running, go straight to Installation and License Activation.

Demo · YouTube

CPVPEvent+ in action

Quick video showing how the plugin works in-game.

→

What's inside.

One jar, one config. No extra plugins required (PlaceholderAPI and TAB are optional, the plugin works fine without them).

Server requirements.

Drop in, restart, configure.

The jar carries everything it needs. The whole install takes about two minutes.

1. Download CPVPEvent+.jar

   Grab the latest jar from your BuiltByBit purchase page.

2. Drop it in plugins/

   Place the jar in your server's plugins/ folder. If you want PlaceholderAPI placeholders or TAB integration, install those too. they're optional but supported.

3. Start the server once

   This generates plugins/CPVPEvent+/config.yml. The plugin will disable itself with a license error. that's expected on first boot.

4. Paste your license key

   Open config.yml and replace PASTE-YOUR-KEY-HERE with the key from your BuiltByBit purchase. See License Activation for the full walkthrough.

5. Configure your worlds

   Set world.target-world and world.spawn-world. See Configuring Worlds.

6. Restart the server

   On a clean boot you should see License verified and Plugin enabled in the console.

Setting up your license key.

The plugin checks your license key every time the server starts. If it's missing or wrong, the plugin shuts itself off and prints an error in the console.

Step 1 · Find your key

Go to BuiltByBit, open your CPVPEvent+ purchase page, and grab the key from the Licenses tab. It looks like a long string of letters and numbers.

Step 2 · Open config.yml

The file lives at plugins/CPVPEvent+/config.yml. The license block is right at the top.

# CPVPEvent+ Configuration
# Support: https://discord.gg/7KKz3rYs8U
# Purchase: https://builtbybit.com/resources/cpvpevent.96670/

license:
  key: 'PASTE-YOUR-KEY-HERE'

Step 3 · Paste the key

Replace the placeholder with your actual key. Keep the surrounding single quotes.

license:
  key: 'a1b2c3d4-XXXX-XXXX-XXXX-c5d6e7f80912'

Step 4 · Restart the server

A reload (/reload or /cepreload) is not enough. The license check runs in onEnable, so you need a full restart.

Step 5 · Verify activation

On success, the plugin prints a banner like this in the console:

╔══════════════════════════════════════════╗
║         CPVPEvent+. License          ║
╠══════════════════════════════════════════╣
║  ✔  License verified                     ║
║  ✔  License valid                        ║
║  ✔  Plugin enabled                       ║
╚══════════════════════════════════════════╝

If you see a red banner with ✗ License validation failed, jump to Troubleshooting.

Target world & spawn world.

You've got two worlds to set up: the event world (where the actual PvP happens, with the border) and the spawn world (the lobby players go back to). Both are configured in the world: block of config.yml.

world:
  target-world: world_minecraft_desert   # the event map
  spawn-world:  world                    # the lobby
  10-seconds-safe-protection: false
  auto-kit: false
  default-kit: /k1
  load-publickit-before-default-kit: false
  spawn-location:
    x: 0.5
    y: 64.0
    z: 0.5
    yaw: 180
    pitch: 0.0

What goes where

How to set up /regen.

/regen resets your event maps. It deletes the live world folders and replaces them with clean templates you set up beforehand. The actual swap happens on the next server boot, before any world is loaded, so it's always safe.

The system supports multiple worlds at once. Drop one template folder per world into plugins/CPVPEvent+/regen-templates/ and the plugin resets all of them in parallel on the next startup. Same approach as the MultiReset plugin, but built in.

How it works

When you run /regen: the plugin writes a small flag file, blinds and kicks players, then triggers a server restart. On the next startup, before Bukkit loads any world, the plugin sees the flag and spins up one thread per template folder. Each thread deletes the live world and copies the template in its place. The main thread waits until every reset finishes, then deletes the flag and the server boots normally.

Step 1 · Create clean backups of your event worlds

Stop the server. For each world you want resettable, copy its folder to your local machine and clean it up: remove chunks you don't want, reset spawn protection, whatever. These are the worlds players will get back every time someone runs /regen.

Step 2 · Place templates in regen-templates/

Drop each backup world folder into plugins/CPVPEvent+/regen-templates/. The folder is created automatically on first start. Each subfolder name must exactly match the live world name on disk.

Step 3 · Tune the regen block in config.yml

The defaults work for most setups. The two settings worth knowing about are templates-folder and restart-method.

regen:
  templates-folder:  regen-templates           # subfolder of plugins/CPVPEvent+/
  restart-method:    restart                   # 'restart' (recommended) or 'shutdown'
  kick-message:      '&cThe map is regenerating. Try again later.'
  restart-delay:     40                          # ticks between announce and kick (40 = 2s)

  # Legacy single-world fallback. Only used if the templates
  # folder is empty AND a single world is found at the path
  # below. Most setups can ignore these two lines.
  world-name:        world_minecraft_desert
  backup-folder:     world_minecraft_desert

Step 4 · Make sure your host can restart the server

With restart-method: restart (the default), the plugin dispatches Bukkit's /restart command. That uses your bukkit.yml's settings.restart-script when one is configured, otherwise it falls back to a clean shutdown.

On hosts with auto-restart-on-crash (Pterodactyl, Folium, systemd, screen-loop wrappers), either method will bring the server back up. If restart misbehaves on your host, set restart-method: shutdown instead, which forces a clean Bukkit.shutdown() and lets the wrapper handle the relaunch.

Step 5 · Test it

As an op, run /regen. You'll see a title and chat broadcast, players get kicked with the configured message, and the server restarts. On boot you'll see something like:

[CPVPEvent+] Regen flag detected - applying templates (MultiReset-style)...
[CPVPEvent+] Resetting 3 world(s) in parallel...
[CPVPEvent+] Resetting 'world_minecraft_plains' from .../regen-templates/world_minecraft_plains
[CPVPEvent+] Resetting 'world_minecraft_desert' from .../regen-templates/world_minecraft_desert
[CPVPEvent+] Resetting 'world' from .../regen-templates/world
[CPVPEvent+] 'world_minecraft_plains' reset in 412ms.
[CPVPEvent+] 'world' reset in 588ms.
[CPVPEvent+] 'world_minecraft_desert' reset in 624ms.
[CPVPEvent+] Regen complete - 3 world(s) ready for startup.

Setting up the gulag.

/revfights <n> grabs n pairs of dead spectators, copies a fresh arena world for each pair, and throws them into a 1v1 with a 50-block border and a 3-minute timer. Winners come back to life, losers stay dead. Arena copies get deleted on the next restart.

Step 1 · Build your arenas

You can have as many arena templates as you want. The plugin picks one at random for each fight. Each one is just a regular world folder with a level.dat. Build them on a creative server, in singleplayer, wherever, then copy the world folder over.

Step 2 · Place templates in RevFights-Worlds/

Drop each arena world folder into plugins/CPVPEvent+/RevFights-Worlds/. The folder is created automatically on first start.

Step 3 · Run a fight

As an op, while the event is live:

/revfights 4   # start 4 simultaneous 1v1s (8 dead players)
/rflist       # list active fights

Loaded copies are named RevFightWorld-001, -002, … in the server root. They're all deleted automatically on the next restart, but if you want to flag them for cleanup right now use /delrfworlds.

Command reference.

Every command requires its corresponding cpvpevent.<name> permission, or op.

Event control

World & border

Players & rekits

Toggles

RevFights & party

Tools & admin

Permission nodes.

Each command has its own node, all under the cpvpevent. prefix. Two convenient umbrella nodes exist for staff:

For everything else, use cpvpevent.<command>, for example cpvpevent.regen, cpvpevent.revfights, cpvpevent.startevent, cpvpevent.eventstatus. The full list of nodes is in plugin.yml.

The settings you'll actually touch.

config.yml has comments on basically every line. The most useful settings are listed below. The rest is mostly cosmetic stuff (titles, chat messages, colors).

General settings

settings:
  join-as-spectator:     false
  rekit-enabled:         true
  chat-enabled:          true
  protection-enabled:    false
  pvp-enabled:           true
  fall-damage-enabled:   false

suppress-chat-messages:  false   # silence plugin broadcasts

Border & storm sickness

border:
  initial-size: 100     # radius in blocks

border-damage:
  enabled:          true
  base-damage:      2.0
  max-damage:       8.0
  damage-increase:  0.5

storm-sickness:
  enabled:            true
  tick-threshold:     15
  warning-threshold:  5
  warning-interval:   5
  safe-zone-distance: 0

Border action bar

Optional pop-in action bar that shows the live border size while it's animating to a new target. When active, it takes priority over the rekit action bar and the countdown action bar.

border-action-bar:
  enabled: false
  format:  '&#FFCC00Border: &#FF2B2B<current_border_size> &#AAAAAA-> &#FF2B2B<border_final_size>'

Placeholders: <current_border_size> and <border_final_size> (radius in blocks). Standard & color codes and &#RRGGBB hex codes both work.

"You died!" title

Red title that flashes when a player dies. Set enabled: false to turn it off entirely.

titles:
  you-died:
    enabled:  true
    main:     '&#FF2B2B&lYou died! ☠︎'
    subtitle: ''
    fade-in:  5
    stay:     40
    fade-out: 10

Allowed spawn blocks

The random teleport at event start (and on late-join into a running event) only lands players on top of one of these block types. After 60 failed tries the plugin falls back to "any solid surface" so a player is never left un-teleported.

allowed-spawn-blocks:
  - GRASS_BLOCK
  - MYCELIUM
  - SAND
  - RED_SAND
  - SNOW          # 1-8 layer snow
  - SNOW_BLOCK    # full snow block
  - POWDER_SNOW

Use any Bukkit Material name, case-insensitive. Leave the list empty to use the built-in defaults shown above.

Blocked commands during events

For non-op players while the event is running. Spectators can still use the entries listed under spectator-allowed-commands.

blocked-commands:
  enabled: true
  commands:
    - spawn
    - rtp
    - regear
    - heal
    - repair

spectator-allowed-commands:
  enabled: true
  commands:
    - spawn
    - hub
    - lobby

Four modes, one command.

/startevent <minutes> <mode> <announce> queues an event with a countdown, sequential drops, kit broadcasts, border phases, and a winner announce.

While a sequence is live, use /pauseevent / /resumeevent to handle restarts or staff calls, and /stopevent to abort cleanly. /startforce <mode> <announce> skips the countdown if you need to start right now.

You can also start any of these from the visual GUI: /eventsettings → pick mode → Force Start or Normal Start. Same flow, no typing required.

Live readout for Automatic mode.

/eventstatus shows you exactly where the Automatic event sequence is right now. Past steps are dimmed, the current step is highlighted, and upcoming steps are listed with a countdown to the next fire.

Markers:

• ✓  step has already fired
• ►  step is the most recent fire (current step)
• ·  step is upcoming

/eventstatus

Event Status → Automatic mode (elapsed 4:23)
 ✓ T+0:00   Border 100m (instant)
 ✓ T+1:30   Drop deepslate
 ► T+3:00   Border 80m over 60s
 · T+5:00   Drop bedrock + reviveall
 · T+8:00   Border 50m over 90s
 · T+12:00  Finish
Next step in 0:37

The command works only while an event is running in Automatic mode. In any other mode (HighPlayers, LowPlayers, Manually) it tells you so. Permission node: cpvpevent.eventstatus (default: op).

Schedule a fight every day.

The plugin can fire /startevent automatically at the same time every day. Configured in config.yml:

daily-event:
  enabled:      true
  time:         '18:00'      # 24-hour, server timezone
  mode:         HighPlayers
  waiting-time: 10           # minutes between announce and start
  announce:     true

If you change daily-event.time at runtime, run /cepreload for the scheduler to pick it up.

Built-in teams with friendly fire off.

Players can group up to 8 with /party create and /party invite. Members see each other glowing (only teammates see the glow, nobody else), and they get their own chat channel with /p <message>.

/party create
/party invite Heuxil
/party accept
/party kick Evoma_the_bot
/party leave

If you want to disable parties for a specific event, the cpvpevent.party.admin permission unlocks disable, enable, and disbandall.

party:
  max-size: 8

No camping outside the border.

Storm Sickness counts ticks for any player who's outside the border. Once they go past tick-threshold ticks over the limit, they get eliminated with a death title. You can set up a safe-zone-distance around spawn where players are immune.

storm-sickness:
  enabled:            true
  tick-threshold:     15   # ticks past border before elimination
  warning-threshold:  5    # show warning at N ticks remaining
  warning-interval:   5
  safe-zone-distance: 0    # radius (blocks) of immune zone around spawn

To disable the mechanic entirely, set storm-sickness.enabled to false and reload.

Available placeholders.

If PlaceholderAPI is installed, the following placeholders register under the cpvp identifier.

When something looks off.

License validation failed

Open the console and read the error line. The most common reasons:

• The placeholder is still there. Make sure license.key is your real key, not PASTE-YOUR-KEY-HERE.
• Quotes were dropped. Keep the surrounding single quotes in config.yml.
• The server can't reach the API. Network issues or a firewall blocking outbound HTTP. The plugin needs to talk to the SunLicense API on enable.
• You did /reload. A plugin reload doesn't re-run the license check. Use a full server restart.

"World 'X' not found! Run /regen first."

The world configured as world.target-world doesn't exist on disk. Either generate it manually, set the value to a world that does exist, or place a template folder in plugins/CPVPEvent+/regen-templates/ and run /regen once.

/regen kicks players but never restarts

The plugin dispatches /restart by default. If your host doesn't have a working settings.restart-script in bukkit.yml, the server will shutdown and your wrapper needs to bring it back up. Two things to check:

• On Pterodactyl/Folium, make sure Auto-restart on crash is on in the panel.
• If /restart misbehaves on your host, try regen.restart-method: shutdown in config.yml to force a clean shutdown instead.

/regen finished but my world looks the same

Two common causes:

• The template folder is empty or invalid. Each subfolder under regen-templates/ needs a real level.dat + chunks. If it's empty, the plugin "resets" to nothing and Minecraft regenerates fresh terrain.
• You captured the template after your changes. The template is whatever you copied. If it already has your changes baked in, the regen "works" but the result looks identical to what was there before. Re-capture from a fresh world.

/regen looks fine right after, but breaks once players walk around

Your template doesn't include all the chunks. World folders only contain the chunks that were loaded on disk when you copied them, so any unvisited chunk gets regenerated from scratch the first time a player walks into it after /regen, which produces patchy terrain, weird biome borders, and players occasionally spawning in mid-generation chunks.

Fix: install Chunky, run /chunky world <name> + /chunky radius <blocks> + /chunky start to pre-generate every chunk inside the event area, then capture the template. See the FAQ for the full sequence.

Border placeholder shows wrong world

As of the latest version, %cpvp_border% and the in-game scoreboard Border: line both auto-track world.target-world from config.yml. If you're on an older build and seeing a hardcoded world name, update the plugin.

RevFights does nothing

Check the console for [RevFights] No world templates found in .... That means you haven't put any arenas in plugins/CPVPEvent+/RevFights-Worlds/. Each subfolder in there counts as one arena template.

Placeholders don't expand

Make sure PlaceholderAPI is installed. On startup you should see PlaceholderAPI register result: true in the console. If you don't see it, the plugin will warn you.

Common questions.

Stuff people ask a lot. Short answers first.

/chunky world <your-world>
/chunky radius 200      # a bit larger than your event border
/chunky start
# wait for it to finish (can take a while on big radii)

Need help?

Open a ticket on Discord and I'll get back to you. When you do, please include your server software (Paper, Spigot, etc.), the plugin version, and any error lines from the console. Saves a ton of back and forth.