101 Setting up the config file

garbagemule edited this page 2024-02-02 22:44:50 +01:00

Table of Contents

• An Overview
• global-settings
• classes
• Bring your own items
• Slot-specific armor nodes
• Potion effects
• Price
• Unbreakable weapons/armor
• Per-class permissions
• Pet classes
• Pet names
• Mounts
• arenas
• settings
• waves
• rewards
• coords

On this page:

• Overview
• global-settings
• classes
  • Bring your own items
  • Slot-specific armor nodes
  • Potion effects
  • Price
  • Unbreakable items
  • Per-class permissions
  • Pet classes
  • Mounts
• arenas
  • settings
  • waves
  • rewards
  • coords

An Overview

Note: When editing the config-file, you MUST use spaces for indentation! Using tabs instead of spaces will give you errors!

The config-file, plugins/MobArena/config.yml, consists of 3 sections: global-settings, classes, and arenas. The default config-file that is generated when MobArena is first loaded looks something like this:

[...]
global-settings:
  update-notification: true
  enabled: true
  allowed-commands: /list
  prefix: '&a[MobArena] '
  pet-items:
    wolf: bone
classes:
  Knight:
    items: diamond_sword, potion:instant_heal:3
    armor: iron_helmet, iron_chestplate, iron_leggings, iron_boots
  Tank:
    items: iron_sword, potion:instant_heal:2
    armor: diamond_helmet, diamond_chestplate, diamond_leggings, diamond_boots
    effects: slow, health_boost
  [...]
arenas:
  default:
    settings:
      prefix: ''
      world: Tundra
      enabled: true
      protect: true
      clear-wave-before-next: false
      [...]
    waves:
      [...]
    rewards:
      [...]

Note about notation: [true|false] means the setting must be "true or false", either or. <time> means the setting must be an amount of time (in seconds or server ticks), always a whole number, and always 0 or greater. <amount> is similar to time.

global-settings

The global-settings are few, but important. Note that if enabled: false, no arenas can be joined, regardless of their individual enabled status.

• enabled: [true|false] - This determines if MobArena is enabled or not. If set to false, players will not be able to join any arenas at all, regardless of what the arenas' individual statuses are.
• update-notification: [true|false] - If true, MobArena will send a message to ops when they log on if a new version of MobArena is available.
• allowed-commands: <com1>, <com2>, ... - A comma-separated list of the commands that players are allowed to use while in the lobby and/or arena. This is useful if you don't want players to use teleport-commands, flying carpets, kill commands, etc. If you write the command WITH its forward-slash, the entire command and all "sub-commands" will be allowed. For instance, writing /kill will allow both /kill, /kill Sausageman22 and /kill Notch. Writing the command WITHOUT its forward-slash will allow only that specific command or "sub-command". Writing kill will thus ONLY allow /kill, but not /kill Sausageman22.
• prefix: <prefix> - The prefix MobArena uses for all of its messages. The default is the classic green [MobArena], but you can change it to whatever you want. You can override the prefix for specific arenas by using the arena-specific setting with the same name.
• pet-items - By default, bones are transformed to pet wolves. This section lets you add new pet types (note that only tameable entities behave as actual pets) or change the bones to something else.

I recommended leaving the update notifications on, and disabling commands like /kill and /tp.

classes

The classes-section is slightly more complicated. It is divided into class-branches, where each branch denotes the name of the class, and each branch has mandatory nodes items and armor, as well as optional slot-specific armor nodes and optional nodes effects, price, permissions, lobby-permissions, unbreakable-weapons, and unbreakable-armor.

Note: YAML is picky about how you type your items. Make sure you read the short Item and Reward Syntax-page and fully understand it before you attempt to modify the config file!

classes:
  Archer:
    items: wood_sword, bow, arrow:128, grilled_pork
    armor: leather_helmet, leather_chestplate, leather_leggings, leather_boots
    effects: speed
    permissions:
    - EffectiveArrows.use.*
    - -mobarena.use.leave
  Tank:
    items: iron_sword
    helmet: diamond_helmet
    chestplate: diamond_chestplate
    leggings: diamond_leggings
    boots: diamond_boots
    offhand: shield
    effects: slow, health_boost
  Knight:
    items: diamond_sword
    armor: iron_helmet, iron_chestplate, iron_leggings, iron_boots
  Wolf Master:
    items: stone_sword, grilled_pork, bone:2
    armor: leather_helmet, leather_chestplate, leather_leggings, leather_boots
    pet-name: 'Minion of <player-name>'
  Crusader:
    items: iron_sword, hay_block:17
    armor: chainmail_helmet, chainmail_chestplate, chainmail_leggings, chainmail_boots
    price: $5

To read about how to put enchantments on items please read the Item and Reward Syntax-page.

Bring your own items

MobArena allows you to just bring your own items into the arena via the implicit 'My Items' class. What this means is that if you just place a sign in the lobby with the text My Items, you'll get the items that you had before joining the arena. Items are still restored on dying in or leaving the arena.

For a smooth, own-items-only experience, ditch the signs and set the per-arena setting default-class to my-items.

Note: To prevent item smuggling/duping, MobArena removes Ender Chests, Ender Pearls, Shulker Shells, and Shulker Boxes from player inventories in the lobby. The items are not removed completely; they are still restored when players die in or leave the arena.

Slot-specific armor nodes

If you want to use off-hand items, or if you just want to be explicit about which items go where in the armor slots, use the optional slot-specific armor nodes: helmet, chestplate, leggings, boots, offhand. In the example above, the Tank class gets a shield in its off-hand slot along with full diamond armor from the other slot-specific nodes.

Potion effects

Classes can be enhanced with potion effects using the optional effects node. Available potion effects are listed in the PotionEffectType constants in the Bukkit API. The potion syntax is <effect>:<amplifier>:<seconds>. The amplifier and duration are optional, and will default to 0 (level 1) and pseudo-infinity, respectively. In the example above, the Archer class has the speed effect to make it more nimble, and the Tank class has the slow effect to match the weight of its heavy armor and the health boost effect to make him more beefy. All of these effects are level 1 and last "forever".

Price

The optional price node can be used to give classes a per-session price. When a player tries to pick a class that has a price, they will only be able to if they can afford it. The money is withdrawn when the arena starts, i.e. picking different priced classes in succession will not (necessarily) result in empty player wallets. In the example above, the Crusader class costs $5.

Unbreakable weapons/armor

The optional unbreakable-weapons and unbreakable-armor nodes can be used to toggle on or off the unbreakability of class items and armor. The nodes default to true, so they are really only necessary if you want to toggle OFF the feature, i.e. if you want items to deteriorate and break! If that's what you want, set the nodes to false.

classes:
  FrailTank:
    items: diamond_sword
    armor: diamond_helmet, diamond_chestplate, diamond_leggings, diamond_boots
    unbreakable-weapons: false
    unbreakable-armor: false

Note that items received from upgrade waves are not made unbreakable regardless of these flags.

Per-class permissions

Using the optional permissions-node, you can give classes special permissions to customize them even more. Each permission must be listed with a dash (-) in front of it. If you want a class to not have a permission, put a dash/minus at the very beginning of the permission node. In the example above, the Archer class will be able to use the EffectiveArrows plugin, but won't be able to use /ma leave (meaning it's impossible to leave the arena without dying).

classes:
  Archer:
    items: wood_sword, bow, arrow:128, grilled_pork
    armor: leather_helmet, leather_chestplate, leather_leggings, leather_boots
    permissions:
    - EffectiveArrows.use.*
    - -mobarena.use.leave

The optional lobby-permissions-node gives players special permissions while they are in the lobby after they have picked a class. This feature can be used e.g. in combination with a shop plugin and a base class that perhaps has nothing (maybe except for a few potions).

classes:
  Basic:
    items: ''
    armor: ''
    lobby-permissions:
    - shop.buy

Pet classes

By default, every bone in a class' items-list (or class chest) is transformed to a wolf pet upon arena start. In the example above, every player that picks the Wolf Master class will have 2 wolves spawn upon arena start. The wolves are invincible, but deal less damage than normal wolves.

classes:
  Wolf Master:
    items: stone_sword, grilled_pork, bone:2
    armor: leather_helmet, leather_chestplate, leather_leggings, leather_boots
    pet-name: 'Minion of <player-name>'

You can add more pet types or change the bone to a different item in global-settings.

Pet names

The optional pet-name node can be used to change pet names from the default value of <player-name>'s pet. In the example above, the wolves will be named Minion of garbagemule for a Wolf Master named garbagemule.

The template supports two variables: <player-name> and <display-name>.

Note: YAML uses the single quote character (') to denote the start and end of strings. To use a single quote in the template, it must be escaped by using a backslash (\), e.g. <player-name>\'s friend.

Mounts

To give a class a horse mount, give it a hay block in the items-list (or place a hay block in the class chest). The item stack amount (in the first encountered stack) determines the variant and barding of the horse. You can use this table to figure out which hay block amount you need for your desired variant and barding:

	None	Iron	Gold	Diamond
Horse	1	9	17	25
Donkey	2	-	-	-
Mule	3	-	-	-
Skeleton	4	-	-	-
Zombie	5	-	-	-

Note that only normal horses can have barding.

In the example above, every player that picks the Crusader class will have a white horse with gold barding upon arena start. The mounts are invincible.

classes:
  Crusader:
    items: iron_sword, hay_block:17
    armor: chainmail_helmet, chainmail_chestplate, chainmail_leggings, chainmail_boots

arenas

This section is by far the largest, and it is divided into several smaller branches. In the above example, default denotes the name of the default arena. This name can be altered, but it must contain no spaces (use underscores instead). The arena name is significant when a server has multiple arenas and no Master Lobby (will be featured later). Let's go over the different branches:

settings

The settings-branch is quite extensive, and besides the world-node, it is basically just a bunch of toggles (on/off, true/false), though a few are special.

• prefix: <prefix> - An arena-specific prefix to use for messages/announcements in this arena only. The default is the empty string (''), which means the global-settings prefix will be used.
• world: <name> - The name of the world the arena resides in.
• enabled: [true|false] - If false, players cannot join the arena.
• protect: [true|false] - If false, the arena will not be protected from explosions and players breaking the blocks.
• entry-fee: [$<amount>|<item>:<amount>] - Follows the exact same notation as the class items and rewards (read the Item and Reward Syntax-page). $20 will subtract 20 of whatever currency you use from the players upon joining. $5, stick:2 will require the player to have 5 currency units and 2 sticks to join the arena. The entry-fee will be refunded if the player leaves before the arena starts.
• default-class: <class> - If non-empty, this class is automatically assigned to players when they join the arena. The class name must be all lowercase and with no spaces. If used in combination with auto-ready: true, it is necessary to also set a start-delay-timer to prevent the arena from starting immediately when the first player joins.
• clear-wave-before-next: [true|false] - If true, no monsters will spawn before all monsters of the previous wave have been killed.
• clear-boss-before-next: [true|false] - If true, no new waves will spawn before the current boss (if any) is dead.
• clear-wave-before-boss: [true|false] - If true, a boss wave will not spawn until all previous monsters have been killed.
• clear-wave-leeway: <amount> - The amount of mobs allowed to be alive before a wave is considered "cleared" when using the clear-wave-before-next and/or clear-wave-before-boss flags. Also affects final-wave.
• soft-restore: [true|false] - If true, blocks in the arena can be destroyed during a session, but all destroyed blocks will be saved in a "repair list", which will be used to restore the blocks at arena end. Note that the protect flag must also be true for this feature to work.
• soft-restore-drops: [true|false] - If true, blocks destroyed by players will drop as items like they normally do (using pickaxes, spades, etc.). Note that this makes it very easy for classes with pickaxes to "mine the arena" and build forts.
• require-empty-inv-join: [true|false] - If false, players' inventories will be saved upon joining, and restored upon death/leaving.
• require-empty-inv-spec: [true|false] - If false, players can spectate the arena without having to empty their inventories.
• pvp-enabled: [true|false] - If true, players can damage each other in the arena.
• monster-infight: [true|false] - If false, monsters will no longer damage each other.
• allow-teleporting: [true|false] - If false, all warping to and from the arena region is blocked. Useful for preventing players from summoning other players into the arena for help.
• monster-teleporting: [true|false] - If false, monsters such as Endermen cannot teleport around in the arena region. Note that this also allows monsters to teleport to unreachable areas, if any, in the arena region.
• spectate-on-death: [true|false] - If false, players will not get warped to the spectator area, but instead be "kicked" from the arena (essentially a forced /ma leave).
• auto-leave-on-end: [true|false] - If true, players waiting in the spectator area will automatically leave (as if they ran /ma leave) when the arena session ends.
• share-items-in-arena: [true|false] - If false, players will not be able to drop items in the arena.
• min-players: <amount> - Gives a lower limit on how many players are required to start the arena. The default of 0 is the same as 1, which means 1 or more players may start the arena. Note that this feature is incompatible with auto-start-timer and start-delay-timer!
• max-players: <amount> - Gives an upper limit on how many players may join the arena. The default of 0 means no limit.
• max-join-distance: <distance> - The maximum distance (in blocks) from which players can join or spectate the arena. If 0 (default), there is no limit, and players can join from any world. Note that the distance is calculated from every corner of the arena region, and that players not in the arena world won't be able to join or spectate.
• join-interrupt-timer: <time> - Delay (in seconds) between typing a join/spec command and the command actually executing. If a player moves or takes damage during this delay, the command is interrupted, and the player will not join/spec the given arena. This should help prevent exploits on PvP servers.
• first-wave-delay: <time> - The time (in seconds) before the first wave of monsters upon arena start.
• next-wave-delay: <time> - The time (in seconds) before the next wave of monsters spawns. Note that if wave-interval: 20 and next-wave-delay: 5, there will always be at least 25 seconds between each wave.
• wave-interval: <time> - The time (in seconds) between each new wave of monsters. If clear-wave-before-next: true, this setting will be ignored.
• final-wave: <number> - The number of the final wave before the arena is force ended. This is useful if you want to set a cap on how many waves an arena will have.
• monster-limit: <amount> - The maximum amount of monsters MobArena is allowed to spawn for this arena. The next wave, if any, will not spawn until there is room for more monsters.
• monster-exp: [true|false] - If true, monsters will drop experience orbs. This is useful if you wish to give players the ability to spend the gathered experience on enchants or something else (using different plugins) during the session.
• food-regen: [true|false] - If true, a full food bar will cause players to regenerate health while in the arena. Note that this potentially makes tank-like classes extremely overpowered, since diamond armor (by default) coupled with a full food bar will make a player very hard to kill.
• lock-food-level: [true|false] - If true, the food bar will be locked for all players in the arena, meaning they will not end up starving, and they will be able to sprint around as they please.
• player-time-in-arena: <time of day> - When set to anything but world, this setting will freeze the apparent world time for players in the arena to whatever value you set. This is useful for making time-of-day themed arenas (e.g. constant night time for a cemetery, broad daylight for a pirate ship). Valid values are: dawn, sunrise, morning, midday, noon, day, afternoon, evening, sunset, dusk, night, midnight.
• auto-ignite-tnt: [true|false] - If true, TNT will be automatically ignited when placed. This is useful for preventing Oddjob-like classes from forting.
• auto-ignite-fuse: <number> - The time (in ticks) before an auto-ignited TNT block explodes after being placed.
• auto-start-timer: <time> - The time (in seconds) before the arena will be force started after the first player has joined the lobby (the default of 0 means deactivated or infinite time). Non-ready players will be removed from the lobby. This setting is useful to prevent ill-minded players from delaying or preventing other players from starting the arena. Note that this feature is incompatible with min-players!
• start-delay-timer: <time> - The time (in seconds) before the arena can be started after the first player has joined the lobby. This setting is useful if you want to give your players a fixed window of time to join the arena after the first player has joined, so they can't just start it off right away. Note that this feature is incompatible with min-players!
• auto-ready: [true|false] - When set to true, players are automatically flagged as ready when they pick a class. Useful for arenas with many players where hitting an iron block becomes difficult. If used in combination with a default-class, it is necessary to also set a start-delay-timer to prevent the arena from starting immediately when the first player joins.
• use-class-chests: [true|false] - When set to true, MobArena will try to use Class Chests in this arena when available. Otherwise, it will only use the class configuration from the config-file.
• arena-warp-offset: <radius> - A radius (in blocks) around the arena warp in which players can spawn. If set to a value greater than 0, MobArena will randomize the exact arena warp location for each player. This can help prevent suffocation damage when many players join an arena together.
• boss-health-bar: [boss-bar|title|name|none] - Shows a boss health bar. If set to boss-bar on 1.11+, a boss bar like the one for ender dragons and withers is used. If set to title, the Chapters/Titles API is used to show the health as a bar of colored pipe symbols (||||) on every hit. If set to name, the colored pipe symbols appear as the name of the boss. none disables the boss bar.
• display-waves-as-level: [true|false] - When set to true, the players' level counter (above the experience bar) will be used to display the current wave number. If the wave announcements in the announcements-file are silenced, this can be used to make a much less "spammy" MobArena experience. NOTE: Do not use this if keep-exp is set to true!
• display-timer-as-level: [true|false] - When set to true, the players' level counter (above the experience bar) will be used to display the auto-start timer in the lobby. NOTE: Do not use this if keep-exp is set to true!
• use-scoreboards: [true|false] - Whether to use scoreboards in MobArena or not.
• isolated-chat: [true|false] - When set to true, all chat messages sent by arena players will be seen only by other arena players in the same arena. The arena players will still be able to see chat messages from other players on the server who aren't in an arena.
• announcer-type: [title|chat] - Announce arena messages such as wave spawns, player deaths, and boss abilities either as titles or in the chat window.
• global-join-announce: [true|false] - When set to true, MobArena will announce the arena-join-global message (see Announcements) to all players on the server when the first player joins an arena.
• global-end-announce: [true|false] - When set to true, MobArena will announce the arena-end-global message (see Announcements) to all players on the server when an arena ends.
• show-death-messages: [true|false] - When set to true, MobArena will announce death messages. When set to false, death messages for arena players are disabled.

waves

Please see Setting up the waves for more information.

rewards

The rewards-section denotes which rewards the arena players can win in the arena. It uses the exact same item system as the classes-section does, so nothing new there. You can also specify monetary rewards if you use a major economy plugin (iConomy, BOSEconomy, Essentials Eco) in the notation $<amount>.

Note: YAML is picky about how you type your items. Make sure you read the short Item and Reward Syntax-page and fully understand it before you attempt to modify the config file!

The waves-branch is broken into every- and after-branches. The every-branch denotes rewards that the players can receive every x waves (repeated). The after-branch denotes rewards that the player can receive after wave x (only once) has "ended", i.e. right before the next wave spawns, or right before the session ends if wave x is the final wave. Note that only one reward is picked at random from the list.

In the following example, players will receive either four arrows or a gold bar every 3 waves (3, 6, 9, 12, etc.), and a diamond every 10 waves (10, 20, 30, etc.), as well as an iron tool on wave 7 (only on wave 7), a diamond sword on wave 19 (only on wave 19), and 200 currency units on wave 20:

rewards:
  waves:
    every:
      '3': arrow:4, gold_ingot
      '10': diamond
    after:
      '7': iron_shovel, iron_hoe, iron_axe, iron_pickaxe
      '19': diamond_sword
      '20': $200

Note: The wave numbers must be enclosed by apostrophes (e.g. '7':, not 7:), or YAML will throw errors. If you aren't sure how to do it, just copy one of the other lines and change the wave number and the items.

coords

The coords-section does not exist when MobArena first generates the config-file. This is because the coordinates need to be set by the user in-game. See the in-game section for more details on how to set everything up. The coords-section consists of five key points, and an arbitrary amount of spawnpoints:

• p1 and p2 - These two points should span the entire arena region (including spectator areas and the lobby associated with the arena, if possible).
• l1 and l2 - [OPTIONAL] If the lobby can't properly reside within the arena region for some reason, these two points should span the lobby region.
• arena - This warp is where the players will be teleported upon arena start.
• lobby - Where the players will be teleported upon joining the arena.
• spectator - Where the players will be teleported upon death or spectating.
• spawnpoints - A list of points where monsters can spawn from.

Note that editing these points manually can have some very unhappy consequences. Always edit these points from within Minecraft to ensure that they are generated properly.