AjdnikovGamemodes Documentation

Overview

New in 1.3.2

• Automatic updates — new versions download by themselves after a licence check and load on the next restart.
• New settings appear on their own — new options are added to your config.yml with their comments, and your values stay.

What's new in 1.3

• Tournaments — free-for-all fights in protected arenas with preset or custom kits, a shrinking particle border, custom schematic maps and reward commands.
• Hunt and Target events — track players with a compass (and hide from trackers with the Hunter's Mask), or hunt a secret target in one shuffled loop.
• Public events page — every licensed server gets a live page on ajdnikov-dev.com with players, kill feed, winners and leaderboards, plus optional Discord posts.
• Item rescue — items from other plugins (StrengthSMP tokens, AnziLifesteal hearts) are no longer lost when game worlds reset.
• Turn gamemodes on or off with /ag gamemodes, and /events gui for one menu over tournaments, arenas, kits, hunt, target, the web page and Discord.

New in 1.2

• Achievement Speedrun — a seventh gamemode: race to complete the same random advancements.
• Chat games — scramble, math, trivia and quick-type rounds in chat that award points.
• MySQL / MariaDB storage for points, with an optional Redis add-on for instant cross-server leaderboards, and /ag storage migrate to move existing data.
• Queued, crash-safe point writes: database outages are retried, and unsent changes survive a shutdown in pending-points.yml.

Requirements

The server needs internet access on first start. It downloads the database libraries (HikariCP, Jedis and MySQL Connector/J) from Maven Central, checks the licence, and looks for updates. No world-management plugin is needed: worlds are created and managed internally, so Multiverse-Core is not required.

Installation & License

1. Put AjdnikovGamemodes-<version>.jar in plugins/. If you want PvP Arena or Hide & Seek, install FAWE as well.
2. Start the server once. This creates plugins/AjdnikovGamemodes/config.yml.
3. Paste your licence key into license.key and restart.
4. In the lobby, stand where players should return to and run /ag setlobby.
5. Optionally, switch storage to MySQL, or MySQL + Redis. See Storage.

On the first start with world-pool.enabled: true, the plugin generates the preloaded survival worlds in the background, which can take a few minutes. Survival gamemodes start instantly once the pool is ready.

AnziLock License

AjdnikovGamemodes is protected by AnziLock. Licence keys are issued through the Discord community — use /claim there, then set it in config.yml:

license:
  key: "YOUR_LICENSE_KEY_HERE"

If the licence is invalid, the plugin stops right after the check and none of the features load. The console says why.

Automatic Updates

Since 1.3.2, AjdnikovGamemodes updates itself. When a new version is released, it checks your licence again, downloads the new jar into plugins/update, and the server loads it on the next restart. The file is kept only if its size and checksum match the signed licence answer. Nothing changes while the server is running.

• Turn it off with auto-update: false in config.yml. Admins then get the "new version available" notice instead.
• Players with ajdnikovgamemodes.updates (ops by default) are told on join when a new version is waiting for a restart.
• New settings are added to config.yml on every start, with their comments. Your values stay, and the old file is kept as config.yml.bak. messages.yml fills in new messages by itself; kits.yml is never touched.
• Coming from 1.3.1 or older? Install 1.3.2 or newer by hand once. Every later version arrives by itself.

How the download is checked: AnziLock → Automatic Updates.

Support Dumps

Since 1.3.4, /ag dump makes a private link for support. The page shows AjdnikovGamemodes's own log next to the full server log, and your server's setup: software and version, uptime, TPS, RAM, disk, CPU, Java, worlds, every plugin, and config.yml with keys, passwords and webhooks blanked out. Only you see the link in chat: click it, or click [Copy], and send it to whoever helps you on Discord.

• /ag dump 6 covers only the last 6 hours. /ag dump local uploads nothing and saves the dump in plugins/AjdnikovGamemodes/dumps/ as a readable .txt and a .json.gz.
• On the page you can filter and search both logs, show only the lines about AjdnikovGamemodes (stack traces included), and save everything to your PC as .txt or .json. A saved .json opens again at license.ajdnikov-dev.com/dump after the link has expired.
• The link works for dump.link-hours (24 by default, at most 168). You can remove it sooner on your licence page under Dumps.
• IP addresses are replaced with x.x.x.x unless you set dump.hide-ips: false.
• Needs ajdnikovgamemodes.dump (ops by default).

dump:
  # Hours of AjdnikovGamemodes's log to keep on disk (dump-logs/) and put in a dump.
  log-hours: 48
  # How long the link works, in hours (at most 168).
  link-hours: 24
  # Replace IP addresses in the logs with x.x.x.x.
  hide-ips: true

What a dump contains and how long it is kept: AnziLock → Support Dumps.

Quick Start

/party create friends          # you become the leader (invite-only by default)
/party invite Steve            # Steve gets a clickable invite
/party settings                # optional: choose roles, PvP mode, difficulty...
/game start manhunt            # starts Manhunt with every online party member

When a game ends, players see a scoreboard of the points they earned. Their inventory, XP, health, effects, gamemode, location and respawn point are then restored to what they had before the game.

Gamemodes

Every game needs at least 2 players. Each one ends when its own win condition is met or when its time limit runs out.

Turning gamemodes off. /ag gamemodes opens a menu where you click a gamemode to enable or disable it (/ag gamemodes enable|disable <mode> and /ag gamemodes list work from the console). This sets games.<mode>.enabled in config.yml. A disabled mode can't be started with /game start, is hidden from tab completion and never comes up as a random event.

• Roles (Runner, Target, Seeker) are random unless the party leader picks a player in /party settings.
• Nether and End: survival games use the server's normal Nether and End. The plugin keeps track of which players and dragon belong to which game, so games running at the same time don't interfere.
• During a game, players are frozen and can't take damage while the countdown runs. Everyone gets their own scoreboard. Players who disconnect are removed from the game and their items are restored. If the server crashes mid-game, players get their items back the next time they join.

Parties

Games are started with a party. Every online member who is not already in a game joins the game.

Settings GUI

One page per gamemode:

• PvP Arena: cycle the mode (FFA / 2 Teams / 4 Teams) and assign players to teams.
• Manhunt / Man-Save / Hide & Seek: choose the Runner, Target or Seeker, or leave it on Random.
• Man-Save: edit the Protector kit. Click items in your inventory to copy them in, and click kit items to remove them.
• Speedrun VS: toggle the Easy, Medium and Hard item pools, or All. Easy is the default.
• Achievement Speedrun: toggle the advancement difficulties and cycle how many advancements to complete.

Disconnects: a member who disconnects stays in the party for 5 minutes, and the party is told so. If they reconnect within that time they are simply back in the party; otherwise they are removed.

Admins can put anyone into a party with /ag partyadd <player> <party>. If the party doesn't exist yet, it is created.

Points & Leaderboards

Players earn points for playing. The amounts come from the points: section of the config:

Games started as a random event multiply every award by random-events.points-multiplier.

• /ag stats [player] shows a player's total, and /ag top shows the top 10.
• Admins can change totals with /ag points <player> <add|set|remove> <amount>. Totals never go below 0.

Holographic leaderboards

Place an armor stand, look at it and run /ag setleaderboard. The stand becomes an invisible marker and a hologram with the top 3 players appears above it, refreshing every leaderboard.update-interval seconds. /ag removeleaderboard removes the nearest one (within 5 blocks), and /ag purgeleaderboards removes all of them. Breaking the anchor stand also removes its hologram.

Storage: YAML, MySQL, Redis

Choose one of three setups. Settings are read at start-up, so restart after changing them — /ag reload does not switch storage.

MySQL is always where points are stored. Redis doesn't store any points — it only tells the other servers about each change as it happens, so if Redis goes down nothing is lost and servers go back to refreshing from MySQL. Only points are stored in the backend: the lobby spawn, hologram positions, map spawns and crash-recovery inventory snapshots are per-server and stay in local files.

How writes work

• Reads (scoreboards, /ag stats, holograms) come from memory and never wait on the database.
• Every change updates memory at once and is written by a single background thread, in order. MySQL applies increments atomically (points = points + n), so two servers awarding points at the same time never overwrite each other.
• If the database goes down, changes are queued and retried every 5 seconds. The console logs the outage about once a minute and again when the connection is back. If the server stops while changes are still queued, they are saved to pending-points.yml and replayed on the next start.
• With MySQL, a player's points are loaded when they join, and the top 10 is re-read every storage.top-refresh-seconds.

MySQL / MariaDB

storage:
  type: MYSQL
  mysql:
    host: "db.example.com"
    port: 3306
    database: "ajdnikovgamemodes"   # must already exist
    username: "gamemodes"
    password: "change-me"
    table-prefix: "ag_"
    use-ssl: false

Create the database and a user; the plugin creates its table on first connect:

CREATE DATABASE ajdnikovgamemodes CHARACTER SET utf8mb4;
CREATE USER 'gamemodes'@'%' IDENTIFIED BY 'change-me';
GRANT SELECT, INSERT, UPDATE, CREATE, INDEX ON ajdnikovgamemodes.* TO 'gamemodes'@'%';

The data goes into one table, <table-prefix>players, with the columns uuid (primary key), name, points and updated_at. You can query it directly for websites or Discord bots, e.g. SELECT name, points FROM ag_players ORDER BY points DESC LIMIT 10;

Pool tuning lives under storage.mysql.pool, and extra JDBC driver options under storage.mysql.properties:

    properties:
      serverTimezone: "UTC"
      allowPublicKeyRetrieval: true   # MySQL 8 with caching_sha2_password and use-ssl: false

MySQL + Redis

With MySQL alone, a server only sees points earned on another server after its next top-list refresh or when the player rejoins. Add Redis to make those changes show up instantly:

storage:
  type: MYSQL
  mysql:
    # ... as above
redis:
  enabled: true
  host: "redis.example.com"
  port: 6379
  password: "change-me"
  key-prefix: "ag:"
  server-id: "minigames-1"   # optional, but makes logs easier to read

Each change is published on the Redis channel <key-prefix>sync, and every other server updates its scoreboards and holograms right away. Every server must point at the same MySQL database and the same Redis, and use the same key-prefix. Redis needs no persistence. Redis 6+ ACL users go in redis.username; use redis.ssl: true for TLS-only providers. redis.enabled has no effect with YAML storage, and the plugin warns if you try.

Moving your data

/ag storage migrate <from> <to> copies every player between yaml and mysql, in either direction. Players who already exist in the target are overwritten; other records are left alone. Typical switch from YAML to MySQL:

1. Fill in storage.mysql but keep type: YAML, then run /ag reload. The migration reads the connection details from the loaded config.
2. Run /ag storage migrate yaml mysql.
3. Set storage.type: MYSQL and restart.

/ag storage info shows the active backend, whether it is connected, how many writes are queued and whether Redis is connected.

Random Events

Every min-interval-minutes to max-interval-minutes, a random gamemode is announced to everyone with a clickable [CLICK TO JOIN] (or /game join). When the countdown (announcement-countdown-seconds) ends, the game starts with everyone who joined, as long as at least min-players-to-start joined. Event games award points-multiplier × points. Set discord-webhook-url to also post the announcement to Discord.

re is a short alias for randomevent.

Chat Games

Every min-interval-minutes to max-interval-minutes, when at least min-players players are online, a question is posted in chat. The first correct answer wins points.chat-game points. If nobody answers within answer-time-seconds, the answer is revealed.

Admin control: /ag chatgame start [type], stop, toggle and info (cg is a short alias). /ag reload applies new words, questions and intervals.

chat-games:
  trivia:
    questions:
      - question: "Which mob drops blaze rods?"
        answers: ["blaze", "blazes"]

Worlds & the World Pool

• Survival gamemodes (Death Swap, Manhunt, Man-Save, Speedrun VS, Achievement Speedrun) take a world from the preloaded pool (ag_preloaded_N). The chunks around spawn are generated ahead of time, so games start instantly. After the game, the world is restored from a clean backup and goes back into the pool.
• Schematic gamemodes (PvP Arena, Hide & Seek) use void worlds (ag_game_N, up to worlds.game-slots at once). They are created for the game and deleted afterwards.
• If no world is free, /game start says there are no free game slots.

Pool settings (world-pool:)

• max-preloaded-worlds sets how many survival games can run at once. Each world uses disk space.
• preload-radius plus preload-performance control how fast generation runs versus how much it lags the server. Use chunks-per-tick around 20 on weak hosts and 100+ on strong ones.
• auto-replenish generates missing worlds in the background, but only while fewer than player-threshold players are online.
• daily-regeneration replaces every pool world with a fresh seed at time (HH:mm). If kick-players-if-active is false, it skips the regeneration while games are running.

Setting world-pool.enabled: false generates survival worlds when a game starts instead, which is slower.

Map Setup (PvP Arena & Hide & Seek)

Both modes need FAWE and at least one map.

1. Put .schem files (or .litematic, if your FAWE version supports it) in plugins/AjdnikovGamemodes/PvPArenaMaps/ or plugins/AjdnikovGamemodes/HNSmaps/.
2. Run /setup setspawns <pvparena|hideandseek> <mapname>. You are put in creative mode in a temporary world with the map pasted in. Your inventory is saved and given back afterwards.
3. Use the tools in your hotbar:
   • Hide & Seek: click a block with the blaze rod to set the spawn point.
   • PvP Arena: use the blaze rod to set the FFA area (left-click corner 1, right-click corner 2), then the wool blocks to set the Red, Blue, Green and Yellow team spawns. Red and Blue are required; Green and Yellow are only needed for 4 Teams.
4. Run /setup confirm to save to <mapname>.yml next to the schematic, or /setup cancel to abort.

A random map is chosen each game. Maps are pasted at 0, 64, 0.

Tournaments

Free-for-all fights in a protected arena with a kit the admin picks. Last player standing wins. Several tournaments can run at once, one per arena (tournament.max-concurrent). Everything below can also be done in /tournament gui.

Admin setup

1. Create an arena. Run /tournament wand, left-click one corner block and right-click the opposite corner (or stand on each corner and use /tournament pos1 and /tournament pos2). Then run /tournament create <arena>. The region is protected straight away: no breaking, placing, explosions, liquid flow, fire spread, pistons or mob griefing (see arena-protection). WorldGuard isn't needed.
2. Add spawn points. Stand inside the arena and run /tournament setspawn <arena> once per spawn. You need at least 2. No spawn is used twice until every one has been used, so spawns are only shared when there are more players than spawns. Manage them with /tournament listspawns <arena> and /tournament removespawn <arena> <number|nearest>.
3. Pick or make a kit. Seven presets ship in kits.yml: dia_smp, smp (netherite), sword, mace (1.21+), axe, uhc and nethpot. To make your own, fill your inventory and run /tournament savekit <name>, or edit kits by drag and drop in /tournament gui → Kits (effects, icon and name are set there too).
4. Set the elimination lobby (optional). By default eliminated players go to the server lobby (/ag setlobby). /tournament setlobby uses your position instead; /tournament resetlobby goes back.
5. Start. /tournament start <arena> <kit> broadcasts a clickable join button and the events page link. Players join with /tournament join.
6. Ready. When enough players are in, /tournament ready starts the countdown (countdown-seconds, default 10). Players are frozen and can't hurt anyone until it reaches 0.

What happens to players

• Joining saves the player's inventory, armour, offhand, XP, health, hunger and effects to inventory_saves/<uuid>.yml before anything is cleared. They are teleported to a spawn and get the kit after kit-delay-seconds (everyone gets it at /tournament ready at the latest).
• Dying eliminates the player. Kit items never drop. They respawn at the elimination lobby with their own items back.
• Logging out counts as an elimination; their items are restored before they leave. /tournament leave before the fight just gives everything back; during the fight it counts as an elimination.
• The end comes when one player is left, or with /tournament stop. Everyone still in gets their items back and is sent to the lobby, the winner is announced and reward-commands run for them.
• A crash or restart never loses items: snapshots stay on disk and are restored the next time each player joins. On a normal shutdown or /reload, running tournaments are stopped and everyone is restored first.

Restrictions during a tournament

Participants can't open ender chests (by block or by command), can't use any command in tournament.restrictions.blocked-commands (namespaced forms such as essentials:ec are caught too), can't walk or pearl out of the arena, and can't drop items. Each rule has a toggle. Ender chests inside arenas are blocked for everyone. ajdnikovgamemodes.tournament.bypass ignores the command list.

Only the sides of the arena limit players: they can move from bedrock up to the build limit, so they can climb a mountain or go down a cave even if it is above or below the region you selected (tournament.restrictions.full-height; turn it off to make the region's height a hard limit). Arena protection covers the same height (arena-protection.full-height).

Mobs

While a tournament runs, no mobs spawn anywhere in its arena (tournament.mobs.block-spawning), and hostile mobs are removed at the start and every 5 seconds (tournament.mobs.remove-hostile; named mobs are kept). Other plugins and /summon can still spawn things.

Shrinking border

Set tournament.border.enabled: true (or /tournament gui → Shrinking border) for a border that closes in during the fight. It is a wall of particles, not the vanilla world border, so the arena can sit in a world where other people are playing; only tournament players see it (show-to-nearby-players shows it to everyone in that world). It starts at start-size blocks from the arena centre (0 = fit the arena), waits delay-seconds after FIGHT, then shrinks to end-size over shrink-seconds. Players outside take damage-per-second. shape is SQUARE or CIRCLE; particle, color, view-distance and spacing change how it looks (bigger spacing = less lag).

Custom maps

Put .schem or .litematic files in plugins/AjdnikovGamemodes/TournamentMaps/ (WorldEdit or FAWE needed). Then run /tournament importmap <file> [arena], or open /tournament gui → Custom maps and click a map. The map is pasted into its own void world (tournament.maps.world, no mobs, always day), each map spacing blocks apart, and becomes a normal arena around the pasted blocks (plus margin). You are teleported there; add spawns with /tournament setspawn <arena> and start it like any other arena.

• /tournament savemapspawns <arena> writes the spawns to <map>.yml next to the file, so importing the map again (here or on another server) loads them automatically. PvP Arena maps set up with /setup can be copied over with their .yml; their team spawns are used.
• /tournament resetmap <arena> pastes the map again. With tournament.maps.reset-after-tournament: true this happens after every tournament on it.
• /tournament maps lists the files and which arenas use them.

Hunt Event

/hunt start and /hunt end (both broadcast). While the hunt runs, any player can use /hunt <player> to track someone: they get a compass pointing at the target and the distance in their action bar, updated every second. There is a cooldown (hunt.cooldown-seconds). /hunt stop stops tracking. Tracking also stops when the event ends or the target logs out.

Hunter's Mask. A carved pumpkin crafted with the shaped recipe in hunt.mask.recipe (default: leather around an eye of ender and a carved pumpkin). Wearing it makes you impossible to track, including by someone who was already tracking you; they are told the trail is lost. Only a real mask works: it is recognised by hidden item data, not by its name, so renamed pumpkins do nothing. By default it can only be crafted while the hunt runs (hunt.mask.craft-only-during-event). It can't be placed or used in other recipes. Admins can hand one out with /hunt givemask [player].

Players with ajdnikovgamemodes.hunt.exempt can't be tracked. Players in a tournament can't be tracked unless hunt.allow-in-tournaments is on.

Target Event

/target start gives every online player with ajdnikovgamemodes.target.join a secret target (players in a tournament or minigame are left out unless target.exclude-busy-players is off). The targets form one shuffled loop, so nobody gets themselves. /bounty works as an alias.

• Killing your target runs target.kill-reward-commands, and you take over your victim's target.
• Only a kill by your hunter takes you out. Dying to mobs, falls or other players doesn't.
• If a player logs out they leave the loop, and whoever was hunting them gets their target.
• The last player left wins and target.winner-reward-commands run. With max-duration-minutes, the player with the most kills wins when time is up (a tie means no winner).
• /target info shows your target, your kills and how many players are left. /target end stops it with no winner.

Public Events Page

Every licensed server gets a public page on ajdnikov-dev.com/events showing its live and recent tournaments, hunts and targets: players, eliminations, kill feed, countdown, winners, history and wins/kills leaderboards. Players get the link with /events link; it is also added to start broadcasts and Discord posts. You'll find it, with a copy button, on your licence page at license.ajdnikov-dev.com.

• The page only shows player names, kills and results. It never shows coordinates (not even during a hunt), IPs or your licence key. The page address is a random id, not your key.
• Updates are sent in small batches in the background. If the site can't be reached, events keep working normally; the console shows one warning and updates are retried.
• Your licence comes with one page. Staff can allow more (for example one per server on a network). Each server picks its page with web-events.feed; servers using the same name share a page. On the licence page you can remove a page or give it a new link if the old one was shared somewhere it shouldn't be.
• Turn it off completely with web-events.enabled: false.

web-events:
  enabled: true
  feed: "main"              # servers with the same name share a page
  display-name: ""          # page title (empty = the page name)
  server-name: ""           # label on each event, for shared pages
  flush-interval-seconds: 3
  link-in-broadcasts:
    tournament: true
    hunt: true
    target: true

event-discord:
  webhook-url: ""           # posts starts, winners and results with the page link
  tournament: true
  hunt: true
  target: true

Item Rescue

Game worlds are deleted or reset after every game, and each player's game inventory is replaced by their saved one. Without help, items from other plugins that were picked up or dropped during a game would be lost. The item-rescue section (on by default) keeps them. Out of the box it covers StrengthSMP's Strength Tokens and AnziLifesteal's Heart and Revive Beacon items.

• An item dropped when a player dies belongs to the killer. If nobody picks it up, the killer gets it when the game ends (they are told so at the kill). After a natural death (lava, fall, mobs), the last player who hit the victim counts as the killer; with no attacker at all, the dead player gets it back.
• Items a player threw on the ground with Q go back to that player.
• Matching items in a player's inventory at the end are given back after their normal inventory is restored.
• Offline players get them when they next join (stored in rescued-items.yml).

item-rescue:
  enabled: true
  nbt-contains:              # all words of an entry must appear in the item's NBT
    - "paper strength"       # StrengthSMP tokens (not vanilla Strength potions)
  pdc-namespaces:            # data tags from these plugins
    - strengthsmp
    - anzilifesteal
  name-contains: []
  materials: []
  custom-model-data: []
  keep-from-inventory: true
  auto-detect-death-drops: true   # custom items another plugin adds on death
  debug: false

If an item is still lost, hold one and run /ag itemrescue check to see whether it matches and to see its NBT. Add a few of its words to nbt-contains, then /ag reload. debug: true logs every death drop and how it was handled. Items lying in the shared Nether/End are not touched, and the server must stop normally (not crash) for them to be kept.

AnziLifesteal: while a player is in a game, AjdnikovGamemodes marks them with the ajdnikovgamemodes_in_game metadata. An up-to-date AnziLifesteal reads it (minigame-protection, on by default), so no hearts are lost or stolen in games, including deaths in the shared Nether/End.

Commands

Players (ajdnikovgamemodes.play)

Game hosts (ajdnikovgamemodes.game)

Admins (ajdnikovgamemodes.admin)

Tournament admins (ajdnikovgamemodes.tournament.admin)

Event admins

Permissions

Game Settings

Every gamemode under games: has a time-limit in seconds. If it's missing, games.global.time-limit (1800) is used.

Other sections

Player-facing text for tournaments, hunt, target, arenas and kits is in messages.yml (& colour codes and hex colours as &#RRGGBB; set a message to "" to turn it off). Kits are in kits.yml. Settings changed in a GUI are saved to config.yml straight away.

Files & Update Checker

All of these are in plugins/AjdnikovGamemodes/:

After an update, config.yml.bak holds your config as it was before the new settings were added.

Update checker

With automatic updates on (the default), new versions are downloaded for you and players with ajdnikovgamemodes.updates are told when one is waiting for a restart.

With auto-update: false, the plugin only checks for a newer release on start-up, asynchronously, so it never delays the server. If the running version is outdated, the console says so, and players with ajdnikovgamemodes.admin get a clickable download link when they join.

Full config.yml

The default configuration shipped with 1.3.2. Every option carries a comment.

# ========================================
#      AjdnikovGamemodes Configuration
# ========================================

license:
  # Insert the license key you received via Discord here (see /claim).
  key: ""

# Download new versions of AjdnikovGamemodes automatically when they are released.
# They are checked against your license and load on the next restart.
# Players with ajdnikovgamemodes.updates (ops by default) are told when one is waiting.
auto-update: true

# /ag dump makes a private link with the plugin's log, the full server log and the server's setup
# to share with support. "dump local" only saves it in plugins/AjdnikovGamemodes/dumps/.
dump:
  # Hours of the plugin's log to keep on disk (dump-logs/) and put in a dump.
  log-hours: 48
  # How long the link works, in hours (at most 168).
  link-hours: 24
  # Replace IP addresses in the logs with x.x.x.x.
  hide-ips: true

# ========================================
#            Storage Settings
# ========================================
# Where player points are stored. Changes need a server restart (not /ag reload).
#   YAML  - plugins/AjdnikovGamemodes/playerdata.yml (single server, no setup)
#   MYSQL - MySQL or MariaDB; share points between several servers.
#           Optionally add Redis (redis.enabled below) for instant cross-server updates.
# Copy existing data with: /ag storage migrate <from> <to>   e.g. /ag storage migrate yaml mysql
storage:
  type: YAML
  # MYSQL: how often (seconds) the shared top list is re-read from the database.
  # With Redis enabled this is only a safety net; changes arrive instantly.
  top-refresh-seconds: 30

  mysql:
    host: "localhost"
    port: 3306
    database: "ajdnikovgamemodes"
    username: "root"
    password: ""
    # Table name becomes <table-prefix>players. Letters, digits and _ only.
    table-prefix: "ag_"
    use-ssl: false
    pool:
      maximum-pool-size: 4
      minimum-idle: 1
      connection-timeout-ms: 5000
      max-lifetime-ms: 1800000
    # Extra JDBC driver properties, e.g. serverTimezone: "UTC" or allowPublicKeyRetrieval: true
    properties: {}

# ========================================
#             Redis Settings
# ========================================
# Optional add-on for storage.type MYSQL (MySQL + Redis). MySQL stays the only place points
# are stored; Redis pub/sub tells every other server about each change, so leaderboards and
# scoreboards update instantly across the network. Has no effect with YAML storage.
redis:
  enabled: false
  host: "localhost"
  port: 6379
  # Leave username empty unless you use Redis 6+ ACL users.
  username: ""
  password: ""
  database: 0
  ssl: false
  timeout-ms: 2000
  pool-size: 8
  # The sync channel is <key-prefix>sync. Servers sharing a database must use the same prefix.
  key-prefix: "ag:"
  # Name of this server in sync messages. Empty = random on every start.
  server-id: ""

# Proxy settings for BungeeCord/Velocity
proxy:
  enabled: false
  lobby-server: "lobby"

# Lobby configuration
lobby:
  world: "world"
  spawn:
    x: 0.0
    y: 64.0
    z: 0.0
    yaw: 0.0
    pitch: 0.0

# World settings (for dynamic game world slots — PvP Arena, HnS, etc.)
worlds:
  game-slots: 3
  prefix: "ag_game_"

# ========================================
#     Preloaded World Pool Settings
# ========================================
# The world pool pre-generates survival worlds so gamemodes like Death Swap,
# Manhunt, Man-Save, Speedrun VS and Achievement Speedrun can start instantly
# without waiting for world generation. After each game, the used
# world is restored to its pristine state from a backup.

world-pool:
  # Whether to use the preloaded world pool system.
  # If false, worlds are generated dynamically on game start (old behavior).
  enabled: true

  # Prefix for preloaded world folder names (e.g. ag_preloaded_1, ag_preloaded_2)
  prefix: "ag_preloaded_"

  # Total number of survival worlds to keep preloaded and ready.
  # More worlds = more disk space, but supports more concurrent games.
  max-preloaded-worlds: 3

  # Radius (in blocks) around world spawn to pre-generate chunks.
  # Higher values = longer initial generation but smoother gameplay.
  # Set to 0 to disable chunk preloading.
  # 500 blocks = ~31 chunk radius = ~3000 chunks per world.
  preload-radius: 500

  # Fine-tune how the chunk preloading behaves.
  preload-performance:
    # How many chunks to generate per server tick.
    # Higher = faster preloading, but more lag during generation.
    # Lower = slower preloading, but smoother server performance.
    # Recommended: 20 for weak servers, 50 for average, 100+ for powerful hardware.
    chunks-per-tick: 50

    # How many ticks to wait between each batch of chunks.
    # 1 = process every tick (fastest), 2 = every other tick, etc.
    # Increase this if you notice TPS drops during world generation.
    ticks-between-batches: 1

    # How often (in chunks) to log progress to the console.
    # Set to 0 to disable progress logging entirely.
    # Example: 500 means a log message every 500 chunks processed.
    log-interval: 500

    # Whether to unload chunks from memory immediately after generating them.
    # true = saves RAM during generation (recommended for large radii).
    # false = keeps chunks loaded (faster if players join the world soon after).
    unload-after-generation: true

  # Auto-replenishment: generates new worlds when available count drops low.
  auto-replenish:
    enabled: true
    # Only generate new worlds when the server has fewer than this many players online.
    # This prevents lag spikes during busy periods.
    player-threshold: 10
    # If the number of available (unclaimed) worlds drops below this number,
    # trigger background generation of a new world.
    min-available: 1
    # How often (in seconds) the plugin checks if replenishment is needed.
    check-interval-seconds: 30

  # Daily regeneration: wipes ALL preloaded worlds and regenerates them
  # with fresh random seeds at a specific time each day.
  daily-regeneration:
    enabled: false
    # Time of day to perform the regeneration (24-hour format, HH:mm).
    time: "03:00"
    # If true, any active games on preloaded worlds will be force-stopped
    # before regeneration. If false, regeneration is skipped if games are active.
    kick-players-if-active: false

# ========================================
#       Random Events Settings
# ========================================
# The random events system triggers a server-wide random event (gamemode)
# where players click a chat message to join the queue.
# Games started as a random event award multiplied/greater points.
random-events:
  # Whether scheduled automatic random events are enabled.
  enabled: true

  # Time range (in minutes) between automatic events.
  min-interval-minutes: 30
  max-interval-minutes: 60

  # Countdown duration (in seconds) during the click-to-join announcement.
  announcement-countdown-seconds: 60

  # Points multiplier applied to games started as random events (e.g. 2.0 = double points).
  points-multiplier: 2.0

  # Minimum number of players in queue required to start the event game.
  min-players-to-start: 2

  # Optional Discord webhook URL to notify when a random event starts.
  discord-webhook-url: ""

# ========================================
#          Chat Games Settings
# ========================================
# Every few minutes a question is posted in chat. The first player to type the
# correct answer wins points (points.chat-game). Admins: /ag chatgame <start|stop|toggle|info>
chat-games:
  enabled: true
  min-interval-minutes: 5
  max-interval-minutes: 10
  # Seconds players have to answer before the answer is revealed.
  answer-time-seconds: 60
  # Only start automatic rounds when at least this many players are online.
  min-players: 2
  # Which kinds of rounds can be picked: scramble, math, trivia, quicktype
  types: [scramble, math, trivia, quicktype]

  scramble:
    # Words to unscramble (answers are not case-sensitive).
    words: [creeper, diamond, obsidian, enchantment, netherite, redstone, villager, skeleton,
            enderman, beacon, crafting, furnace, pickaxe, elytra, trident, blaze, stronghold,
            portal, shulker, piglin, axolotl, emerald, lantern, anvil, bastion, fortress,
            respawn, strider, warden, amethyst]

  math:
    # Largest number used in the problems.
    max-number: 50

  quicktype:
    # Length of the random code to type (case-sensitive), 4-20.
    length: 8

  trivia:
    # "answers" can hold several accepted answers. Matching ignores case and punctuation.
    # The first answer is shown when nobody gets it. Questions support & colour codes.
    questions:
      - question: "How many blocks of obsidian are needed for a minimal Nether portal?"
        answers: ["10", "ten"]
      - question: "Which mob drops blaze rods?"
        answers: ["blaze", "blazes"]
      - question: "What block is the body of a Wither built from? (4 needed)"
        answers: ["soul sand", "soul soil", "soulsand"]
      - question: "What item do you give a piglin to barter?"
        answers: ["gold", "gold ingot", "gold ingots"]
      - question: "How many eyes of ender does it take to fill an End portal frame?"
        answers: ["12", "twelve"]
      - question: "Which ore is only found in the Nether and makes netherite?"
        answers: ["ancient debris"]
      - question: "What mob explodes and hisses before it does?"
        answers: ["creeper", "creepers"]
      - question: "Which tool is needed to collect honeycomb from a bee nest?"
        answers: ["shears"]
      - question: "What do you use to tame a wolf?"
        answers: ["bone", "bones"]
      - question: "What is the maximum level of Sharpness from an enchanting table?"
        answers: ["4", "iv", "four", "sharpness 4", "sharpness iv"]

# Points awarded for actions
points:
  win: 10
  kill: 2
  survive: 5
  participation: 1
  advancement: 1    # Achievement Speedrun: per target advancement completed
  chat-game: 3      # Chat games: first correct answer

# Leaderboard settings
leaderboard:
  update-interval: 60

# Item rescue: keeps items from other plugins (StrengthSMP tokens and AnziLifesteal hearts by default)
# when a game ends. Game worlds are deleted or reset after a game and each player's game
# inventory is replaced by their saved one, so without this those items would be lost.
# - Items dropped when a player dies belong to the killer. If nobody picks them up, the killer
#   gets them when the game ends. After a natural death (lava, fall, mobs) the last player who
#   hit them counts as the killer; with no attacker at all, the dead player gets them back.
# - Items a player threw on the ground with Q go back to that player.
# - Items in a player's inventory at the end of the game are given back after the restore.
# - Players who are offline get them the next time they join (stored in rescued-items.yml).
# Hold an item and run /ag itemrescue check to see if it matches and to see its NBT.
item-rescue:
  enabled: true
  # Keep items whose NBT data (material id, name, lore, custom data...) contains ALL words of
  # an entry. Case and small-caps letters are ignored. "paper strength" = StrengthSMP tokens.
  nbt-contains:
    - "paper strength"
  # Keep items carrying data tags from these plugins (plugin name in lower case)
  pdc-namespaces:
    - strengthsmp     # StrengthSMP: Strength Tokens
    - anzilifesteal   # AnziLifesteal: Heart and Revive Beacon items
  # Keep items whose name contains any of these (colours and case ignored)
  name-contains: []
  # Keep every item of these materials (rarely needed)
  materials: []
  # Keep items with these custom model data values
  custom-model-data: []
  # Also keep matching items a player is holding when the game ends
  keep-from-inventory: true
  # Also keep custom items that another plugin adds when a player dies (anything with a
  # custom name, lore or data that wasn't in their inventory), even if not listed above
  auto-detect-death-drops: true
  # Log every death drop and how it was handled (for finding out why an item wasn't kept)
  debug: false

# Game-specific settings
# Every gamemode has "enabled". Turn modes on/off in game with /ag gamemodes.
games:
  global:
    time-limit: 1800  # 30 minutes default fallback for all games
  deathswap:
    enabled: true     # false = can't be started and never picked for random events
    time-limit: 1800  # 30 minutes
    min-swap-time: 120
    max-swap-time: 300
    warning-time: 5
  manhunt:
    enabled: true     # false = can't be started and never picked for random events
    time-limit: 3600  # 60 minutes
    runner-head-start: 30
    compass-cooldown: 30  # Seconds between manual compass clicks
  hideandseek:
    enabled: true     # false = can't be started and never picked for random events
    time-limit: 600   # 10 minutes (hide + seek combined)
    hide-time: 60
    seek-time: 300
    hider-glow-interval: 30  # Seconds between the 1-second glow that reveals hiders
  mansave:
    enabled: true     # false = can't be started and never picked for random events
    time-limit: 1200  # 20 minutes
    survive-time: 600
  pvparena:
    enabled: true     # false = can't be started and never picked for random events
    time-limit: 300   # 5 minutes
    max-time: 300
  speedrunvs:
    enabled: true     # false = can't be started and never picked for random events
    time-limit: 3600  # 60 minutes
  achievementspeedrun:
    enabled: true     # false = can't be started and never picked for random events
    time-limit: 2400  # 40 minutes — most completed advancements wins when time runs out
    target-count: 5   # Advancements to race for (1-10). Party leaders can change this in /party settings.
    allow-pvp: false  # Whether racers can hurt each other
    # Optional: replace the built-in advancement lists per difficulty.
    # Use vanilla keys such as "story/mine_stone" or "minecraft:story/mine_stone".
    # pool:
    #   easy: ["story/mine_stone", "story/smelt_iron", "husbandry/plant_seed"]
    #   medium: ["story/mine_diamond", "story/enter_the_nether"]
    #   hard: ["nether/obtain_blaze_rod", "story/enter_the_end"]

# ========================================
#             Tournaments
# ========================================
# Free-for-all fights in protected arenas with a kit chosen by the admin.
# Setup: /tournament wand -> select 2 corners -> /tournament create <arena>
#        -> /tournament setspawn <arena> (2 or more) -> /tournament start <arena> <kit>
#        -> players /tournament join -> /tournament ready
# Everything here can also be changed in game with /tournament gui.
tournament:
  # Most players in one tournament. Arenas can override this (/tournament setmax <arena> <n>).
  max-players: 16
  # How many tournaments can run at the same time (one per arena).
  max-concurrent: 3
  # Players needed before /tournament ready works.
  min-players: 2
  # Seconds after joining before the kit is given (everyone gets it at /tournament ready anyway).
  kit-delay-seconds: 3
  # Length of the countdown started by /tournament ready. Players are frozen and can't attack.
  countdown-seconds: 10
  # Bukkit sound names (empty = no sound).
  countdown-sound: "BLOCK_NOTE_BLOCK_PLING"
  fight-sound: "ENTITY_ENDER_DRAGON_GROWL"
  # Skip the death screen for eliminated players.
  auto-respawn: true
  # Item used as the arena selection wand (left-click = corner 1, right-click = corner 2).
  wand-material: "GOLDEN_AXE"
  # Where eliminated players go. use-server-lobby: true = the lobby from /ag setlobby.
  # /tournament setlobby stores your position here and switches use-server-lobby off.
  lobby:
    use-server-lobby: true
    world: "world"
    x: 0.0
    y: 64.0
    z: 0.0
    yaw: 0.0
    pitch: 0.0
  # Mobs inside arenas while a tournament runs there (whole height of the arena).
  mobs:
    # Stop mobs spawning (other plugins and /summon still can).
    block-spawning: true
    # Remove hostile mobs at the start and every 5 seconds (named mobs are kept).
    remove-hostile: true
  # Shrinking border made of particles (not the vanilla world border, so the world can be shared).
  # Only tournament players see it. Players outside it take damage.
  border:
    enabled: false
    # SQUARE or CIRCLE, centred on the arena.
    shape: SQUARE
    # Distance from the centre to the wall at the start. 0 = fit the arena.
    start-size: 0
    # Distance it shrinks down to.
    end-size: 10
    # Seconds after FIGHT before it starts moving, then how long it takes to reach end-size.
    delay-seconds: 60
    shrink-seconds: 300
    # Damage per second outside the border (2 = one heart).
    damage-per-second: 2.0
    # Bukkit particle name. DUST (REDSTONE on older servers) uses the colour below.
    particle: DUST
    color: "#FF3030"
    particle-size: 1.5
    # How far away the wall is drawn, and the gap between particles (bigger = less lag).
    view-distance: 24
    spacing: 1.0
    # Also show the wall to everyone else in the world.
    show-to-nearby-players: false
  # Custom maps: put .schem/.litematic files in plugins/AjdnikovGamemodes/TournamentMaps/ and run
  # /tournament importmap <file> [arena] (or /tournament gui -> Custom maps). The map is pasted into
  # its own void world and becomes a normal arena; add spawns with /tournament setspawn.
  # A <map>.yml next to the file can hold spawns (/tournament savemapspawns writes it).
  maps:
    world: "ag_tournament_maps"
    # Blocks between maps in that world.
    spacing: 1000
    # Y level the map's origin is pasted at.
    paste-y: 64
    # Extra blocks around the map that count as part of the arena.
    margin: 0
    # Paste the map again after every tournament on it (undoes any changes).
    reset-after-tournament: false
  # Console commands run for the winner. Placeholders: %player% %arena% %kit%
  reward-commands:
    - "give %player% diamond 5"
  restrictions:
    # Block opening ender chests (inside arenas, and anywhere for participants).
    block-ender-chests: true
    # Participants can't drop items.
    block-item-drop: true
    # Ender pearls and chorus fruit can't take participants out of the arena.
    block-pearls-leaving-arena: true
    # Participants can't walk out of the arena region.
    keep-players-in-arena: true
    # true = only the arena's sides limit players; they can go from bedrock to the build limit
    # (climb mountains, go into caves). false = the region's height is a hard ceiling and floor.
    full-height: true
    # Commands participants can't use (without "/"). "essentials:ec" style forms are caught too.
    # Players with ajdnikovgamemodes.tournament.bypass ignore this list.
    blocked-commands:
      - ec
      - echest
      - enderchest
      - eechest
      - eenderchest
      - endersee
      - enderview
      - home
      - homes
      - sethome
      - spawn
      - tpa
      - tpahere
      - tpaccept
      - tpyes
      - tpo
      - tp
      - tphere
      - back
      - warp
      - warps
      - rtp
      - wild
      - kit
      - kits
      - fly
      - god
      - heal
      - feed
      - repair
      - fix
      - hat
      - workbench
      - wb
      - craft
      - anvil
      - invsee
      - trash
      - disposal
      - suicide

# What is blocked inside every arena region (no WorldGuard needed).
# Admins with ajdnikovgamemodes.arena.bypass can build in creative mode when not playing.
arena-protection:
  block-break: true
  block-place: true
  explosions: true
  liquid-flow: true
  fire-spread: true
  pistons: true
  mob-griefing: true
  block-decay: true
  # Protect the arena from bedrock to the build limit, not only the selected height.
  full-height: true

# ========================================
#               Hunt Event
# ========================================
# /hunt start and /hunt end (admins). While it runs, players use /hunt <player> to get a
# compass pointing at the target and the distance in their action bar.
# A player wearing the Hunter's Mask can't be tracked. Also editable with /hunt gui.
hunt:
  # Seconds between /hunt uses (admins skip it).
  cooldown-seconds: 30
  # Ticks between compass/action bar updates (20 = once a second).
  update-interval-ticks: 20
  # Give hunters a tracking compass (otherwise only the action bar distance).
  give-compass: true
  # Tell players when someone starts tracking them.
  notify-target: false
  # Allow tracking players who are in a tournament (or tracking while in one).
  allow-in-tournaments: false
  mask:
    name: "&6&lHunter's Mask"
    lore:
      - "&7Wear it on your head and"
      - "&7no one can track you with /hunt."
    # true = only craftable while the hunt runs; false = always craftable.
    craft-only-during-event: true
    recipe:
      enabled: true
      # Up to 3 rows of up to 3 symbols; a space is an empty slot.
      shape:
        - "LEL"
        - "LPL"
        - " L "
      ingredients:
        L: LEATHER
        E: ENDER_EYE
        P: CARVED_PUMPKIN

# ========================================
#              Target Event
# ========================================
# /target start gives every online player with ajdnikovgamemodes.target.join a secret target.
# Kill your target and you inherit theirs. Only a kill by your hunter eliminates you.
# The last player left wins. Also editable with /target gui.
target:
  min-players: 2
  # Leave out players who are in a tournament or a minigame when the event starts.
  exclude-busy-players: true
  # Broadcast every successful hit.
  announce-kills: true
  # 0 = no limit. When time runs out, the player with the most kills wins (a tie = no winner).
  max-duration-minutes: 0
  # Console commands for each target kill. Placeholders: %killer% %victim%
  kill-reward-commands:
    - "give %killer% gold_ingot 3"
  # Console commands for the winner. Placeholder: %player%
  winner-reward-commands:
    - "give %player% diamond 10"

# ========================================
#          Public Events Web Page
# ========================================
# Tournaments, hunts and targets are shown live on a public page on ajdnikov-dev.com.
# The page only shows player names, kills and statuses: never coordinates, IPs or your key.
# Updates are sent in the background; the plugin works normally if the site is down.
# Get the link with /events link, or from your license page on license.ajdnikov-dev.com.
web-events:
  enabled: true
  # Your license can have several pages (the limit is set by staff). Servers that use the same
  # name share one page. Letters, digits, - and _.
  feed: "main"
  # Title shown at the top of the page (empty = the page name).
  display-name: ""
  # Label shown on each event, useful when several servers share a page.
  server-name: ""
  # Seconds between batched updates.
  flush-interval-seconds: 3
  # Add a clickable "watch live" link to these start broadcasts.
  link-in-broadcasts:
    tournament: true
    hunt: true
    target: true
  # Where the page and the API live. Leave these unless told otherwise.
  page-url: "https://ajdnikov-dev.com/events/"
  api-url: "https://license.ajdnikov-dev.com"

# Optional Discord webhook for event starts, winners and results (with the page link).
event-discord:
  webhook-url: ""
  tournament: true
  hunt: true
  target: true

Troubleshooting

Q: "No available game slots!"

A: Every pool world or void slot is in use, or the pool is still generating. Raise world-pool.max-preloaded-worlds or worlds.game-slots, or wait.

Q: "Could not connect to MySQL" at start-up

A: Check the host, port, database name and credentials, and that the database already exists. With MySQL 8 and use-ssl: false, add allowPublicKeyRetrieval: true under storage.mysql.properties. Points keep working while it retries: they are queued in memory and written once the connection is back.

Q: ClassNotFoundException for Hikari or Jedis

A: The server couldn't download the libraries on first start. Allow outbound access to repo.maven.apache.org, or start the server once on a machine that has access.

Q: Points differ between servers

A: Every server must use storage.type: MYSQL with the same database and table-prefix, and must have been restarted after the change. Without Redis, other servers catch up within top-refresh-seconds. Set redis.enabled: true (same Redis and key-prefix everywhere) for instant updates.

Q: I changed storage in config.yml and nothing happened

A: Storage settings are only read at start-up. Restart the server.

Q: Players lost their items after a crash

A: Their snapshot is restored automatically the next time they join. Snapshots are in inventory_saves/.

Q: Strength Tokens or Lifesteal hearts disappear when a game ends

A: Make sure item-rescue.enabled is on, then hold the item and run /ag itemrescue check. If it doesn't match, add a few words of its NBT to item-rescue.nbt-contains and /ag reload. See Item Rescue.

Q: Players lose hearts in minigames (AnziLifesteal)

A: Update AnziLifesteal and keep its minigame-protection on. It reads the ajdnikovgamemodes_in_game marker this plugin sets during games.

Q: "Could not reach the events site" in the console

A: The events page couldn't be updated. Tournaments, hunts and targets keep working, and updates are retried quietly. "The events site refused the update" means the key is wrong, the licence isn't for this plugin, or the licence has used all its event pages (web-events.feed); it retries every 5 minutes.

Q: A tournament won't start: "needs at least 2 spawn points"

A: Add spawns with /tournament setspawn <arena> while standing inside the arena.

Q: PvP Arena / Hide & Seek don't start

A: Install FAWE, add at least one map and set it up with /setup setspawns.

Q: Need more help?

A: Join the Discord server for support and bug reports.