ArenaEngine

Instanced arenas for Paper. Every match runs in its own world, stamped out from a template map on demand and thrown away afterwards, so two matches on the same map never touch each other.

Setting one up

1. Build your map on a normal world and stop the server so it saves.
2. Copy that world folder into plugins/ArenaEngine/maps/<name>. The folder is the one holding level.dat.
3. Write plugins/ArenaEngine/templates/<name>.yml. Starting the plugin with no templates writes a commented duel.yml you can edit.
4. /arena reload, then /arena join <name>.

Nothing under maps/ is ever loaded as a live world, which is what keeps the pristine copy pristine. Instances are created next to your other worlds and are named ae_<template>_<n>.

Commands

Command	Permission	What it does
/arena join <template>	arena.play	Drops you into a match, building an arena if none is free
/arena leave	arena.play	Steps back out and gives your gear back
/arena list	arena.play	Templates that loaded, and why any of them did not
/arena status	arena.admin	What every instance is doing right now
/arena reset <arena>	arena.admin	Ends the round and puts the map back
/arena close <arena>	arena.admin	Unloads an instance and deletes its folder
/arena prewarm <template>	arena.admin	Brings idle instances up ahead of demand
/arena send <player> <template>	arena.admin	Puts someone else into a match
/arena reload	arena.admin	Rereads config, messages and templates

arena.bypass lets you build and run commands inside an arena.

How a reset works

Templates pick one of two policies.

ROLLBACK writes down what each block looked like the first time a match changed it, then replays that backwards in slices when the round ends. It is fast and it never touches the disk. It gives up and falls back to a rebuild in two cases: the match passed journal-cap changes, or it touched a block a BlockData cannot describe, such as a chest with items in it.

RECREATE unloads the world, deletes the folder and copies the map again. Slower, but correct for maps full of containers.

Recovering from trouble

• A world copy that fails is retried a couple of times, since the usual cause is a file handle the OS has not released yet.
• An instance stuck in a state past its deadline is picked up by the watchdog, emptied and either repaired or dropped.
• Player gear is mirrored to plugins/ArenaEngine/restore/ for the length of a visit. If the server dies mid match, the next join hands it back.
• Instance folders carry a marker file. Anything left behind by a crash is swept on the next start, and periodically after that.

Files

plugins/ArenaEngine/
  config.yml       pool sizing, timeouts, isolation, lobby, webhook
  messages.yml     every line the plugin can say
  templates/       one yml per arena kind
  maps/            the pristine map folders templates copy from
  restore/         gear held for players currently inside an arena