Bukkit

The node general contains the basic configuration options, like what ID and DataValue to use for Keys and Lockpicks and how the items should be named. The option LockPickBreakChance configures a percentual chance for lockpicks to break if the user fails at picking the right cylinder. 0.0 means 0%, 1.0 means 100%, 0.42 means 42% and so on. LockPickBreakChanceRate determines the rate the LockPickBreakChance gets reduced per level of the player. This reduction cannot bring the break chance under the value defined in LockPickMinBreakChance.

general:
  KeyID: 369
  KeyDV: 1
  KeyName: 'Key'
  LockPickID: 280
  LockPickDV: 1
  LockPickName: 'Lock Pick'
  LockPickBreakChance: 0.3
  LockPickBreakChanceRate: 0.01
  LockPickMinBreakChance: 0.05

The locks part is more interesting, here you can set up your locks. just add a new subnode (be sure to use a unique name) and adjust your values. LockID is the id of the item which will represent the lock later LockDV is the datavalue of the item which will represent the lock later LockName is the display name of the item which will represent the lock later Difficulty sets the amount of cylinders in your lock. If it is set to 6 the lock can only be opened with a key. RecipeShape determines the shape of your recipe, add up to 3 lines with a maximum of 3 characters per line. RecipeIDs sets the material ID for the characters you used in RecipeShape. The plugin will not work and will throw an error if now all characters are mapped!

locks:
  basic1:
    LockID: 265
    LockDV: 1
    LockName: 'Basic Lock'
    Difficulty: 1
    RecipeShape:
    - BI
    RecipeIDs:
      I: 265
      B: 42
  basic2:
    LockID: 265
    LockDV: 2
    LockName: 'Advanced Lock'
    Difficulty: 2
    RecipeShape:
    - IBI
    RecipeIDs:
      I: 265
      B: 42
  basic3:
    LockID: 265
    LockDV: 3
    LockName: 'Strong Lock'
    Difficulty: 3
    RecipeShape:
    - ' I '
    - IBI
    - '   '
    RecipeIDs:
      I: 265
      B: 42
  basic4:
    LockID: 265
    LockDV: 4
    LockName: 'Tough Lock'
    Difficulty: 4
    RecipeShape:
    - ' I '
    - IBI
    - ' I '
    RecipeIDs:
      I: 265
      B: 42
  basic5:
    LockID: 265
    LockDV: 5
    LockName: 'Fine Lock'
    Difficulty: 5
    RecipeShape:
    - III
    - IBI
    RecipeIDs:
      I: 265
      B: 42
  master:
    LockID: 266
    LockDV: 6
    LockName: 'Masterful Lock'
    Difficulty: 6
    RecipeShape:
    - III
    - IBI
    - III
    RecipeIDs:
      I: 266
      B: 41

The locks set up in the configuration are just the locks which are possible to craft! If you change them your old locks will still work. Hooray!

Events are a new feature in v1.0.1.0. They allow to add commands or messages to the process of lock picking. This could come in handy to give the player experience for successfully opening locks.

Events are defined like this:

_name_:
  event: fail|success
  permission: some.permission.which.is.needed
  action: player-message|server-message|player-command|server-command
  payload: 'your message or command to run'

_name_ must be any unique one-word name, its just for your convenience to better remember which is which

event can be either 'fail' to trigger every time when the player lifts the wrong cylinder, or 'success' to trigger when the player successfully picked the lock

permission can be any permission. The event will only trigger for players who have this permission, if you don't want to use a permission just set it to some basic permission every player posesses.

action can be either 'player-message' for a direct message to the player, 'server-message' for a broadcasted message, 'player-command' for a command which is ran from the player or 'server-command' for a command which is ran by the console.

payload is the message or command which is sent. The first '/' of commands must be omitted. <player> will be replaced by the name of the player and <lock> will be replaced by the name of the lock.

Currently only the two events 'success' and 'fail' are available, more will most likely be added in the future.

The default configuration of events is like this:

events:
  fail1:
    event: fail
    permission: player.fail.kick
    action: server-command
    payload: 'kick <player>'
  fail2:
    event: fail
    permission: shame.on.me
    action: player-command
    payload: 'me failed to pick a <lock>'
  success1:
    event: success
    permission: winning.at.picking
    action: player-message
    payload: 'congrats to your success!'
  success2:
    event: success
    permission: broadcast.my.win
    action: server-message
    payload: '<player> successfully picked a <lock>'

Since v1.0.1.1 all messages are fully configureable, just change the values in the 'messages' section. If you get empty messages you need to add the following values to your configuration:

messages:
  level-1-perm: 'This lock is to difficult for you!'
  level-2-perm: 'This lock is to difficult for you!'
  level-3-perm: 'This lock is to difficult for you!'
  level-4-perm: 'This lock is to difficult for you!'
  level-5-perm: 'This lock is to difficult for you!'
  unpickable-lock: 'This lock can not be picked!'
  bypass: 'Lock bypassed.'
  key-used: 'You opened the chest with your key.'
  pick-needed: 'You need a <lockpick> to open this chest!'
  pick-break: 'Your <lockpick> broke!'

The messages 'pick-needed' and 'pick-break' will replace the '<lockpick>' with the configured name of your lockpick item.