Tactical 5v5 — full guide

1. Requirements

• Paper 1.21.11 — the setup is built and tested against this version. Spigot and CraftBukkit are not supported: the plugin uses Paper APIs that do not exist there.
• Java 21
• Disk — allow a few gigabytes for the worlds and the resource pack.
• A database is optional. MariaDB or MySQL for production; SQLite works with no database server at all. See Storage.
• Redis — optional and off by default. It is only useful across multiple server instances.

2. What's in the archive

server/            # copy the contents of this over your Paper install
  plugins/         # the plugin jar and its configuration folder
  arena_split/     # the competitive arena, fully configured
  world/           # the furnished lobby
  training_range/  # the training world
resource-pack/     # the pack, plus the scripts that generate it
docs/              # the written guides
presets/           # ten ready-made server characters
legal/             # licence register and asset origins
scripts/           # setup, backup, validation, rebranding (Linux + Windows)

3. Installation

Any host, by hand

1. Start from a clean Paper 1.21.11 install and stop the server.
2. Copy the contents of the archive's server/ folder over your server directory.
3. Host the resource pack somewhere reachable and set resource-pack and resource-pack-sha1 in server.properties. The pack is optional, but the custom weapon models, icons and sounds come from it.
4. Start the server. The plugin creates its own database schema on first boot.

With the scripts

# Linux
./scripts/validate-setup.sh --preset production-mariadb
./scripts/setup.sh --preset production-mariadb

# Windows
.\scripts\validate-setup.ps1
.\scripts\setup.ps1

validate-setup checks the install before it changes anything, so run it first. It is also the fastest way to find a missing world, an unset environment variable, or a pack whose checksum does not match.

4. Storage

Four modes, set in plugins/BoteraMC/config.yml. SQLite needs no database server and is a perfectly reasonable way to run a single instance permanently.

storage:
  mode: sqlite          # memory | none | sqlite | mariadb | mysql
  fail-on-unavailable: true
  sqlite:
    file: "plugins/BoteraMC/data/boteramc.db"

redis:
  enabled: false

fail-on-unavailable: true means the server refuses to start if the database cannot be reached, rather than starting and losing everything written while it was down. Leave it on.

5. First boot

A healthy start looks like this:

[BoteraMC] [Database] Schema v52 (up to date).
[BoteraMC] Storage initialized in mode sqlite.
[BoteraMC] Loading arena world: arena_split
[BoteraMC] Arena world loaded: arena_split
[BoteraMC] Extra world loaded: training_range
[BoteraMC] [FFA] Loaded 12 spawns for arena: split
[BoteraMC] [BotNav] arena_split: LOADED cached grid
[BoteraMC] Registered 10 agents with 40 spells.
[BoteraMC] All modules loaded.

The schema number rises with updates; what matters is that it says applied or up to date and not an error. Bot navigation loads from a cached grid that ships with the arena, so bots play from the first boot without computing anything.

6. The eight modes

All eight run on the included arena. Modes are enabled per server in the module list; the FFA modes are chosen by player vote between rounds.

Longer descriptions of each mode →

7. Agents & abilities

Ten agents across five roles, four ability slots each — a signature, two tactical abilities and an ultimate — for forty in total. Every cost, cooldown and charge count is configurable in spells.yml without touching code.

phantom:
  spells:
    smoke-bomb:
      type: ABILITY_1
      cooldown: 32
      cost: 300
      max-charges: 1
      radius: 4.5
      duration: 14

All ten agents and their forty abilities →

8. The ranked ladder

Sixteen ranks: Stone, Iron, Gold, Diamond and Netherite in three tiers each, then Immortal on its own. Rating rewards the margin you won by rather than the win alone.

• Winning pays +21 to +29 depending on the scoreline; losing costs −15 to −25.
• Match MVP adds +5.
• Win streaks add +5 per consecutive win, capped at +20. Losing streaks cost −3 each, capped at −12.
• Placement matches move rating at double rate.
• A demotion shield absorbs the first loss at zero rating in a rank.
• At season end everyone drops two ranks and re-runs their placements.

All of these numbers come from the config file — you can make your ladder faster or slower without touching code.

The full ladder and a worked example →

9. Bots

The bots exist because day one is the hardest day a new server has. They are not target dummies: they buy, rotate, plant, defuse, trade and hold angles, and they fill a short queue then step aside as real players arrive.

/bot add <count>            # add bots to your current game
/bot remove <count>
/bot skill <profile>        # ten profiles, beginner to tournament
/bot list
/bot metrics                # what they actually did

Bots also test your changes: one command runs a full bot match and prints the statistics for it — round length, how rounds ended, how long players waited between fights. Tuning a mode from those numbers is far more reliable than playing it once and forming an impression.

10. Arenas

The setup ships one fully configured competitive arena, Split, with its spawns, bomb sites and pre-computed bot navigation, plus a furnished lobby and a training range. All eight modes run on it.

Adding your own arena means registering its world, its spawns and its sites in arenas.yml and ffa-spawns.yml, then letting the bots compute a navigation grid on first load. The process is documented in the archive.

11. Making it yours

# back up first, then rename everything in one pass
./scripts/backup.sh
./scripts/rebrand.sh --name "YourServer" --short "YS" --apply
./scripts/validate-setup.sh

The rebranding script renames the product across the plugin, the configuration, the messages and the pack. The generators for the 261 sounds and 332 textures ship with the product too, so you can regenerate the art in your own direction rather than living with ours.

12. Configuration files

13. Troubleshooting

A setting seems to do nothing

Check you edited the existing block rather than adding a second one. YAML keeps the last of two identical top-level keys, so a duplicate added above is ignored silently.

The server will not start

storage.fail-on-unavailable: true makes the server refuse to start when the database is unreachable. That refusal is deliberate — it protects you from running and losing writes. Check the credentials, or switch to sqlite to rule the database out entirely.

An arena is not offered

An arena needs three things: its world folder present in the server root, an entry in arenas.yml, and spawns. Missing any one of them means it will not appear. The startup log names every arena world it loads.

Weapons look like ordinary items

The custom models come from the resource pack. Check that resource-pack and resource-pack-sha1 in server.properties point at the pack you are actually serving — a stale checksum makes clients refuse it silently.

Still stuck

Run validate-setup and send us its output on Discord. It is designed to say what is wrong rather than that something is.

14. Licensing

The archive contains a licence register naming the origin of everything inside it, including the two third-party fonts in the resource pack and their notices. The code, the models, the sounds and the textures were made for this product.

Content we cannot establish clear commercial rights to is not shipped. That is why the setup includes one arena rather than several: we would rather remove content than sell it on a footing we cannot defend, and rather tell you that plainly than let you find out later.

Reselling the setup itself, rebranded or otherwise, is covered by the licence file in the archive. If your plan is something it does not cover, ask — the answer is often yes.