This page explain entirely how the config file works.

Config.yml (Default)

Click on a variable to get more info
Any variables are optional, if not setted, default will be used.

# +———————————————————————————————————————————————————+ #
# |——————————     BANITEM CONFIGURATION     ——————————| #
# |——————————————————      v2.1      —————————————————| #
# +———————————————————————————————————————————————————+ #
# |                   Documentation:                  | #
# |               | #
# +———————————————————————————————————————————————————+ #
better-debug: true
no-permission: '&cYou do not have permission.'
prefix: '&c[&e&lBanItem&c] '
use-event-api: false
check-update: true
priority: 'place,consume'
    - '/rename'
    hoppers-block: false
    region-check: false
  worldguard: false


All permissions are for op by default.
  • Bypass permission: banitem.bypass.<worldName>.<itemName>.<optionName>.<dataName>
    - worldName: name of the world, or allworlds (e.g: world)
    - itemName: material or custom item name (e.g: stone)
    - optionName: ban option (e.g: place)
    - dataName: name of the ban option data, or '*' to include them all (e.g: entity)
    - Example:*
  • Commands permissions:: banitem.command.<name>
    - Names: add, check, customitem, help, log, info, reload.
    - Example:
    N.B: you'll need the help permission to display the command help and use the tab completer.


  • /banitem add <option> [message]
    Description: ban the current item in your hand (not include metadata) for the current world;
    Example, with a diamond block in the hand:

    /bi add place,break &cYou can not place or break this.
    -> Diamond block can not be placed or breaked anymore in the current world.
    Bypass permission:* (and same for break)
  • /banitem check [delete]
    Description: will give a list of all players which inventories contains a blacklisted item (respects the worlds).
    Use the delete argument to also delete those items.
  • /banitem customitem add <name> [option] [message]
    Description: to ban the current item in your hand (includes metadata) for the current world.
    Entering no options will only save the custom items, so you can manually edit the config file.
    If a previous custom item with the same name already exists, it will be overridden.
    Example, with a sword in the hand:

    /bi ci add mySword attack,drop &cYou can not attack with this item.
    -> Can not attack with this sword or drop it in the current world.
    Bypass permission: banitem.bypass.worldName.mySword.attack.* (and same for drop)
  • /banitem customitem get <name>
    Description: will give you the custom item into your inventory;
  • /banitem customitem list
    Description: will give a list of all custom items (by name);
  • /banitem customitem remove <name>
    Description: to remove the custom item;
  • /banitem help [type]
    Description: will give you additional informations about the type entered;
    Type: worlds, options, entities, gamemodes, inventories.

    /bi help gamemodes
    -> List of available gamemodes: creative,survival,adventure,spectator
  • /banitem info
    Description: to get information about the current item in your hand (for example the material name to put in config.yml);
  • /banitem log
    Description: will activate the log mode. Players with log mode activated will receive a message in game for all banned items with data 'log: true';
  • /banitem reload
    Description: reload everything (config, custom items, blacklist, whitelist...)

General informations

  • Items:

    The items banneable are: You can easily get the material name by using /banitem info with the item in your hand.
  • Blacklist:

    The blacklist contains list of blocked items. Default synthax: Result: players can not drop or pickup diamonds in the world 'world'.
    Bypass permission example:*
  • Whitelist:

    The whitelist contains list of allowed items only. Default synthax: Result: in the world_the_end, players will only can place dirt.
    Bypass permission example:*
  • Custom items:

    A custom item is an item with its metadata (including durability, displayname etc.), saved into the items.yml file.
    It's used by the plugin to recognize items with metadata (like a potion, a banner, a book, a spawn egg etc.)
    You can use /banitem customitem to add/get/remove/list custom items.
  • Options & Options datas:

    An option is an "action" which will be banned by the plugin.
    Each options can store options data, which contains additional ban checks, like the player gamemodes, if it's in cooldown, if the action should be logged etc.
  • Formats:

    Almost all variables in the config file can be shortened & compressed. There are also 'include all' (*) & 'exlude' (!) operators.
    Worlds can be written:
    • -> Single: 'world','world_the_end'
    • -> Multiple: 'world,world_the_end','world,test,anotherone'
    • -> Include all worlds: '*'
    • -> All except: '*, !world, !world_the_end'-> all worlds, except 'world' and 'world_the_end'

    Items can be written:
    • -> Single: 'stone','dirt'
    • -> Multiple: 'stone,dirt','stone,dirt,diamond_block'
    • -> All: '*' -> also include air (= empty hand)
    • -> All except: '*, !stone, !dirt'-> all, except 'stone' and 'dirt'

    Options can be written:
    • -> Single: 'place','break'
    • -> Multiple: 'place,break','pickup,drop,place'
    • -> All: '*'
    • -> All except: '*, !place, !break'-> all, except 'place' and 'break'

    Options data can be written:
    (if it's a listable one, like: message, entities, gamemode, material etc.)
    • -> Single: entity: 'cow',entity: 'pig'
    • -> Multiple: entity: 'cow,pig',entity: 'cow,pig,chicken'
    • -> Multiple list:
    • -> All: entity: '*'
    • -> All except: '*, !cow, !pig'-> all, except 'cow' and 'pig'

  • Options

    Here is the list of options useable.
    All options can have general options data (like messages, log, cooldown etc.), listed at the end.
    Each options can have custom options data.

    Options Data

    The options data is a complement to the option. It can store additional informations (like the gamemode, a message etc.) for the option.
    Example synthax: Players can not place diamond block if they are in creative mode
    Here is the list of options data useable.

    • Type: boolean  -  Default: true
    • Display better error messages when trying to load the config file.
    • If true:
    • If false:

    • Type: String  -  Default: &cYou do not have permission
    • The no-permission message send to a player which try to use the ban item command.

    • Type: String  -  Default: &c[&e&lBanItem&c]
    • The plugin prefix to displays in chat/console.

    • Type: boolean  -  Default: false
    • If true, a PlayerBanItemEvent will be called whenever an action should be banned.

    • Type: boolean  -  Default: true
    • If true, the plugin will check async, when the server loads, if there is a new update.

    • Type: String/List of ban options  -  Default: place,consume
    • List of options that should have maximum listening priority.
      Giving maximum priority will force the ban item plugin to have the final word on an event.
      This is used mainly to also block other plugins events, if the action is banned.
    • You can use the format synthax.

    • This is a section where you can configure some specifics informations usefull for the ban options:
      • rename: list of rename commands which a player can use to rename an item.
        This is needed for the plugin to check if a player try to rename a banned item with a command.
      • transfer: section containing some configurable data for the transfer option:
        - hoppers-block: also blocks hoppers to take/give banned item from/to inventories
      • wear: section containing some configurable data for the wear option:
        - region-check: if the plugin should check for players armor when it enter or exit a WorldGuard region

    • Contains list of configurable hooks:
      • worldguard: if the plugin should hook with worldguard or not (Worldguard 6 or 7)

    • Type: List of EntityType
    • List of entity which the ban should be applied.
    • You can use the format synthax.
    • You can get a correct list of entities for your current minecraft version with /banitem help entities

    • Type: List of Material
    • List of material which the ban should be applied.
    • You can use the format synthax.
    • You can get the correct material name with /banitem info

    • Type: List of InventoryType
    • List of inventories which the ban should be applied.
    • You can use the format synthax.
    • You can get a correct list of inventory names for your current minecraft version with /banitem help inventories