Setting up the config file

garbagemule edited this page Jan 26, 2015 · 70 revisions

On this page:

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
classes:
    Knight:
        items: diamond_sword, grilled_pork:2
        armor: 306,307,308,309
    Archer:
        items: wood_sword, bow, arrow:128, grilled_pork
        armor: 298,299,300,301
    [...]
arenas:
    default:
        settings:
            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.

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 nodes 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 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: 298,299,300,301
        permissions:
        - EffectiveArrows.use.*
        - -mobarena.use.leave
    Tank:
        items: iron_sword
        armor: 310,311,312,313
    Knight:
        items: '276'
        armor: iron_helmet, iron_chestplate, iron_leggings, iron_boots
    Wolf Master:
        items: stone_sword, grilled_pork, bone:2
        armor: 298,299,300,301
    Crusader:
        items: iron_sword, hay_block:17
        armor: 302,303,304,305
        price: $5

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: 310,311,312,313
        unbreakable-weapons: false
        unbreakable-armor: false

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: 298,299,300,301
        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

For every bone (Material name: bone, data value: 352) in a class' items-list (or class chest), one wolf pet will spawn 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: 298,299,300,301

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 in a bit string pattern similar to the UNIX file permissions. To calculate the item stack amount, use this tool. 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: 302,303,304,305

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 number-based.

  • 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.
  • logging: [true|false] - This setting is currently bugged, do not set to true! If true, at every arena end, relevant information about the arena session will be appended to a file plugins/MobArena/logs/<arena>.log. Note that there is no sort of limit on how big this file can become, so keep an eye on it.
  • entry-fee: [$<amount>|<item>:<amount>] - Follows the exact same notation as the class items and rewards (read the Item 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.
  • 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.
  • auto-equip-armor: [true|false] - If true, armor pieces will automatically be equipped upon class selection. Note that this does not work if a class has more than 1 of an armor piece type.
  • soft-restore: [true|false] - If true, all destroyed blocks will be saved in a "repair list", which will be used to restore blocks at arena end. No data is saved to the harddrive. Note that this setting, if true, ignores the protect flag.
  • 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.
  • hellhounds: [true|false] - If true, all pet wolves in the arena will be in flames! This has no actual function, and is purely for the cool-factor. Also useful for distinguishing enemy wolves and pet wolves.
  • 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.
  • 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-respawn: [true|false] - If false, players will be greeted with the typical death screen upon dying in the arena, and will have to click the respawn button to respawn. With this setting at false, players will actually die in the arena, meaning plugins like Heroes and mcMMO will properly trigger their resetting of internal data upon respawn.
  • 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.
  • first-wave-delay: <time> - The time (in seconds) before the first wave of monsters upon arena start.
  • 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.
  • keep-exp: [true|false] - If true, players will keep the experience they gather in the arenas after death. This is useful if you want to allow players to level up or gather experience in the arenas. NOTE: If using display-waves-as-level or display-timer-as-level, set keep-exp to false.
  • 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-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!
  • 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!
  • 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.
  • 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.
  • 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.
  • 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.

waves

Please go to 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 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 started. 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_spade, 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.