Documentation


Last update: 10.10.2023

Config.yml

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

# +———————————————————————————————————————————————————+ #
# |——————————     BANITEM CONFIGURATION     ——————————| #
# |——————————————————      v3.5      —————————————————| #
# +———————————————————————————————————————————————————+ #
# |                   Documentation:                  | #
# |             https://banitem.andross.fr/           | #
# +———————————————————————————————————————————————————+ #
debug:
  errors: true
  reload: false
  colors-console: false
no-permission: '&cYou do not have permission.'
prefix: '&c&l[&e&lBanItem&c&l] '
api:
  playerbanitemevent: false
  deletebanneditemevent: false 
check-update: true
priority: 'use,consume'
actions:
  enchant:
    material: BARRIER
    displayname: '&cBANNED'
    lore:
      - '&cYou can not add this'
      - '&cenchantement.'
  rename:
    - '/rename'
  transfer:
    hoppers-block: false
  wear:
    region-check: false
	scanner: true
  delete:
    ignored-inventories-titles:
      - 'My Cool Gui'
      - 'Shop'
hooks:
  advancedenchantments: false
  itemsadder: false
  worldguard: false
illegal-stacks:
  enabled: false
  vanilla-max-stack-size: true
  block-type: split

Permissions

All permissions are for op by default.

Commands

    All commands can be shortened /bi
  • /banitem add <action> [-m materials] [-w worlds] [message]
    Description: ban the current item in your hand (does not include metadata) for the current world;
    You can set multiples materials or multiples worlds.
    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: banitem.bypass.worldName.diamond_block.place.*

    Example from console:
    /bi add place -m stone -w world
    -> Stone can not be placed into 'world'.
  • /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 help [type]
    Description: will give you additional informations about the type entered;
    Type: worlds, actions, entities, gamemodes, inventories, enchantments, potions.
    Example:

    /bi help gamemodes
    -> List of available gamemodes: creative,survival,adventure,spectator
  • /banitem info [debug]
    Description: to get information about the current item in your hand (for example the material name to put in config.yml)
    If you enter /bi info debug, a complete detailled debug will be displayed about the item into your hand.
  • /banitem load <file>
    Description: will load the configuration in the file.
    The file has to be into the BanItem plugin folder.
  • /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 metaitem add <name> [action] [message]
    Description: to ban the current item in your hand (includes metadata) for the current world.
    Entering no actions will only save the meta item.
    If a previous meta item with the same name already exists, it will be overridden.
    The command can be shortened /bi mi.
    Example, with a sword in the hand:

    /bi mi 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.*
  • /banitem metaitem get <name>
    Description: will give you the meta item into your inventory;
  • /banitem metaitem list
    Description: will give a list of all meta items (by name);
  • /banitem metaitem remove <name>
    Description: to remove the meta item;
  • /banitem reload
    Description: reload everything (config, custom/meta items, blacklist, whitelist...)
    The command can be shortened /bi rl.
  • /banitem remove [-m materials] [-w worlds]
    Description: remove & unban the current item in your hand.
    You can use the command from console and specifiy the materials and worlds.

General information

Items:

The items bannable are:
  • Material
    The material item, does not include metadata.
  • Meta items
    The item, including all/exact metadata (displayname, lore, enchants, durability etc.)
  • Custom items
    Customizable item with customizable metadata.
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 example synthax: Result: players can not drop or pickup diamonds in the world 'world'.
    Bypass permission example: banitem.bypass.world.diamond.drop.*

  • Whitelist:

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

  • Meta items:

    A meta item is an item with its metadata (including durability, enchants, displayname etc.), saved into the metaitems.yml file.
    It's used by the plugin to recognize items with the exact same metadata (like a potion, a banner, a book, a spawn egg etc.)
    You can use /banitem metaitem to add/get/remove/list meta items.

  • Custom items:

    A custom item is an item which contains configurable/customizable metadata, so the plugin can recognize different metadata on a same item.
    This will require to manually modify the config.yml & customitems.yml files.

  • Actions & Actions datas:

    An action is an ingame action that will be banned/blocked by the plugin.
    Each actions can store actions 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.
    You can use regex names for items names & world names, adding "#" at the beginning of the string.
    The plugin does not support spaces into the world names!

    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'
    • -> Regex: '#(?i)world'-> world, world_nether, 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'
    • -> Regex: '#(?i)_bed'-> will match all bed items
    Actions can be written:
    • -> Single: 'place','break'
    • -> Multiple: 'place,break','pickup,drop,place'
    • -> All: '*'
    • -> All except: '*, !place, !break'-> all, except 'place' and 'break'
    Actions 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'

    • Actions

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

    Actions Data

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

    Errors:

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

    Reload:

    • Type: boolean  -  Default: false
    • Display more informations when reloading the plugin.

    Colors-console:

    • Type: boolean  -  Default: false
    • If true, the console will try to display colored messages.

    • 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&l[&e&lBanItem&c&l]
    • The plugin prefix to displays in chat/console.

    • Type: boolean  -  Default: false
    • playerbanitemevent - will be called whenever an action should be banned
    • deletebanneditemevent - will be called whenever an item should be deleted by the plugin.

    • 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 actions  -  Default: use,consume
    • List of actions 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 actions:
      • enchant: a configurable ItemStack.
        This configurable ItemStack will be displayed in an anvil if the player can not enchant the item.
      • 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 action:
        - hoppers-block: also blocks hoppers to take/give banned item from/to inventories
      • wear: section containing some configurable data for the wear action:
        - region-check: if the plugin should check for players armor when it enter or exit a WorldGuard region
        - scanner: if the plugin should check each seconds async if the player wear a banned item
      • delete: contains a list of string 'ignored-inventories-titles'.
        The plugin will not take in consideration inventories which name is in this list.
        Do not use color codes, as the plugin automatically strip GUIs title colors.

    • Contains list of configurable hooks:
      • advancedenchantments: if the plugin should hook with AdvancedEnchantments or not (v8+)
      • itemsadder: if the plugin should hook with ItemsAdder or not (v2+)
      • worldguard: if the plugin should hook with worldguard or not (Worldguard 6 or 7)

    • This (async) scanner will check if the max stack size of items inside players inventories are respected.
      • enabled true/false - if this scanner should be enabled
      • vanilla-max-stack-size true/false - if the default max stack size for all items should be used
      • block-type - specify what will happen to the illegal stack
        • split - to split and give items back until the correct max stack is respected
          Example: 1 item representing 2 diamonds helmet -> 2 items 1 diamond helmet
        • delete - to delete the whole stack
          Example: 1 item representing 64 diamonds helmets -> 0 item
        • deletemore - to delete only the exceeded amount
          Example: 1 item representing 64 diamonds helmets -> 1 item 1 diamond helmet
      • items - contains a list of configurable max stack amount PER item
        • You can write as many materials as you want and you can use the items format
        • If you have set vanilla-max-stack-size to true then the configurated item will be used
        • You can use world to set one or multiple worlds where the check will apply. If no world is specified, all worlds will be included.

    • 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