Bukkit

Examples

To start with, look at the default configuration file. It has some examples that you may find useful.

Note that the above is tuned for 2.4.0 or 2.3.0 (or Minecraft 1.3.1). For 2.2.4 and below, use these instead:

Tutorial

Click for a tutorial with examples

Top level settings

Multiplier

This is the global experience multiplier. All experience drops, including the vanilla mob experience, will increase or decrease by this factor. To increase drops by X%, set the multiplier to 1 + X/100. For 50% this is 1 + 50/100 = 1.5

multiplier: 1.5

Default Rewards Disabled

When this is set to TRUE, all mob experience not specified under mobs will be set to zero. This is useful if you want to completely change the experience system.

Reward Type

Select the default method of rewarding players.

Economy Drop

Sets the item to drop when awarding currency. Remove it if you want to give currency directly.

Economy Drop Worth

The value of each currency item.

Virtual Scan Radius

When using the VIRTUAL reward type, experience will only be granted automatically for actions that can be directly traced to the player. Mobs that die from traps will instead drop experience orbs if there are other players within this radius.

Default Channels

The default channel(s) to use when sending messages. If you're not using HeroChat, set this to "global".

Maximum Enchant Level

The amount of experience levels needed to receive the highest possible enchantment. The default level is 30.

Maximum Bookcase Count

The amount of books needed for an enchantment table to select the highest possible enchant level at the bottom slot. Default value is 15 bookcases, with a maximum of 255 bookcases. You must continue to build the walls of bookcases upwards for them to count.

Global Settings

These settings can be found in the file global.yml.

Max Blocks in History

This is the maximum number of block changes to store in memory. This history, along with data from LogBlock or HawkEye, is used to prevent players from getting experience illegitimately, i.e. from ore they themselves have placed. Default is 5000 changes.

Max Age in History

This is the maximum number of seconds to keep a block change in memory. The default is 10 minutes - after that, the mod will resort to looking up the block history in a database such as LogBlock.

Use Metrics

Whether or not to transmit anonymous usage data and general statistics. In addition to what MCStats is usually sending, the following is also included:

• Whether or not ExperienceMod is connected to LogBlock, HawkEye, HeroChat, Vault or ExperienceBridgeMod.
• The number of errors/warnings encountered since last reload.

You can opt-out from sending this data either by setting "use metrics" to false or setting "opt-out" in PluginMetrics to true.

Use AutoUpdate

Whether or not to automatically check BukkitDev for a new version on server startup, and then every three hours after that.

Use Permissions

Whether or not to use a permissions mod.

If this is disabled, all users will automatically be granted everything but the admin, untouchable and info-permissions, which are reserved for operators (users in ops.txt).

Disable Services

Any service with a name on this list will be disabled.

Mobs Section

Example:

mobs:
  ?: 0
  ?|fall: 5
  zombie: 10

Mobs are matched by attributes using the following syntax (the rule body):

name|damage_cause|size|wither|spawner|baby|tamed:
  experience

The different mob attributes:

An attribute, like name, can either be set to a value, or left blank with a question mark. Some attributes have no index - that means the order they're written in is irrelevant as long as they placed after (to the right) of all the attributes with indexes.

Player Death Section

Example:

player death:
  # Special people
  notch: TOTAL_EXPERIENCE
  player: 0

  # Groups
  ?|vip: min(TOTAL_EXPERIENCE * 0.5, 255)
  ?|member: min(TOTAL_EXPERIENCE * 0.2, 255)
  ?|guest: [20, 40]

  # Experience reduction from damage types
  ?|?|projectile:
    multiplier: 0.75
  ?|?|magic:
    multiplier: 0.5

  # Don't give experience when killed by the environment
  ?|?|?|!murder: 0

Players are matched with a syntax that's similar to mobs:

name|group|damage_cause|[murder]

The different attributes are as follows:

In addition, you may use the following variables when defining the amount of resources awarded:

You can also define the rewards with arbitrary mathematical expressions (+, -, *, /, ^) - for instance, in the example above, I multiplied the TOTAL_EXPERIENCE by 0.5 for VIPs, making them drop half their total experience when they're killed. In addition, I used the "min"-function to limit the experience drop to 255.

A full list of every available function can be found on this page.

Items Section

Example:

items:
  coal ore:
    block source: 5
  redstone ore:
    block source: 20
  glowing redstone ore:
    block source: 20
  diamond ore:
    block source: 150
  mob spawner:
    bonus:
      first: 250
      last: 1000
  iron ingot:
    smelting result: [3, 9]

The syntax for matching regular items are as follows:

name|data value:
  trigger: 
    experience

The different mob attributes:

However, name can also be a block ID, such as 46 for TNT. This is necessary if you want to match non-standard blocks, such as custom blocks from Technic Pack.

Multiple triggers for the same block type MUST be placed within the same query:

items:
  stone:
    block source: 1
    smelting result: 1

A list of every item and its name can be found here. For certain items it is possible to use a name instead of a number to match certain data values:

Notice that you must specify the experience on the result of the smelting, ect. an iron ingot, whilst mined blocks must be specified on the block type, not the dropped material.

The different actions (or triggers) are as follows:

These rewards are triggered regardless of the history of a particular block or item. Generally, players will be able to gain experience from blocks they have placed themselves, but it's easy to prevent for ore blocks. Just use block instead of bonus, which disables experience from silk-touch pickaxes, or smelting if this doesn't make a difference (for iron or gold ores).

Experience

The amount of experience is either an integer, a real number or a range of numbers:

items:
  diamond ore:
    block source: 10
  stone:
    block source: 0.1 #  10% probability of giving 1 experience
  coal ore:
    block source: [3, 5]  # Range

You can also use first and last to set a range. The difference is only in esthetics:

items:
  coal ore:
    block source:
      first: 3
      last: 5

Cost or Penalty

If you're using the virtual or economy reward types, it's also possible to make certain actions cost resources. For instance, you can make placing TNT cost 5 experience:

items:
  tnt:
    placing result: -5

You could also refund this cost if the player picks up the TNT instead of blowing it up

items:
  tnt:
    placing result: -5
    bonus source: 5

Item Drops

You can also add to the list of items that are usually dropped from blocks or mobs. This is acheived by using the drops reward:

# Simulate the gold rush!
items:
  clay:
    block source:
      drops:
        gold nugget: 0.1

Currently, this will only add additional items to the default drop list, and never replace it. Preventing gravel from dropping flint, for instance, is thus not yet possible, but it's on the TODO list for a future version.

Potions

Example:

items:
  potion|?|1|!splash|!extended:
    brewing result: 20
  potion|instant heal|1|!splash|!extended:
    brewing result: 50

The syntax is as follows:

potion|potion_type|level|extended|splash:
  brewing result:
    experience

The different potion type attributes that can be matched:

Matching Multiple Attributes

You can match multiple attributes at once with comma:

items:
  glowing redstone ore, redstone ore::
    block source: 20

This also works for potions:

items:
  potion|instant heal, instant damage, regen, speed|1|!splash|!extended:
    brewing result: 50

Player Section

This section contains reward for activities that doesn't fit anywhere else, such as fishing.

Fishing Success

The amount of experience to grant when a player successfully catches a fish.

player:
  fishing success: [3, 5]

Fishing failure

The amount of experience to be awarded even when a player fails to catch a fish.

player:
  fishing failure: 0

Multiple Rewards

You can have multiple reward types at the same time. The following will give 10 exp and 10 currency for mining redstone ore.

items:
  redstone ore:
    block source:
      virtual: 10
      economy: 10
      message: '{player} has found redstone!'
      channels: [global]

Sending Messages

Starting from 2.0.0, it's possible to set a message that will be broadcasted when a player is awarded experience. Alternatively, the message can be transmitted on a set channel (like local), to not unnecessarily spam the server when someone is mining coal. Note that currently this is only possible if your server is using HeroChat, but that might change in the future.

The syntax is relatively simple. Add the message (and an optional channel list) to everywhere you award experience and want to broadcast a message:

items:
  diamond:
    block source:
      experience: [100, 150]
      economy: 50
      message: '{player} has found a diamond and got {experience} experience and currency!'
      channels: [global]
  coal ore:
    block source:
      default: 10
      message: '{player} mined some coal.'
      channels: [local]

In the above example we've decided to broadcast the diamond find to the entire server, while coal is simply sent to the local channel (which might have a range of say 100 meters). We've also given 50 currency in addition to the experience. Note that coal uses a default reward - this means you can easily change the reward type of every item by setting "reward type" at the root.

The possible properties for item and mob rewards is as follows:

Channels are either referring to HeroChat channels, if HeroChat is enabled, or the following built-in channels:

It's also possible to reference certain values in the message:

Presets

Presets allow you to set a different configuration file per user. The following is an example of a presets.yml file:

# default for all worlds
?:
  local:
    multiplier: 1
    items:
      diamond:
        block source: 5   
 
# default for every user in world1
?|world1:
  file: defaultForWorld1.yml
 
# preset for every VIP member
vipPreset:
  file: vip.yml
 
# you can also combine files
adminPreset:
  file: vip.yml
  file: admins.yml

After that, you can associate each preset with a particular user or group. Here using PremissionsEx:

groups:
  vip:
    permissions:
    # ect.
    options:
      experiencePreset: vipPreset
     
  admins:
    permissions:
      - '*'
    options:
      experiencePreset: adminPreset

In 2.5.0, it's also possible to use a more specific multiplier that only applies to certain blocks. The following preset uses the "vip.yml" preset for all users in world 2, but with every block source reward increased by 300%. Every other reward is untouched.

?|world2:
  local:
    items:
      ?:
        block source:
          multiplier: 4
  file:
   - vip.yml

Levels

This section allows you to alter the amount of experience required to level up to the next level. For instance, to recreate the experience system in 1.2.5. in 1.3, use the following:

levels:
  0 - Infinity: floor(7 + 3.5*level)

If you instead want to use something similar to 1.3, start by modifying these formulas:

levels:
  0 - 15: 17
  16 - 29: 17 + (level - 15) * 3
  30 - Infinity: 62 + (level - 30) * 7

Or just set each level directly:

levels:
  # Level - Experience needed to level
  0: 17
  1: 17
  2: 17
  3: 17
  4: 17 
  5: 17
  6: 17
  7: 17
  8: 17
  9: 17
  10: 17
  11: 17
  12: 17
  13: 17
  14: 17 
  15: 17
  16: 20
  17: 23
  18: 26
  19: 29
  20: 32
  21: 35
  22: 38
  23: 41
  24: 44
  25: 47
  26: 50
  27: 53
  28: 56
  29: 59
  30 - Infinity: 62 + (level - 30) * 7