Skip to main content

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.

Back to top