User Guide
Contains all the information relating to running the BattleArena plugin.
- Plugin Overview
- Installation
- Arena Management
- Map Creation
- Arena Configuration
- Creating Custom Modes
- Event Reference
- Action Reference
- Option Reference
- Victory Conditions Reference
- Configuration
- Leaderboards and Statistic Tracking
- Frequently Asked Questions
- Commands
- Teams
- Permissions
- Additional Resources
- Plugin Integrations
Plugin Overview
BattleArena is a complete match and event framework for Minecraft. Supports creating modes through config files, or fully custom modes through plugins.
BattleArena allows you to create your own games on a Minecraft server through config files. It comes with a large number of customizable options, allowing you to configure a wide number of features.
Default Modes
Active games in BattleArena are referred to as Competitions. BattleArena natively supports two competition types:
- Match: A game that is started when a certain condition is met (i.e. number of players), or is always active. These games can be joined at any time, as long as there are available maps. Common examples may include Spleef, SkyWars, Survival Games, or Capture the Flag.
- Event: A game that is started based on a certain interval, or when triggered by a server administrator. These games cannot be joined normally unless the event is active. Common examples may include a bracket tournament, deathmatch, or a free for all.
Builtin Match Types
- Arena: Simple duels mode that you fight with what is given to you in the config.
- Skirmish: You bring in items you want to fight with. The game is always running, and you can join and leave at any time.
- Colosseum: 4v4 team deathmatch. Last team standing wins.
- Battlegrounds: 1 minute match in which the winner is the player with the most kills.
Builtin Event Types
- Free for All: A free for all deathmatch that starts every 30 minutes. Last player alive wins.
- Deathmatch: A 2-minute event where if you die you respawn. The player with the highest number of kills wins.
- Tournament: Bracket tournament for any number of teams.
Default Modules
As part of being a match and event framework, BattleArena is very modular and comes pre-installed with multiple modules which extend upon the base functionality in the plugin. These include:
- Arena Restoration - Restores maps using WorldEdit once they complete
- Boundary Enforcer - Ensures players do not leave the boundaries of a map
- Classes - Adds classes/kits to BattleArena
- Scoreboards - Adds scoreboard support to BattleArena
- Team Colors - Colors players names inside competitions to their team colors
- Team Heads - Adds the item from the teams.yml to a player's head
- Tournaments - Adds bracket tournaments to BattleArena
- Vault Integration - Adds support for Vault into BattleArena
Installation
Requirements
- A Paper server (or other derivative) running 1.19.4 or above
Downloading
- Download the BattleArena plugin
- Stop your server and place the plugins in your plugins folder
- Start the server and BattleArena will load
Arena Management
Map Creation
Overview
BattleArena comes with a handful of arenas built-in. An "Arena" in BattleArena represents an individual mode. A "Map" is used to denote an actual game map that is used. A "Competition" is what will occur in the map. Maps can exist without an active competition, but a competition cannot exist without a map.
By default, BattleArena comes with 6 different Arena types which are covered briefly on the Plugin Overview page.
Creating a Map
A map can be created with the /<arena> create command. This command will open a wizard which will guide you through the map creation process. The root command determines which arena to create the map for, so /battlegrounds create will create a Battlegrounds map, whereas /arena create will create an Arena map.
The full steps are also shown below.
Map Name
The first step in creating a map is setting a map name. Type the name in chat to set the name of the map.
Map Type
You will next be prompted to choose which map type to select.
Static maps are maps that exist in the same place all the time. This means that no new world is created for your map when a competition starts. If you wish to have a gamemode in a colosseum on a survival server for instance, where players can see the active game, this is perhaps the best option. The disadvantage to this option is that there can only be one of this map available at a time.
If you have WorldEdit installed, you can select the dynamic option as well. Dynamic maps are maps created on-demand, meaning that when a player wishes to join the map, a new world is created with the map copied into it. The advantage to this option is that the map can scale up as needed, but may result in a performance hit on slower machines due to the cost of creating worlds and pasting the map contents in them. This can be mitigated slightly by using FastAsyncWorldEdit however.
Map Bounds
The next step involves you selecting the region of the map. The wizard will ask you to click the blocks that should be the minimum and maximum positions. This is particularly important for dynamic maps, as it tells BattleArena what should be copied over to your dynamic world.
Waitroom Spawn
BattleArena will next ask you to select a waitroom spawn. This is where players will wait for a competition to start in arenas where a waitroom is configured. This will be set to your current position once you type "waitroom" in chat.
Even if your game mode does not have a waitroom, this option must be set to proceed with the wizard.
Spectator Spawn
Similar to above, BattleArena will next ask for you select a spectator spawn. This is where spectators will spawn when they spectate a competition in this map. This will be set to your current position once you type "spectator" in chat. This too is required to proceed with the wizard.
Team Spawns
The next and final option is where you configure spawnpoints. Similar to the last two steps, when you type "spawn" in chat, a spawn point will be created at your location.
Once you type "spawn", you will need to enter which team the spawn belongs to. In solo games, this will often just be "Default", however BattleArena will inform your of all the valid teams available.
Once you have typed in the team name, you can continue adding as many spawns as you wish by continuing to type "spawn" in chat. Once you are done, type "done" in chat and the wizard will complete.
Now that the map is created, you can join it using the /<arena> join <map> command.
Editing a Map
Maps can be edited with the /<arena> edit <map> <option> command. Upon typing in the command, a list of modifiable options will show up in the tab completion. These will correspond to the documented options above, and upon executing the command, updating a specific option follows the exact same instructions.
Deleting a Map
Maps can simply be deleted using the /<arena> delete <map> command.
Map Storage
Maps are stored in the plugins/BattleArena/maps directory. Each arena will have its own directory containing the map configurations. These can also be modified by hand, and loaded in-game by running the /ba reload command.
Arena Configuration
Overview
BattleArena offers a significant amount of flexibility when it comes to configuring arenas.
All arenas in BattleArena are located in the plugins/BattleArena/arenas directory. All of these can be modified, deleted and new ones can be added. For the sake of this tutorial, we will be working with the arena.yml arena configuration. Each set of options is documented below.
Standard Options
- name: The name of the arena.
- mode: The mode of the arena. BattleArena only comes with the "Arena" mode built in, but extension plugins may add new modes.
- aliases: Command aliases to see available commands for this arena.
- type: The type of arena. Can either be Match or Event. See the plugin overview page for what differentiates these two.
- modules: A list of modules to enable in this competition. See the Modules and Other Tools page for more information on modules.
NOTE: Changing these options for arenas with existing maps may cause the maps to no longer be linked to the arena. If this occurs, be sure to update the map arenas in plugins/BattleArena/maps/<arena> YAML files. You may need to rename the directory to be the same name as what is set in the name option above.
Team Options
Manages how to distribute players across teams along with options regarding the team size.
- named-teams: Whether teams should be named (i.e. Red, Blue, etc.) See the teams page for more information about teams.
- team-size: How many players this team fits. This can be a specific number, a range, or a minimum-inclusive range. See the following examples:
- team-size: 4: Each team must have 4 players in order for a competition to start. Additionally, the team can only hold 4 players.
- team-size: 2-4: Each team can hold between 2 and 4 players. The competition will start once each team has at least 2 players.
- team-size: 2+: Each team can hold 2 or more players (minimum-inclusive). The only limit is the number of spawns set in the map.
- team-selection: How team selection is done in the competition. The following options are listed below:
- none: No team selection. This is often used for solo competitions, where a player does not have a specific team and all other players are their enemies
- random: BattleArena randomly assigns a player to a team.
- pick: Players pick their team (usually during a countdown or waiting phase). This can be done using the /<arena> team <team> command. Server owners can also configure this to be done when the player clicks an NPC, sign or GUI button.
- shared-spawn-points: Whether team members are able to share spawn points. This is primarily useful for team games where all players on a team spawn at the same place.
team-options:
named-teams: true
team-size: 4
team-amount: 4
team-selection: pick
shared-spawn-points: true
An example from colosseum.yml is shown above, which shows these options in use.
Lives
Controls how many lives players have in an arena. By default, this is disabled,
- enabled: Controls whether lives are enabled.
- amount: How many lives a player has by default.
Victory Conditions
Controls how a player or team may "win" a competition. Each victory condition has its own set of options which determine how a player may win. Multiple can be set per competition, and once one condition is met, the competition ends. An example is shown below for the teams alive and time limit conditions.
victory-conditions:
teams-alive:
amount: 1
time-limit:
time-limit: 5m
In this example, a team will win the competition if they are the last team standing. However, if after 5 minutes there is no winner, the competition will end and all remaining players will draw.
A full list of victory conditions can be found on the Victory Conditions Reference page.
Events & Actions
This is where the bulk of logic for BattleArena is configured. Events denote when certain "things" happen in an arena, such as when a player joins, spectates, leaves, wins, dies, etc. Upon these events, actions can be ran which control the competition behavior. These can be as simple as sending a message to the player, clearing their inventory, or kicking them from the arena.
An example from the arena.yml is shown below for the on-join and on-leave events.
events:
on-join:
- store{types=all}
- change-gamemode{gamemode=adventure}
- flight{enabled=false}
- teleport{location=waitroom}
on-leave:
- clear-effects
- restore{types=all}
As seen in the on-join event, when a player joins the arena, their state is stored. This includes their inventory, previous gamemode, health, attributes, experience, effects and last location. Their gamemode is also updated to adventure, flight is disabled for them, and they are teleported to the waitroom.
When the player leaves, as seen in the on-leave event, the player's previous state is restored. This will effectively restore everything that was stored when the store action was called.
A full list of events can be found on the Event Reference page. All actions can be found on the Action Reference page.
Options
The options section allows you to control mechanics while in the arena. The default options from the arena.yml is shown below.
options:
- block-break{enabled=false}
- block-place{enabled=false}
- block-interact{enabled=false}
- damage-entities{option=never}
- keep-inventory{enabled=true}
- keep-experience{enabled=true}
These are fairly self explanatory, and disable various mechanics such as block breaking and entity damage.
A full list of options can be found on the Option Reference page.
Phases
Perhaps one of the most powerful systems in the plugin, phases let you control exactly how a competition progresses. BattleArena comes built-in with four phases, which are all utilized in the arena.yml.
Each phase has a set of common options that are available for any phase. These are listed below:
- next-phase: The next phase to progress to.
- allow-join: Whether players can join during this phase. Highly recommended to set to true for the waiting phase.
- allow-spectate: Whether this map can be spectated during this phase.
- options: Options (see above) that are set for this phase only. This allows for more fine-tuning of options, such as enabling damage in an in-game state, or disabling block breaking during a waiting phase.
- events: Events (see above) that are set for this phase only. This allows for more fine-tuning of events, such as giving players items in on-start or teleporting them to a spawn location in on-respawn.
The initial phase is set in the config using the initial-phase option.
Waiting
This phase is simply a holding phase for players before a competition begins. Nothing really happens here, except the progression to the next phase once a player threshold is hit.
The example from arena.yml is broken down below:
phases:
waiting:
allow-join: true
next-phase: countdown
options:
- damage-players{option=never}
This essentially means that during this phase, players cannot damage each other along with all the other options set in the main options section. Once the player threshold is hit, the game will move on to the countdown state.
Countdown
This phase is a generic countdown phase that runs a countdown timer, in which once concluded, will move on to the next state. This is often paired with a waiting state, before moving on to an ingame state.
Options:
- revert-phase: Whether the countdown should cancel and the competition should revert to the previous state if the conditions are no longer met (i.e. not enough players).
- countdown-time: How long the countdown should be.
- sound: What sound the play when a countdown number is broadcasted. Leave blank to disable.
The example from arena.yml is broken down below:
phases:
countdown:
allow-join: false
allow-spectate: true
revert-phase: true
next-phase: ingame
countdown-time: 5s
options:
- damage-players{option=never}
events:
on-complete:
- teleport{location=team_spawn}
- give-effects{effects=[speed 300 1]}
- play-sound{sound=block.note_block.pling;pitch=2;volume=1}
In this example, the countdown phase will only last 5 seconds before progressing onto the ingame phase. Players can also not join during this phase, as allow-join is set to false. Once this phase is complete, players will be teleported to their team spawn, given speed, and a sound is played to notify them the competition is now in-game.
In-game
This phase is the phase in which victory conditions are checked upon, and when the actual game logic should run. The example from arena.yml is provided below:
phases:
ingame:
allow-join: false
allow-spectate: true
next-phase: victory
options:
- damage-players{option=other_team}
As seen here, the damage-players option has been updated to allow damaging players on other teams. The next phase is set to victory, so once the victory conditions are met, the competition will progress to the victory phase.
Victory
The final phase in the logic for a competition. This is called once victors have been determined for a competition.
Options:
- duration: How long the competition should remain in this phase before moving to the next phase.
The example from arena.yml is broken down below:
phases:
victory:
allow-join: false
allow-spectate: false
next-phase: waiting
duration: 5s
events:
on-complete:
- leave
on-victory:
- send-message{message=<green>Congrats, you won!</green>}
- play-sound{sound=entity.player.levelup;pitch=1;volume=1}
on-lose:
- send-message{message=<red>Sorry, you lost!</red>}
- play-sound{sound=block.anvil.place;pitch=0;volume=1}
on-draw:
- send-message{message=<yellow>It's a draw!</yellow>}
- play-sound{sound=block.beacon.deactivate;pitch=0;volume=1}
During this phase, player joining is still disabled, along with spectators now. As seen in the events section though, upon the completion of the victory phase (after the 5 seconds), the player is removed from the competition with the leave action. All the victors are sent a message upon their victory, informing them they won the game. The losers are told they have lost the game.
In the case of a draw, the on-draw event will be ran, in which all players will be informed the competition ended in a draw.
Conclusion
These phase options are quite flexible, and not all are required. In the case of a Skirmish arena for example (provided by default in BattleArena), the game is always running and can be joined or left at any point. The game also never ends. Due to this, only the ingame phase is present.
Creating Custom Modes
Overview
This page covers creating a custom arena mode with some more advanced features. It largely picks up from the Arena Configuration page, so before continuing on with this section, it's recommended to familiarize yourself with the arena configurations. This is primarily a walk-through example.
In this example, we will be creating a 2v2 PvP game with up to 5 players on each team called Red vs Blue. Each player will have 3 lives, and the last remaining team alive wins. This will be a 10 minute game.
Standard Options
The first step will be configuring the standard options for the arena.
name: RedvsBlue
aliases: [rvb]
mode: Arena
type: Match
This sets the arena name to RedvsBlue, the aliases for the command to /rvb, the mode to Arena, and the type to Match.
Team Options
team-options:
named-teams: true
team-size: 2-5
team-amount: 2
team-selection: random
This will set the team options to use named teams, with a team size of between 2 - 5 players from earlier. This means the game will begin starting when there are at least 2 players on each team, but max out at 5 players on each.
Modules
For this mode, we will be enabling a few modules: Classes, Team Colors, and Team Heads.
In order to enable these, the following options have been added:
modules:
- classes
- team-colors
- team-heads
Lives
The lives configuration has been updated to be enabled, and give each player three lives.
lives:
enabled: true
amount: 3
Victory Conditions
The following victory conditions have been enabled: teams-alive and time-limit. We want the game to end when there is one team alive, but if after 10 minutes there is no victor, the game should end in a draw.
victory-conditions:
teams-alive:
amount: 1
time-limit:
time-limit: 10m
Events & Actions
For this mode, we will be using very similar events from the arena.yml, however some changes have been made since players will have multiple lives in this mode.
In the on-death event, the teleport and delay actions have been removed, leaving it as the following:
events:
on-death:
- clear-inventory
- respawn
Since the player has multiple lives, we don't want them being teleported back to the waitroom on death. However, if the player has exhausted all their lives, we also don't want them being teleported into the game. The following events below are used:
events:
on-life-deplete:
- delay{ticks=2}
- give-effects{effects=[speed 300 1]}
- teleport{location=team_spawn}
- equip-class{class=warrior}
- team-heads
on-lives-exhaust:
- delay{ticks=2}
- teleport{location=waitroom}
As seen here, on-life-deplete is used when the lives are depleted. This is called upon death, but only when the player has lives remaining. We want to use this event here as it allows players to be teleported back to the game, only when they have lives to spare.
However, when the player runs out of lives, on-lives-exhaust is called. In this case, we want to teleport the player back to the waitroom.
More details about these events and others can be found on the Event Reference page.
The delay option used above allows you to delay how long until the next action runs. In this case, we delay immediately since we want to ensure the player is fully respawned, and their death & lives tally have updated internally.
Options
For the options, we will be using the same options as arena.yml.
options:
- block-break{enabled=false}
- block-place{enabled=false}
- block-interact{enabled=false}
- damage-entities{option=never}
- keep-inventory{enabled=true}
- keep-experience{enabled=true}
- class-equip-only-selects{enabled=true}
Phases
The phases for this game are the same as what is from arena.yml, with some minor additions.
The first option being changed is to the countdown phase, increasing the countdown-time from 5 seconds to 1 minute. Since the maximum players for this game is 10, but the minimum is 4, we want to give players not in the game a longer opportunity to join before starting the game. Additionally, the allow-join option has been set to true, since we want to allow joins during the countdown phase.
And finally, in the ingame phase, the following is added to the events section:
events:
on-start:
- team-heads
This will set the player's helmet to their team color, using the team-heads action.
Conclusion
And with this done, we now have a Red vs Blue arena! Run /ba reload or restart the server, and the arena will now exist on the server. A map for this arena can be created by following the Map Creation instructions, and joined with /rvb join.
A full YAML file for the Red vs Blue arena can be found below:
name: RedvsBlue
aliases: [rvb]
mode: Arena
type: Match
team-options:
named-teams: true
team-size: 2-5
team-amount: 2
team-selection: random
modules:
- classes
- team-colors
- team-heads
lives:
enabled: true
amount: 3
victory-conditions:
teams-alive:
amount: 1
time-limit:
time-limit: 10m
events:
on-join:
- store{types=all}
- change-gamemode{gamemode=adventure}
- flight{enabled=false}
- teleport{location=waitroom}
on-spectate:
- store{types=all}
- change-gamemode{gamemode=spectator}
- flight{enabled=true}
- teleport{location=waitroom}
on-leave:
- clear-effects
- restore{types=all}
on-death:
- respawn
- clear-inventory
on-life-deplete:
- delay{ticks=2}
- give-effects{effects=[speed 300 1]}
- teleport{location=team_spawn;random=false}
- equip-class{class=warrior}
- team-heads
on-lives-exhaust:
- delay{ticks=2}
- teleport{location=waitroom}
options:
- block-break{enabled=false}
- block-place{enabled=false}
- block-interact{enabled=false}
- damage-entities{option=never}
- class-equip-only-selects{enabled=true}
- keep-inventory{enabled=true}
- keep-experience{enabled=true}
initial-phase: waiting
phases:
waiting:
allow-join: true
next-phase: countdown
options:
- damage-players{option=never}
- class-equipping{enabled=true}
countdown:
allow-join: true
allow-spectate: true
revert-phase: true
next-phase: ingame
countdown-time: 1m
options:
- damage-players{option=never}
- class-equipping{enabled=true}
events:
on-complete:
- teleport{location=team_spawn}
- give-effects{effects=[speed 300 1]}
- play-sound{sound=block.note_block.pling;pitch=2;volume=1}
ingame:
allow-join: false
allow-spectate: true
next-phase: victory
options:
- damage-players{option=other_team}
events:
on-start:
- equip-class{class=warrior}
- team-heads
victory:
allow-join: false
allow-spectate: false
next-phase: waiting
duration: 5s
events:
on-complete:
- clear-effects
- leave
on-victory:
- send-message{message=<green>Congrats, you won!</green>}
- play-sound{sound=entity.player.levelup;pitch=1;volume=1}
on-lose:
- send-message{message=<red>Sorry, you lost!</red>}
- play-sound{sound=block.anvil.place;pitch=0;volume=1}
on-draw:
- send-message{message=<yellow>It's a draw!</yellow>}
- play-sound{sound=block.beacon.deactivate;pitch=0;volume=1}
Event Reference
Overview
This page contains all the events built in to BattleArena natively. Additional modules or extensions may add new events, which will be included on their documentation page.
Events List
Event |
Description |
on-start | Called when a phase starts. Best used inside of the events section of phases, since while this can be used globally, it'll call on every phase. |
on-complete |
Called when a phase completes. Best used inside of the events section of phases, since while this can be used globally, it'll call on every phase. |
on-join |
Called when a player joins a competition. |
on-leave |
Called when a player leaves a competition for any reason. |
on-respawn |
Called when a player respawns in a competition. |
on-death |
Called when a player dies in a competition. |
on-life-deplete |
Called when a player loses a life, but still has lives to spare. |
on-lives-exhaust |
Called when a player loses their final life and is considered "dead". |
on-kill |
Called when a player kills another player in a competition. |
on-victory |
Called when a player or team is victorious in a competition. This is only called for players who win the competition. |
on-lose |
Called when a player or team loses a competition. This is only called for players who lose in the competition. |
on-draw |
Called when a competition ends in a draw. This will be called for all players. |
on-spectate |
Called when a player spectates a competition. |
Action Reference
Overview
This page contains all the actions built in to BattleArena natively. Additional modules or extensions may add new actions, which will be included on their documentation page.
Actions List
- <, > denotes a required option
- [, ] denotes an optional option
- Options are separated using the semicolon (;)
Broadcast
- Description: Broadcasts a message to the specified audience
- Options
- <message> The message to broadcast
- [audience] Who the message will be broadcasted to. Can be game or server (default game)
- [type] The type of message. Can be chat, action_bar, title, subtitle (default: chat).
- Syntax
- broadcast{message=<message>;type=[type]}
Change Gamemode
- Description: Changes the player's gamemode
- Options
- <gamemode> The gamemode to set the player to
- Syntax
- change-gamemode{gamemode=<gamemode>}
Change Role
- Description: Changes the player's role
- Options
- <role> The role to set the player to. Can be playing or spectating
- <role> The role to set the player to. Can be playing or spectating
- Syntax
- change-role{role=<role>}
Clear Effects
- Description: Clears all of a player's effects
- Syntax
- clear-effects
Clear Inventory
- Description: Clears a player's inventory
- Syntax
- clear-inventory
Delay
- Description: Delays any subsequent actions by a specified duration
- Options
- <ticks> The amount of time to delay the next action
- <ticks> The amount of time to delay the next action
- Syntax
- delay{ticks=<ticks>}
Flight
- Description: Sets whether a play can fly
- Options
- <enabled> Whether the player can fly
- <enabled> Whether the player can fly
- Syntax
- flight{enabled=<enabled>}
Give Effects
- Description: Gives potions effects to a player
- Options
- <effects> The effects to give to the player
- Syntax
- give-effects{effects=<effects>}
- The effects syntax is in a list format, with root object being the effect name, and the parameters specified inside
- Example: give-effects{effects=[speed{duration=300;amplifier=1},jump_boost{duration=300;amplifier=1}]}
- The effects syntax is in a list format, with root object being the effect name, and the parameters specified inside
- give-effects{effects=<effects>}
Give Item
- Description: Gives an item to a player
- Options
- <item> The item to give to the player
- [slot] The slot to place the item in. If unspecified, it will be added to the next available slot
- Syntax:
- give-item{item=<item>;slot=[slot])
- See the Item Syntax page for how to format items in this section
- give-item{item=<item>;slot=[slot])
Health
- Description: Sets the player's health and hunger values
- Options
- <health> The health to set for the player
- <hunger> The hunger to set for the player
- <health> The health to set for the player
- Syntax
- health{health=<health>;hunger=<hunger>}
Join Random Team
- Description: Makes a player join a random team. Only runs on players who have not selected a team already
- Syntax
- join-random-team
Kill Entities
- Description: Kills all entities within the map bounds
- Options
- [excluded-groups] The group of entities to exclude. If left empty, all entities are killed aside from players
- The following options are allowed: monster, animal, water_animal, water_ambient, water_underground_creature, ambient, axolotl
- [excluded-groups] The group of entities to exclude. If left empty, all entities are killed aside from players
- Syntax
- kill-entities{excluded-groups=<excluded-groups>}
- The kill-entities syntax is in a list format, with the separator being a comma
- Example: kill-entities{excluded-groups=[monster,axolotl]}
- kill-entities{excluded-groups=<excluded-groups>}
Leave
- Description: Causes a player to leave the competition
- Syntax
- leave
- leave
Play Sound
- Description: Plays a sound to the player
- Options
- <sound> The sound to play
- [pitch] The pitch of the sound. Values between 0 and 2 are allowed
- [volume] The volume of the sound
- <sound> The sound to play
- Syntax
- play-sound{sound=<sound>;pitch=[pitch];volume=[volume]}
Reset State
- Description: Resets the state of a player. This will clear all of their stats, and make them leave their current team (and rejoin a random one if applicable)
- Syntax
- reset-state
Respawn
- Description: Causes a player to automatically respawn
- Syntax
- respawn
- respawn
Restore
- Description: Restores player data that was previously stored
- Options
- <type> The type of data to restore.
- The following options are available: all, inventory, gamemode, health, attributes, experience, flight, effects, location
- <type> The type of data to restore.
- Syntax
- restore{types=<types>}
- restore{types=<types>}
Run Command
- Description: Runs a command
- Options
- <command> The command to run
- [source] The source of the command Can be player or console (default: player)
- Syntax
- run-command{command=<command>;source=[source]}
- run-command{command=<command>;source=[source]}
Send Message
- Description: Sends a message to the player
- Options
- <message> The message to send
- [type] The type of message. Can be chat, action_bar, title, subtitle (default: chat).
- Syntax
- send-message{message=<message>;type=[type]}
Store
- Description: Stores player data that should later be restored. Allows for instances where games may have their own inventories, but player inventories should be restored later
- Options
- <type> The type of data to restore.
- The following options are available: all, inventory, gamemode, health, attributes, experience, flight, effects, location
- [clear state] Whether the state should be cleared. If false, this means that players will join with their previous inventory, gamemode, etc., or whatever is configured in the type option. However, the inventory that was used before the competition will be restored at the end, so if a player were to break a chestplate, the previous version of that chestplate is what would be restored at the end of the competition.
- <type> The type of data to restore.
- Syntax
- store{types=<types>;clear-state=[true|false]}
Teardown
- Description: Tears down a competition and removes it from starting again. Often used for event competitions, which close once the event has concluded
- Syntax
- teardown
Teleport
- Description: Teleports a player to a location in a map
- Options
- <location> The location to teleport the player. Can be waitroom, spectator, team_spawn or last_location
- [random] Whether the teleport is randomized. Only used for the team_spawn option
- Syntax
- teleport{location=<location>;random=[random]}
- teleport{location=<location>;random=[random]}
Option Reference
Overview
This page contains all the options built in to BattleArena natively. Additional modules or extensions may add new options, which will be included on their documentation page.
Options List
Option |
Description |
Syntax |
block-break |
Whether block breaking is enabled. |
block-break={enabled=<true|false>} |
block-place |
Whether block placing is enabled. |
block-place={enabled=<true|false>} |
block-drops |
Whether blocks will drop loot when broken. |
block-drops={enabled=<true|false>} |
block-interact |
Whether players can interact with blocks (i.e. buttons). |
block-interact={enabled=<true|false>} |
hunger-deplete |
Whether hunger should deplete. |
hunger-deplete={enabled=<true|false>} |
item-drops |
Whether players can drop items while in a competition. |
item-drops={enabled=<true|false>} |
keep-inventory |
Whether players keep their inventory when they die in a competition. |
keep-inventory={enabled=<true|false>} |
keep-experience |
Whether players keep their experience when they die in a competition. | keep-experience={enabled=<true|false>} |
team-selection |
Whether players can switch teams. |
team-selection{enabled=<true|false>} |
damage-players |
Whether players can damage other players. |
damage-players={option=<never|other_team|always>} |
damage-entities |
Whether players can damage other entities. |
damage-entities={option=<never|other_team|always>} |
Victory Conditions Reference
Overview
This page contains all the victory conditions built in to BattleArena natively. Additional modules or extensions may add new actions, which will be included on their documentation page.
Victory Conditions List
Highest Stat
- Description: A victory condition that determines the winner based on the highest stat
- Options
- stat-name: The name of the stat
- win-after: The threshold of a stat value to achieve before a winner is determined (default: -1)
- If this option is not specified, this condition can still be used, but the winner will be determined when otherwise a draw would have occurred (i.e. in time-limit)
- team-stats: Whether to tally up all the stats of a team, rather than an individual player. (default: false)
- Example:
victory-conditions:
highest-stat:
stat-name: kills
win-after: 20
team-stats: false
Teams Alive
- Description: A victory condition that determines the winner when a certain number of alive teams are remaining
- Options
- amount: The amount of teams alive
- Example:
victory-conditions:
teams-alive:
amount: 1
Time Limit
- Description: A victory condition that ends the competition after a specified amount of time. This will always result in a draw if a victor cannot be determined. When combined with highest-stat, at the end of this time, the victor will be the player with the highest number of the specified statistic
- Options
- time-limit: The amount of time before the competition is ended
- time-limit: The amount of time before the competition is ended
- Example:
victory-conditions:
time-limit:
time-limit: 5m
Configuration
Overview
This page covers the main configuration for BattleArena (config.yml). For information about arena configurations, see the Arena Configuration page.
Config Options
backup-inventories
- Description: Whether player inventories should be backed up when joining competitions. This is designed as a safety measure in instances where a server crashes while players are in a competition and their inventories have become desynced.
- Default option: true
max-backups
- Description: The maximum number of backups to save for each player.
- Default option: 5
max-dynamic-maps
- Description: The maximum amount of dynamic maps an Arena can have allocated at once. This enforces a limit on the number of dynamic maps to ensure an excessive amount of server resources are not used. Setting this value to -1 disables the limit.
- Default option: 5
disabled-modules
- Description: Modules that are disabled by default. BattleArena comes pre-installed with multiple modules that can be disabled with this option if their behavior is not desired.
- Default option: empty list
randomized-arena-join
- Description: Whether joining an arena using /<arena> join without specifying a map should randomly pick an arena, rather than joining the most convenient one. Competitions with players waiting will always be prioritized though, even with this setting enabled.
- Default option: false
events
- Description: Contains a list of event schedules. This allows for automatic scheduling of arenas with the Event type. Multiple event schedules can be defined for an arena. The interval determines when to run the event, and the message specified will be broadcasted to all players once the event has started. Additionally, the delay option lets you specify how long until the initial event starts, in addition to the interval. As seen in the example below, the first event will run 35 minutes after the server starts, however once an FFA event ends, another will start 30 minutes later.
- Default value:
events:
FFA:
- type: scheduled
interval: 30m
delay: 5m
message: "<gold>[</gold><yellow>BattleArena</yellow><gold>]</gold> <yellow>A Free for All event is starting! Run <gold>/ffa join</gold> to join!</yellow>"
Leaderboards and Statistic Tracking
BattleArena has support in companion with BattleTracker to track arena statistics and leaderboards.
Tracking Statistics
In order to track statistics, the first step is to simply download BattleTracker. Upon restarting the server with BattleTracker, the following commands will become available:
- /<arena> top - Shows the leaderboard of player wins in the competition
- /<arena> rank [name] - Shows the rank and associated statistics of a specific player
Storing Additional Statistics
In some cases, it may be desired to track additional statistics that are not tracked by BattleArena by its own. An example of this in use is ArenaCTF, which tracks the flags captured and shows them in /ctf rank [name].
By default, BattleArena does not track any statistics that are not otherwise tracked by BattleTracker, so this feature is generally most useful for third party plugins that provide their own. However, it is documented here for the sake of visibility.
In your <arena>.yml, you can simply add the following section to track those statistics permanently. Here is an example with the flags-captured statistic.
tracking:
stats-tracked:
flags-captured:
key: flags_captured
type: add
Frequently Asked Questions
Is BattleArena survival friendly?
BattleArena was designed with a large emphasis on survival Minecraft servers. BattleArena works alongside existing Minecraft plugins on survival servers to offer additional experiences alongside traditional survival modes. Arena isolation is a core feature, allowing you to completely segment off BattleArena minigames from the rest of the server, but also can be ran without isolation (i.e. the Skirmish mode), allowing players to bring in their survival items.
My server crashed and players lost their inventories
In the event of a server crash, BattleArena has an inventory backup system implemented to alleviate this. Simply run /ba backups <player> to view all the backups a player has. By default, BattleArena will save back to 5 inventory backups, which can be changed in the configuration.
Running /ba restore <player> <backup index> will restore a player's inventory to the backup specified. This will clear the player's current inventory, so ensure that you wish to perform this command!
How do I track statistics?
In order to track statistics from arenas, you must install the BattleTracker plugin which works in conjunction with BattleArena.
Commands
BattleArena Commands
This contains commands for the /battlearena (or /ba) command. These are not tied to a specific arena.
Command |
Description |
/battlearena backups <player> |
Shows backups that a player has saved. |
/battlearena backup <player> |
Creates a manual backup of a player inventory. |
/battlearena debug |
Toggles debug mode. |
/battlearena module |
Lists all modules. |
/battlearena reload |
Reloads the plugin. |
/battlearena restore <player> <number> |
Restores a backup for a player. Backup numbers can be found with the /battlearena backups <player> command. |
/battlearena schedule <arena> <duration> |
Schedules an event to start at the specified time. |
/battlearena start <arena> |
Starts an event manually |
/battlearena stop <arena> |
Stops an event manually. |
/battlearena stopall |
Stops all events manually. |
Arena Commands
These are commands that any Arena executor will have.
Command |
Description |
/<arena> advance |
Advances the arena to the next phase. |
/<arena> create |
Creates a new map. |
/<arena> edit <map> <map option> |
Edits an arena map. |
/<arena> join [map] |
Joins an arena. |
/<arena> list |
Lists all maps and competitions in them. |
/<arena> kick <player> |
Kicks a player from the arena. |
/<arena> leave |
Leaves the arena. |
/<arena> team join <team> |
Joins a team. Only works if team selection is set to pick in the arena's team-options. |
/<arena> team leave <team> | Joins a team. Only works if team selection is set to pick in the arena's team-options. |
/<arena> team list | Lists all available teams. |
/<arena> remove <map> |
Removes a map. |
/<arena> spectate [map] |
Spectates an arena. |
Teams
Overview
This page covers the main teams configuration for BattleArena. Per-arena team configurations are covered in more detail in the Arena Configuration page.
Teams Configuration
The main teams configuration in BattleArena is located in the plugins/BattleArena/teams.yml file. Quite simply, this is just a list of teams that BattleArena will use in competitions.
By default, teams are allocated to a game based on which teams are in the configuration file first. For instance, if an arena has a team-amount set to 2, that means the first two teams in the configuration will be used (red and blue by default). However, this can be changed per map, by simply making the team amount min inclusive by adding a + (so, team-amount: 2+), and only creating spawn points for the desired teams.
teams:
- name: Red
color: 255,0,0
item: red_wool
- name: Blue
color: 0,0,255
item: blue_wool
The config snippet from above contains the configuration for the Red and Blue teams. These include the item to represent the team, the color of the team (to be used in text), and the plain name of it.
Permissions
BattleArena Command Permissions
This contains permissions for the /battlearena (or /ba) command. These are not tied to a specific arena.
Permission | Command |
battlearena.command.backups |
/battlearena backups |
battlearena.command.backup |
/battlearena backup |
battlearena.command.debug |
/battlearena debug |
battlearena.command.module |
/battlearena module |
battlearena.command.reload |
/battlearena reload |
battlearena.command.restore |
/battlearena restore |
battlearena.command.schedule |
/battlearena schedule |
battlearena.command.start |
/battlearena start |
battlearena.command.stop |
/battlearena stop |
battlearena.command.stopall |
/battlearena stopall |
Arena Command Permissions
These are permissions any Arena command executor will have.
Permission | Command |
battlearena.command.<arena>.advance |
/<arena> advance |
battlearena.command.<arena>.create | /<arena> create |
battlearena.command.<arena>.edit | /<arena> edit |
battlearena.command.<arena>.join | /<arena> join |
battlearena.command.<arena>.join.map | /<arena> join <map> |
battlearena.command.<arena>.list | /<arena> list |
battlearena.command.<arena>.kick | /<arena> kick |
battlearena.command.<arena>.leave | /<arena> leave |
battlearena.command.<arena>.team.join | /<arena> team join |
battlearena.command.<arena>.team.leave | /<arena> team leave |
battlearena.command.<arena>.team.list | /<arena> team list |
battlearena.command.<arena>.remove | /<arena> remove |
battlearena.command.<arena>.spectate | /<arena> spectate |
Additional Resources
Item Syntax
BattleArena has an item format that is used for creating items in config. A few examples of where this format is used is in the Classes module, as well as for the Give Item Action, among other places.
Item Options
Name |
Description |
Type |
color |
The color of the item, mainly for leather armor, banners, etc. |
Color: - #<hex> or <rrr,ggg,bbb> |
custom-model-data |
The custom model data to use. |
<number> |
damage |
How much damage (or durability) should be applied to the item. |
<number> |
display-name |
The display name of the item (supports MiniMessage). |
<string> |
enchants |
Enchants to put on the item. |
Enchantment list: - [<enchant name>:<amount>...] |
item-flags |
The item flags to apply. See ItemFlag. |
Item Flag list: -[<item flag name>...] |
lore |
The lore of the item (supports MiniMessage). |
Lore list: [<line>...] |
amount |
How amount of the item. |
<number> |
unbreakable |
Whether the item is unbreakable. |
<true|false> |
effects |
The potion effects to apply to the item. |
Potion effect list: - [<potion effect>...] |
Single-line Format
This is the most common use of items in BattleArena, and follows a very similar format to that seen in the Action Reference. Note that options are separated using the semicolon (;).
Note: Custom items from third party plugins can also be used. See this page for more information.
Examples:
items:
- stone{amount=32}
- bow{unbreakable=true}
- arrow{amount=64}
- diamond_sword{display-name=<yellow>Mob Slayer;lore=[Kills every mob in it''s way!];enchantments=[sharpness:10]}
Configuration Node Format
While less common, this format may be seen to represent items as well. Rather than the item properties existing on a single line, they are defined over a configuration node. Here is an example of how that may look:
my-item:
item: golden_apple
amount: 32
display-name: Yummy Apple
lore:
- Legends say this apple is delicious!
- Try it for yourself!
Time Format
In many places in BattleArena, a duration is specified a configuration option. Time durations are abbreviated and multiple can be chained together.
Duration Abbreviations
- y: Years
- M (uppercase): Months
- w: Weeks
- d: Days
- h: Hours
- m (lowercase): Minutes
- s: Seconds
Examples
phases:
countdown:
...
countdown-time: 1m30s # 1 minute 30 seconds
victory:
...
duration: 5s # 5 seconds
Potion Effect Format
BattleArena has an potion effect format that is used for in both creating items and applying effects to players.
Effect Options
Name |
Description |
Type |
duration |
The amount of time (in ticks) to apply the effect for. |
<number> |
amplifier |
How strong the effect is. |
<number> |
ambient |
Whether the effect is ambient (less intrusive) |
[true|false] (default: false) |
particles |
Whether the effect should show particles or not. |
[true|false] (default: true) |
Examples
events:
on-start:
- give-effects{effects=[speed{duration=300;amplifier=1},jump_boost{duration=300;amplifier=2}]}
...
events:
on-respawn:
- give-item{item=splash_potion{effects=[speed{duration=300;amplifier=1}]}}
Custom Effect Format
BattleArena has support for custom effects in a few places that are primarily cosmetic.
Particle
Name |
Description |
Type |
particle |
The name of the particle. See Particle. |
<Particle> |
speed |
The speed of the particle. |
<number> |
count |
The number of particles to display. |
<number> |
offset |
The offset of the particle. |
Position: <x,y,z> |
data |
The data for the particle. |
Will vary for each particle (i.e. item_crack will use Item) |
Firework
Name |
Description |
Type |
firework-type |
The type of firework to display. See FireworkEffect.Type. |
<FireworkEffect.Type> |
flicker |
Whether the firework should flicker. |
<true|false> |
trail |
Whether the firework should have a trail. |
<true|false> |
colors |
The colors of the firework. |
Color list: - [#<hex>...] |
fade-colors |
The colors the firework should fade to. |
Color list: - [#<hex>...] |
Freeze
Name |
Description |
Type |
duration |
How long to freeze the player for. See Time Format. |
<Duration> |
radius |
In what radius players should be frozen for, if applicable. |
<number> |
Single-line Format
This is the most common use of effects in BattleArena, and follows a very similar format to that seen in the Action Reference. Note that options are separated using the semicolon (;).
Examples:
effects:
- particle{particle=flame;speed=0.01;count=15;offset=0.3,0.7,0.3}
- freeze{duration=5s}
Configuration Node Format
While less common, this format may be seen to represent effects as well. Rather than the effect properties existing on a single line, they are defined over a configuration node. Here is an example of how that may look:
my-effect:
firework-type: ball
flicker: true
trail: false
colors:
- "#fcba03"
- "#fcba03"
fade-colors:
- "#878378"
Plugin Integrations
Integrations with third party plugins to extend BattleArena functionality.
Placeholder API
Within BattleArena, there is support to display arena info through a plugin called PlaceholderAPI. If you are unfamiliar with the plugin, it allows for you to show information with certain placeholders (e.g. %player_name% will return the player name) in plugins that have support for PlaceholderAPI. An example usage of this is displaying the number of players in a competition on a hologram through PlaceholderAPI.
Placeholders
These are the placeholders for BattleArena. They are split into three sections: general placeholders, map placeholders and competition placeholders. General placeholders are not tied to a specific competition and show general information about arenas. Map placeholders pull information from a specific map. Competition placeholders will only resolve for players in a competition and will vary from player to player depending on which competition they are in.
General Placeholders
These placeholders show statistics for the arena specified. This information will look the same to each player seeing it in-game. <arena> is a placeholder for the arena to display information on (i.e. arena, battlegrounds, skirmish, etc.)
- %ba_<arena>_active_competitions%: Displays the number of active competitions for this arena type.
- %ba_<arena>_online_players%: The number of online players (alive & spectator) across all competitions of this arena type.
- %ba_<arena>_alive_players%: The number of alive players across all competitions of this arena type.
- %ba_<arena>_spectators%: The number of alive players across all competitions of this arena type.
- %ba_<arena>_waiting_competitions%: The number of waiting competitions for this arena type.
- %ba_<arena>_ingame_competitions%: The number of ingame competitions for this arena type.
Map Placeholders
These placeholders show statistics for the arena and map specified. This information will look the same to each player seeing it in-game. <arena> is a placeholder for the arena to display information on (i.e. arena, battlegrounds, skirmish, etc.), and <map> is the name of the map.
- %ba_<arena>_map_<map>_arena%: The name of the arena that the competition belongs to (i.e. Arena, Skirmish, etc.)
- %ba_<arena>_map_<map>_alive_players%: The number of alive players in the competition.
- %ba_<arena>_map_<map>_online_players%: The number of online players (alive & spectator) in the competition.
- %ba_<arena>_map_<map>_map%: The name of the map this competition is taking place in.
- %ba_<arena>_map_<map>_max_players%: The maximum players that can play in this competition.
- %ba_<arena>_map_<map>_spectators%: The number of spectators in the competition.
- %ba_<arena>_map_<map>_phase%: The phase this competition is currently in (i.e. waiting, countdown, etc.)
- %ba_<arena>_map_<map>_time_remaining%: The time remaining for the competition (i.e. 4 minutes)
- %ba_<arena>_map_<map>_time_remaining_short%: The time remaining for the competition with a shorter format (i.e. 00:04)
- %ba_<arena>_map_<map>_remaining_start_time%: The amount of time until the competition starts (only resolves during the countdown phase)
Competition Placeholders
These placeholders resolve for the current competition the player is in.
- %ba_competition_arena%: The name of the arena that the competition belongs to (i.e. Arena, Skirmish, etc.)
- %ba_competition_alive_players%: The number of alive players in the competition.
- %ba_competition_online_players%: The number of online players (alive & spectator) in the competition.
- %ba_competition_map%: The name of the map this competition is taking place in.
- %ba_competition_max_players%: The maximum players that can play in this competition.
- %ba_competition_spectators%: The number of spectators in the competition.
- %ba_competition_phase%: The phase this competition is currently in (i.e. waiting, countdown, etc.)
- %ba_competition_team%: The team the player belongs to in this competition.
- %ba_competition_team%: The team the player belongs to in this competition.
- %ba_competition_team_color%: The hex color of the team the player belongs to in this competition.
- %ba_competition_team_color_legacy%: The legacy (section symbol) color of the team the player belongs to in this competition.
- %ba_competition_team_name_formatted%: The formatted name of the team the player belongs to in this competition.
- %ba_competition_team_name_formatted_legacy%: The legacy (section symbol) formatted name of the team the player belongs to in this competition.
- %ba_competition_time_remaining%: The time remaining for the competition (i.e. 4 minutes)
- %ba_competition_time_remaining_short%: The time remaining for the competition with a shorter format (i.e. 00:04)
- %ba_competition_remaining_start_time%: The amount of time until the competition starts (only resolves during the countdown phase)
Custom Items
BattleArena has support for a number of plugins with custom items. This means that anywhere an item can be defined, if one of these plugins is installed, you can use an item from there.
Plugins Supported
- QualityArmory
- Oraxen
- ItemsAdder
- MythicCrucible
- Magic
- MMOItems
- Contains support for defining MMOItem type, level and tier
- Example: mmoitems:epic_sword{type=sword;level=5;tier=rare}
- WeaponMechanics
Defining Items
In order to use items from these plugins, the same format of <namespace>:<key> for Minecraft items is used, with the namespace being the lowercase name of the plugin. For example:
- oraxen:emerald_bow - Gets an emerald bow from Oraxen
- qualityarmory:blaster - Gets a blaster from QualityArmory
- minecraft:iron_sword - Gets an iron sword from vanilla Minecraft