EventPractice Documentation

license-key: "YOUR-KEY"
color-format: "legacy" # Options: "legacy" (& codes) or "minimessage" (<color> tags)

1. Go to Arenasworld. Teleport to the Arenasworld world from console or with a teleport plugin. If the world does not exist yet, the plugin creates it as a void world during the first arena operation; still make sure the world exists before building.
2. Build the arena. Create the floor, decoration and spawn platforms inside this world. You will stand near the center of the template.
3. Stand at the center and save:

   /arena save crystal 60

   This command takes your location as the center and saves the whole region (60-block radius on x/z, full height from Y -64 to 256) as arenas/crystal.schem. The category center is set at the same time, and the category is auto-added to every match mode that has no categories.

4. Set the duel spawn points. Spawn locations on a cloned arena are computed as offsets from the template's recorded positions, so record them from within the template itself:

   /arena setspawn1 crystal   # run while standing on player 1's spot
   /arena setspawn2 crystal   # run while standing on player 2's spot

5. (Optional) Add breakable blocks. Hold the block item in your hand (e.g. OBSIDIAN) and run:

   /arena addblock crystal

   The block type is appended to the breakable-blocks list in arenas.yml; only listed blocks can be broken during matches.

6. (Optional) Assign a menu icon. Hold the icon item and run:

   /arena seticon crystal

7. Pregenerate the pool. Keep spare arenas ready so the first queue match starts instantly during busy hours:

   /arena pregen crystal 3

   The command sends a progress message every second (percentage, completed/total, elapsed time) and a completion message once all pastes finish.

8. Verify:

   /arena list

   The output shows category, arena id, state (e.g. GENERATING/AVAILABLE) and owner info.

1. Register a template per PvP type with separate categories: /arena save crystal 60, /arena save netheritepot 40, /arena save builduhc 80 etc.
2. Write the categories into each mode's arena-category list in match-modes.yml:

   modes:
     crystalpvp:
       arena-category:
         - "crystal"
     netheritepot:
       arena-category:
         - "netheritepot"
     builduhc:
       arena-category:
         - "builduhc"
         - "generic"

3. Reload the plugin: /eventpractice reload.
4. Start a match from the mode's queue menu and confirm the arena comes from the correct pool.

1. To remove a category completely:

   /arena remove crystal

   This deletes the arenas/crystal.schem file, the category record in arenas.yml and the persisted pooled instance records together.
2. To only update a template, do not use remove; fix the build and run /arena save crystal 60 again with the same category name. The schematic file is overwritten.
3. Re-apply center/spawn points with the same commands afterwards.

All arena pastes happen in the config.yml → arenas-world world (default Arenasworld). Your lobby and survival worlds stay clean of match blocks.

# config.yml
arenas-world: "Arenasworld"

You do not need to edit arenas.yml by hand; every arena command keeps it up to date. The structure looks roughly like this:

arenas:
  crystal:
    size: 60
    center: {world: Arenasworld, x: 0, y: 64, z: 0, yaw: 0, pitch: 0}
    spawn1: {...}
    spawn2: {...}
    icon: {...}
    breakable-blocks:
      - OBSIDIAN
      - END_STONE
instances:
  crystal: [...]

1. Fill your own inventory with the content you want to register (armor included, with the hotbar arrangement — this layout is used when a player has no personal kit).
2. Save the kit:

   /kitadmin save CrystalPvP

   The inventory is written to kits.yml instantly and you receive the "Kit has been saved successfully." message.

3. Check the registered kits:

   /kitadmin list

4. Test the kit by applying it to yourself:

   /kitadmin load CrystalPvP

5. Bind the kit to a match mode. Write the exact kit name into the mode's kit field in match-modes.yml:

   modes:
     crystalpvp:
       kit: "CrystalPvP"

6. Run /eventpractice reload, start a short match from the queue and confirm the kit arrives correctly.

The Kitroom is the editor area where players customize the item layout of their match kit. kitroom.yml defines categories; each category carries a slot-based item list like a chest GUI page. The default file ships with example crystal-pvp, potions and misc categories.

1. Edit via GUI (recommended): Hold the item you want to register, then

   /kitroom edit crystal-pvp

   to enter editor mode (permission: eventpractice.kitroom.edit). Slots you place items on are written into kitroom.yml live.
2. If you prefer manual editing, the kitroom.yml structure is slot → item:

   categories:
     crystal-pvp:
       '0':
         material: NETHERITE_HELMET
         amount: 1
         enchantments:
           PROTECTION: 4
           UNBREAKING: 3
           MENDING: 1
           RESPIRATION: 3
           AQUA_AFFINITY: 1
         unbreakable: false
         durability: 407
       '2':
         material: OBSIDIAN
         amount: 64
       '22':
         material: TIPPED_ARROW
         amount: 64
         potion-effects:
           slow_falling:
             duration: 4800
             amplifier: 0
   potions:   # quick potion rows
     '0':
       material: SPLASH_POTION
       potion-effects:
         instant_health:
           duration: 1
           amplifier: 1
   misc:      # general item pool
     '0':
       material: DIAMOND_HELMET
       amount: 1

3. Run /eventpractice reload after changes.

A personal kit lets a player customize hotbar and inventory placement without changing the admin kit's content: which slot potions go to, where the sword sits, pearl/gapple positions are saved per player.

1. The player opens the personal kit menu with /kit or /k (permission: eventpractice.kit.use).
2. They pick the kit and rearrange the layout from the menu; the layout is stored permanently in the database (personal-kits storage).
3. When a match starts, the player's personal layout is applied if they have one; otherwise the admin kit's default layout is given.

1. Arrange the inventory and register it with /kitadmin save BuildUHC.
2. Set the menu icon with /kitadmin seticon BuildUHC using a held item.
3. Add the mode to match-modes.yml (using the template in the Match Modes & Queue section) and set kit: "BuildUHC".
4. If the mode is build-enabled, register an arena category (/arena save builduhc 80) and add it to the arena-category list.
5. If players should see mode-specific items in the Kitroom, add a category in kitroom.yml.
6. Reload, enter a test match from the queue, and verify the kit and arena pairing.

1. Open match-modes.yml, copy an existing template under modes: and add a new key (key = mode id, lowercase recommended):

   modes:
     nodebuff:
       display-name: "&9NoDebuff"
       enabled: true
       kit: "NoDebuff"
       arena-category:
         - "nodebuff"
       enderpearl-cooldown: 10
       damage-multiplier: 100
       world-border:
         radius: 50
         damage: 2
       icon-material: SPLASH_POTION
       bot-profile: null
       rules:
         ITEM_DROP: true
         ITEM_DAMAGE: true
         ITEM_PICK: true
         ELYTRA: false
         PUBLIC_PLAY: true
         PUBLIC_SPECTATE: true
         BUILD: false
       potions: []

2. Register the kit (/kitadmin save NoDebuff) and an arena category (/arena save nodebuff 40).
3. Run /eventpractice reload.
4. Confirm the new mode appears in the /queue menu and test the kit + arena pairing.

1. As an admin run /queue add nodebuff. The command:
   • creates a new MatchMode record in match-modes.yml,
   • adds a default PAPER item to menus/queue.yml (queue menus) named &9nodebuff with active players and queue status lore,
   • syncs the menus automatically.
2. Open the editor with /queue edit nodebuff and configure the mode: display name, kit, arena categories, rules, border, damage multiplier, enderpearl cooldown and (with TrainingBot) the bot profile.
3. Once kit and arena are ready, start a test match from the queue menu.

The config.yml → default-game-rules section defines the defaults for rules that are not overridden per mode or event.

1. Make sure at least one active match mode with kit and arena is ready (previous sections).
2. Tune the ELO parameters in config.yml:

   elo:
     default-rating: 1000     # starting score for new players
     k-factor: 32             # score change coefficient
     minimum-rating: 100      # rating floor
     matchmaking:
       base-range: 100        # initial search range (+/- ELO)
       range-increase: 50     # ELO added per expansion
       increase-every-seconds: 10   # expansion interval

3. Configure the ping-based matchmaking filter:

   queue:
     ping-range:
       enabled: true
       default: 60        # player's default ping gap limit (ms)
       minimum: 10
       maximum: 200
       step: 10           # increase/decrease step in the menu
       fallback-player-ping: 150   # used when ping cannot be read

4. Reload. Players pick a mode from the Ranked Queue lobby item or /ranked and enter the queue.

1. Install TrainingBot. Place the TrainingBot jar into /plugins and configure it according to its own docs (bot behaviors, difficulty levels).
2. Create a bot profile in TrainingBot. Define global bot profile(s) on the TrainingBot side (difficulty, strafe, potion throwing behavior etc.). The EventPractice queue editor lists these profiles automatically from the TrainingBot API (getGlobalProfileNames).
3. Start the server and verify the hook. You should see this line in console:

   TrainingBot found. Hooked into BotDeathListener successfully.

   If the message is missing, TrainingBot may have been loaded after EventPractice or the plugin name differs.

4. Assign bot profiles to match modes. Write the TrainingBot profile name into the mode's bot-profile field in match-modes.yml:

   modes:
     netheritepot:
       bot-profile: "PotBotMedium"

5. Customize the bot duel menu. Titles, items and layout are edited in menus/bot-duel.yml.
6. Test it. Open the menu with /botduel or run /botduel <mode>, pick a mode and start the duel. When the bot dies, the BotDeathListener hook closes the match flow cleanly on the EventPractice side.

1. Register an arena category suitable for FFA (large maps with multiple spawns recommended; see Arena Setup).
2. Make sure the modes used in FFA are enabled: true in match-modes.yml and their kit/arena pairing works.
3. Review the FFA behavior setting:

   ffa:
     refill-kit-on-kill: true   # refill kit after a kill (restock pots/items)

4. Customize the FFA scoreboard (scoreboard.yml → in-game.ffa; killstreak, total kills/deaths fields are supported) and the FFA menu (menus/ffa.yml).
5. Reload and test joining with /ffa, plus the FFA-appropriate respawn on death.

1. Set the default ticket amount in config.yml:

   default-ticket-amount: 10   # set -1 to disable the ticket system completely

2. Grant the ticket commands to your staff group with permissions:

   Command	Description	Permission
   /ticket info <player>	Shows remaining tickets	eventpractice.ticket.info
   /ticket add <player> <amount>	Adds tickets	eventpractice.ticket.add
   /ticket remove <player> <amount>	Removes tickets	eventpractice.ticket.remove
   /ticket set <player> <amount>	Sets the ticket amount directly	eventpractice.ticket.set

3. To attach tickets to VIP/shop packages, run /ticket add from your purchase flow (or console).

1. A player opens the event menu with the lobby's Create Event item or /event create: kit, participant limit (players.min/max/default), winner count (winner-amount), border radius/damage (world-border), damage multiplier, rules, potions.
2. Tickets are deducted when the event is created; the system picks a free arena and, while pasting, shows "Event is being created. It may take a few seconds...".
3. Other players join with /event join <player> or the owner invites them with /event invite <player> (chat message with join button; invite-cooldown prevents spam).
4. Advertise: /event advertise - throttled by advertise-cooldown (default 60s).
5. The owner starts the countdown with /event start (countdown-seconds, required-players). The countdown is cancelled if there are not enough players.
6. Spectating: /event spectate <player>. The owner can remove problem players with /event ban <player>.
7. In-game controls: /event border <radius> <delay> and /event dropdown <targetY> let the event owner manage the border and Y levels.

Players store frequently used event settings as presets (kit, damage multiplier, potions, rules, border). Menu: menus/preset.yml. Data is kept in the event-presets storage area and reached from the /settings profile menu.

1. Confirm the system is enabled:

   visual-replay:
     enabled: true
     cooldown: 10s
     recording:
       enabled: true
       max-duration: 5m
       max-participants: 16

2. Check the playback world. Replays are played back in a separate world instance:

       world-instance:
         enabled: true
         world: eventpractice_replay
         auto-create-world: true

   The world is created automatically; change the world name if you want your own replay world.

3. Define storage and cleanup policy:

       storage:
         directory: replays
         retention: 15m        # how long recordings are kept
         max-stored: 250
         max-replay-size-mb: 10.0
         cleanup:
           enabled: false      # set true if you want automatic cleanup

4. With Citizens installed, replay visuals render through NPCs; otherwise Armor Stand rendering is used with fallback-armorstand: true.
5. Reload. Finish a match and verify the recording exists with /replay latest; /replay status shows system health.

License, color format, database, arena world, core event parameters, ELO, FFA, queue ping range, default game rules, lobby/spawn items and the visual-replay configuration.

license-key: contact the author
color-format: "legacy" # "legacy" (& codes) or "minimessage" (<color> tags)
database:
  method: "SQLite" # SQLite | MySQL
  data:
    host: "localhost"
    port: 3306
    database: "eventpractice"
    username: "root"
    password: ""
    ssl: false
arenas-world: "Arenasworld"
countdown-seconds: 10
required-players: 2
default-ticket-amount: 10 # -1 = ticket system disabled
delay-before-end: 5
advertise-cooldown: 60
invite-cooldown: 30
team-glow: true            # packet-based glow when packetevents is present
allowed-commands: [/msg, /stats, /ping]
y-coordinate: {min: -64, max: 256}
players: {max: -1, min: 2, default: 10}
winner-amount: {max: 5, min: 1, default: 1}
world-border:
  radius: {max: 150, min: 50, default: 100}
  damage: {max: 20, min: 0, default: 5}
damage-multiplier: {max: 100, min: 0, default: 0}
elo:
  default-rating: 1000
  k-factor: 32
  minimum-rating: 100
  matchmaking: {base-range: 100, range-increase: 50, increase-every-seconds: 10}
ffa:
  refill-kit-on-kill: true
queue:
  ping-range: {enabled: true, default: 60, minimum: 10, maximum: 200, step: 10, fallback-player-ping: 150}

Covered in detail in the Match Modes & Queue section. Each mode carries display-name, kit, arena-category, rules, border, potions, bot-profile and icon. Mode ids (keys) are permanent identifiers.

Categories (e.g. crystal-pvp), potions and misc sections carry slot → item definitions. Syntax examples are in the Kit Setup section.

# Kill message styles: default, brutal, flashy + custom packs
# Placeholders: <killer>, <victim>, <mode>
# Kill effects: particle burst, totem burst, firework burst,
#               cosmetic lightning, dust ring
# Per effect: enabled, display name, lore, type, sound

Players pick their message and effect from the Kill Cosmetics screen in the profile menu. The file works together with the menus/kill-cosmetics.yml menu.

main-menu:
  title: "&8Queue Selection"
  size: 27
  items:
    crystalpvp:
      material: END_CRYSTAL
      name: "&9Crystal PvP"
      lore:
        - "&8Mode Details"
        - "&7Active Players: &f<playing>"
        - "&7Queue Status: &f<queued>"
        - ""
        - "&eClick to select this mode."