ItemJoin Getting Started

Aug 5, 2017
ItemJoin Getting Started
  • [​IMG]
    If you feel like something is missing and needs to be added or clarified please Private Message me and I will add it.

    Note; Clear-Items: in the config.yml, All will clear any item in the players inventory, ItemJoin will clear only ItemJoin items.
    [​IMG]

    How do you create an item?
    An Item is fairly simple to create, to create an item you must first list the world identifier. This is the name of the world that you want to receive these items in. The next identifier you must add is the items identifier, to signify the creation of the items. Now you can simple list the name of the items you wish to create.

    The items must have and ID and SLOT to receive the item in game. You can also list the enabled-worlds you want each item in, or if you don't list the enabled worlds it will be given to all worlds by default. All of features are optional and simply for greater configuration. Shown below is an example of creating three items.

    Here is an example of some items;
    Code (Text):
    items:
      any-text:
        id: 284
        slot: 0
        enabled-worlds: world_name_here, another_world_name
      another-item:
        id: SEEDS
        slot: 2
      wheat-item:
        id: WHEAT
        slot: 4
        enabled-worlds: world, world_nether, world_the_end
     
    Now I as I said you can add more options to your items to make them so much more custom.
    You can set a custom name, add lines of lore, enchantments, define custom permission nodes to receive the items, as well as the count/amount of each item you get. There is also an option to use data-value of an item, this is useful to get items such as wool.

    data-values are sometimes confusing as you would think you could just put it in the ID. Although you must put the data-value in its own section. Such as to get green wool you would need to set the ID to WOOL or 35, then set the data-value to 5 since green wool's data-value is 5.

    Finally we have durability, you set this to the amount of durability you want the item to haven taken, such as if the item has 32 durability and you set the durability to 5 it will have 27 durability when you receive the item.

    As said all options are optional and can be removed if you do not want to use them in your item, you just must have the defining characteristics of an item, ID and Slot.

    Here is a list of all available options;
    Code (Text):
    items:
      ultra-item:
        id: DIAMOND_SWORD
        slot: 0
        name: '&bBlazefury'
        data-value: 0
        count: 1
        durability: 5
        lore:
          - '&7A god sword..'
          - '&7This is generations old!'
        commands:
          multi-click:
            - 'message: &eYou can send yourself custom messages!'
            - 'console: say You can even execute more than one command!'
            - 'player: say This is item slot 1'
            - 'say Hello world!'
          right-click:
            - 'console: gamemode 1 %player%'
            - 'message: &eYou have been set to creative mode.'
          left-click:
            - 'console: gamemode 3 %player%'
            - 'message: &eYou have been set to spectator mode.'
          multi-click-air:
            - 'message: &eThis will prevent commands from being executed when you click on blocks such as a sign.'
          right-click-air:
            - 'message: &eThis will prevent commands from being executed when you click on blocks such as a sign.'
          left-click-air:
            - 'message: &eThis will prevent commands from being executed when you click on blocks such as a sign.'
          inventory:
            - 'console: gamemode 2 %player%'
            - 'message: &eYou have been set to adventure mode.'
        enchantment: FIRE_ASPECT:3, DAMAGE_ALL:5, DAMAGE_UNDEAD:5, KNOCKBACK:8
        commands-type: interact, inventory
        commands-sound: BLOCK_NOTE_PLING
        commands-cost: 25
        commands-cooldown: 5
        cooldown-message: '&7[&eItemJoin&7] &a[%item%&a] &cis on cooldown for &a%timeleft% &cseconds..'
        itemflags: inventory-modify, death-drops, unbreakable, disposable, count-lock, cancel-events, placement, hide-durability, hide-attributes, self-drops, first-join, CreativeBypass, AllowOpBypass
        triggers: join, respawn, world-change
        permission-node: 'itemjoin.ultra'
        enabled-regions: region1, region2
        enabled-worlds: world, world_nether, world_the_end
    How does the slot system work?
    The slot system consists of 35 Numerical slots and 6 Custom Name slots, 0 to 8 are the first 9 slots in your hot bar. Normally when you count you would not start with zero then count up from there, you would start with one. CraftBukkit / Spigot does not do this, they start out with zero first. So the first slot in your hot bar would really be slot zero.

    As for the physical inventory, the slot numbers start at the top left and increase to the right, as shown in the image below. Those slots are 9 to 35.

    To set an item in your armor slots you would simply type the name of the slot you would want it to be in. Helmet, Chestplate, Leggings, or Boots, If you want an item in your offhand you would do the same for this. Just put the slot as Offhand.

    There is also a slot option called Arbitrary, If an item is set to this, the item will be put in the FIRST available slot in the players inventory, it will not remove any of the players items in their inventory to place itself in that spot.

    You can also set multiple slots per item, just separate the slots by commas such as 1, 12, 13, Arbitrary, 3.


    Here is an example of the slots being used for various items;
    Code (Text):
    items:
     first-item:
       d: SKULL_ITEM
       slot: 0 #// This can be any number between 0 and 35, depending on the location you want it in the players inventory.
     second-item:
       id: DIAMOND_SWORD
       slot: Arbitrary
     helmet-item:
       id: DIAMOND_HELMET
       slot: Helmet
     chestplate-item:
       id: 299
       slot: Chestplate
     leggings-item:
       id: DIAMOND_LEGGINGS
       slot: Leggings
     boots-item:
       id: LEATHER_BOOTS
       slot: Boots
     offhand-item:
       id: SHIELD
       slot: Offhand

    [​IMG]


    How do I use the global items option?
    This is fairly simple to setup, all you have to do is add either All or Global to the enabled-worlds identifier. Then the items will be given in every world.

    Here is an example of global items;
    Code (Text):
    items:
      any-text:
        id: 284
        slot: 0
        enabled-worlds: Global
      wheat-item:
        id: WHEAT
        slot: 4
        enabled-worlds: All
     


    How do I setup and use commands?
    First off, we have to start by setting up the command actions. These will be the actions the player has to do to activate the commands.
    There are 4 types of executors: multi-click, right-click, left-click, inventory and physical.
    It is not recommended to use physical and it is disabled by default because this executes the command if a player steps on a pressure plate, hits a mob, opens a chest, or any other physical actions with that item in your hand it will run any commands it has.
    You can set it up as such to use all of the executors or you can remove the ones you don't want to use. See the example below for how the executors should be setup.

    As for the commands cooldowns it is as simple as it gets! It sets the time in seconds that the items command will be on cooldown for. If the commands are on cooldown then it will send a cooldown message, sends the player the cooldown message when the item is on cooldown.

    Finally we have command instances. Commands can be executed by 4 instances; console, player, server, and message. If no instance is specified in the commands string, then by default it will be executed by the player.
    If you still do not understand what each do;
    console, executes the set command by console.
    player, executes the command as if the player executed it themselves.
    server, sends the player to that directed server name. (Connects to BungeeCord).
    message
    , sends the player a custom message of your choosing.

    Here is an example of an item with a command;
    Code (Text):
    items:
      ultra-item:
        id: DIAMOND_SWORD
        slot: 0
        commands:
          multi-click:
            - 'message: &eYou can send yourself custom messages!'
            - 'console: say You can even execute more than one command!'
            - 'player: say I am executed by player'
            - 'server: survival'
            - 'say I am executed by player since I dont have a executor...'
          right-click:
            - 'console: gamemode 1 %player%'
            - 'message: &eYou have been set to creative mode.'
          left-click:
            - 'console: gamemode 3 %player%'
            - 'message: &eYou have been set to spectator mode.'
          inventory:
            - 'console: gamemode 2 %player%'
            - 'message: &eYou have been set to adventure mode.'
        commands-type: interact, inventory
        commands-sound: BLOCK_NOTE_PLING
        commands-cost: 25
        commands-cooldown: 5
        cooldown-message: '&7[&eItemJoin&7] &a[%item%&a] &cis on cooldown for &a%timeleft% &cseconds..'
        enabled-worlds: world


    How do I set custom itemflags on an item?
    Itemflags allow HUGE modifications to the items. All you have to do to add itemflags to an item, is add the itemflags identifier to the item as shown below.

    These are custom itemflags, all itemflags with description are listed below, Itemflags are always being updated an added onto so check back here for updates!

    Current available itemflags:
    first-join - This will only give the item when joining the server for the first time, to get the item every time you join just remove this itemflag.
    unbreakable - Set the item as INDESTRUCTIBLE!
    hide-attributes - Hides ALL attributes, such as firework color, damage the item does, enchantments. (Hides everything from lore except the custom lore).
    hide-durability - Hides the durability bar from the item.
    placement - Prevents this item from being placed if it is a BLOCK.
    inventory-modify - Prevents this item from being moved, stored, or switched to offhand in the players inventory.
    cancel-events - Prevents player from opening a chest while this item is in hand or any open-able items. Useful for canceling the event of opening a book to set custom book items.
    count-lock - Prevents the player from using all of the item. If the item is set to count: 32 then each time the player places the block item the stack will be refreshed back to 32.
    death-drops - Clears this item if it is dropped on the ground when the player dies.
    self-drops - Prevents the player from dropping this item, either clicking it out of inventory or using the drop key, usually (q).
    disposable - If a command is ran from the item it will remove x1 of the item from the players inventory.
    AllowOpBypass - This would allow the user IF THEIR OP to bypass most of these itemflags. It will work on ALL non item modifying flags. This would NOT work on unbreakable, hide-attributes, stuff like that.
    CreativeBypass - This would allow the user IF THEIR IN CREATIVE MODE to bypass most of these itemflags. It will work on ALL non item modifying flags. This would NOT work on unbreakable, hide-attributes, stuff like that.

    Here is an example of an item with all itemflags;
    Code (Text):
    items:
      ultra-item:
        id: DIAMOND_SWORD
        slot: 0
        itemflags: first-join, unbreakable, hide-attributes, hide-durability, placement, inventory-modify, cancel-events, count-lock, death-drops, self-drops, disposable, AllowOpBypass, CreativeBypass
        enabled-worlds: world
    How do I set custom triggers on an item?
    Triggers allow you to receive the items under certain conditions. All you have to do to add a trigger to an item, is add the triggers identifier to the item as shown below. If a trigger is not defined, the item will be given upon joining the server by default.

    These are custom triggers, all triggers with description are listed below.

    Current available triggers:
    join - This will give the item when the player logs into the server.
    respawn - This item will be given on respawn if a player dies.
    world-change - This item will be given when the player changes worlds. When you enter the world this item is allowed in it will be given.
    region-enter - This will give the item upon entering a region, you must have WorldGuard set to true and have enabled-regions listed for the item.
    disabled - This will prevent the item from being given on join, respawn, world-change, and region-enter. This is helpful if you only wish to get the item using /itemjoin get <item>.

    Here is an example of an item with all itemflags;
    Code (Text):
    items:
      ultra-item:
        id: DIAMOND_SWORD
        slot: 0
        triggers: join, respawn, world-change, region-enter
        enabled-regions: region1, region2
        enabled-worlds: world
      second-item:
        id: PAPER
        slot: 1
        triggers: disabled
        enabled-regions: region1, region2
        enabled-worlds: world
     

    How do I create Custom Books!?
    Custom books can get a bit complicated and tricky so bare with me.
    To begin creating your custom book you must set the ID to WRITTEN_BOOK. It must be that, it cannot be anything else. You have the option of adding an author if you would like by adding the author identifier.


    Each custom book must have a pages identifier.
    How do pages identifiers work?
    Pages identifiers have the instances newpage, newline, and :endofbook:.
    newpage: starts the new page as well as the first line of the book.
    newline: continues the next line of the new page of the book.
    :endofbook: finalizes the book, marks the end of the book. This must always be put at the end of the book as it will cause problems if it is not.

    Here is an example of a custom book item;
    Code (Text):
    world:
      items:
        book-item:
          id: WRITTEN_BOOK
          slot: 0
          author: '&bItemJoin'
          pages:
            - 'newpage: &bYou can get this book on join!'
            - 'newline: &aThis book also supports &ccolor codes!'
            - 'newline: &0'
            - 'newline: &cHow do custom books work?'
            - 'newline: &0'
            - 'newline: &0You can set an &cauthor&0'
            - 'newline: &0as shown in the items.yml'
            - 'newline: &0I set it to &bItemJoin.'
            - 'newline: &0'
            - 'newpage: &cHow do you create a new page?'
            - 'newline: &0'
            - 'newline: &0As displayed to the left in the items.yml'
            - 'newline: &0Use &bnewpage&0 and &cnewline&0 to create your pages.'
            - 'newline: &cnewpage &0will start the next page.'
            - 'newline: &cnewline &0will create a new line for that page.'
            - 'newpage: &bItemJoin &0by RockinChaos!'
            - ':endthebook:'


    How do I create custom fireworks?
    Your custom firework item's ID must be FIREWORK. If it is not this will not work.
    Each firework must have the firework identifier as shown below.
    You must specify what firework type you would like your firework to be. The available firework types are; BALL, BALL_LARGE, BURST, CREEPER, STAR.

    You also have the option of enabling / disabling flicker and trail from your firework. Flicker is if you want the particles after the explosion to sparkle and fade out. Trail is if you want your firework to leave a trail of misty smoke behind the fireworks path of trajectory.

    Next you must specify the power, the power represents the distance the firework will travel before it will explode. For example, 1 is fairly close to the ground, 2 is fairly high in the sky. It is recommended that you keep the power BELOW 2, as it will get really high up into the sky if it is set any higher than 2.

    Finally you must set the color identifier. Within the color identifier you can add as many colors as you want! These colors must be Dye colors. There available dye colors are; BLACK, BLUE, BROWN, CYAN, GRAY, GREEN, LIGHT_BLUE, LIME, MAGENTA, ORANGE, PINK, PURPLE, RED, SILVER, WHITE, YELLOW.
    You can see the list of dye colors here.

    Here is an example of a custom firework item;
    Code (Text):
    items:
      firework-item:
        id: FIREWORK
        slot: 0
        firework:
          type: CREEPER
          flicker: true
          trail: true
          power: 1
          colors:
            - 'GRAY'
            - 'WHITE'
            - 'PURPLE'
            - 'SILVER'
            - 'GREEN'


    How do I create custom maps?
    Custom maps are really simple and easy to setup! All you need to do is set the ID to MAP and add the custom-map-image identifier as shown below.

    Just put the image you want to be displayed on your map in the local ItemJoin folder, where the config files are located, and replace the default.png with the name of the png file.

    You must also set a map-id to the item, this id can only be 1 - 29. If it is above or below it will cause errors! If you have multiple custom maps you must set them to have different map-id's.

    NOTE: The map image must be NO LARGER than 128x128 pixels, this is a perfect fit for the map size. The image file you use must also be PNG.

    Here is an example of a custom map item;
    Code (Text):
    items:
      map-item:
        id: MAP
        slot: 0
        map-id: 1
        custom-map-image: 'default.png'

    How do I create custom skulls, (Player Heads)?
    Custom Player Heads are super simple to setup. Set the ID to SKULL_ITEM, and set the data-value to 3. The data-value being 3 means it is a player head.

    Finally just add the skull-owner identifier as shown below and put the name of the player you want to be displayed on the skull. In the example a placeholder %player% is shown. This means the player that gets the skull in their inventory will show their own skin! So everyone gets their own skull, with their own skin!

    Here is an example of a custom skull item;
    Code (Text):
    items:
      skull-item:
        id: SKULL_ITEM
        slot: 0
        name: '&b%player%'
        skull-owner: '%player%'
        data-value: 3

    How do I create custom arrows?
    Custom Arrows are meant for making Tipped Arrows, these are the new 1.9 arrows with potion effects.
    All you have to do is set the id to TIPPED_ARROW, and add the potion-effect identifier, which is the effect given off by the arrow, the power; strength of the arrows potion effect, the default is 1 and there is no limit that I have found, Lastly would be the time; this is the time in seconds that the arrows effect will have on the target it is on in seconds, the default is set to 20 seconds. So formatting would look like this; Effect:LevelOfEffect:DurationInSeconds you can see below I did Wither 1 with 20 seconds of duration.

    Here is an example of a custom skull item;
    Code (Text):
    items:
      arrow-item:
        id: TIPPED_ARROW
        slot: 0
        count: 16
        potion-effect: WITHER:1:20

    How do I create custom potions?
    Custom potions are simple to create. You just need to set the ID to POTION, SPLASH_POTION, or LINGERING_POTION and add the potion-effect identifier. Formatting goes as such Effect:LevelOfEffect:DurationInSeconds as you can see below I did Jump level 2 with 120 seconds of time applied to you upon drinking it.

    Here is an example of a custom skull item;
    Code (Text):
    items:
      potion-item:
        id: POTION
        slot: 0
        potion-effect: JUMP:2:120, INCREASE_DAMAGE:3:150, REGENERATION:1:160

    How do I create custom golden apples?
    Custom golden apples are apples that have custom potion effects. These work with both golden apples and notch apples. Just add the potion-effect identifier like the custom potions. Formatting goes as such Effect:LevelOfEffect:DurationInSeconds as you can see below I did Jump level 2 with 120 seconds of time applied to you upon drinking it.

    Here is an example of a custom skull item;
    Code (Text):
    items:
      golden-apple-item:
        id: GOLDEN_APPLE
        slot: 0
        potion-effect: JUMP:2:120, NIGHT_VISION:2:400, GLOWING:1:410, REGENERATION:1:160

    How do Placeholders work?
    ItemJoin supports PlaceholderAPI, meaning it can hook into the plugin and use those placeholders! You can use ANY of these placeholders, in all parts of ItemJoin. Such as, skull-owner, name, lore, book pages, commands, cooldown-messages, and more! Placeholders will be supported by all parts of ItemJoin!!

    If you do not use PlaceholderAPI, ItemJoin currently only has two placeholders by default; which is %player% and %hitplayer%. This will be expanded upon in the future but it is highly recommended that you use PlaceholderAPI, as it is so useful and has so many features!


    How can I get items in a certain region?
    ItemJoin supports WorldGuard, meaning that you can hook into the plugin and use certain regions. If you want to receive items upon entering, joining, respawning into that region its really simple.

    You have to set WorldGuard to true in the config.yml, then set the enabled-regions per item, you can set multiple regions separated by commas. Lastly you have to set the triggers to region-enter. You can make your items multipurpose saying you can receive them on join anywhere but you can also get them when entering a region, see the available triggers above to setup more than just a region-enter trigger.

    Here is an example of several items you can get when entering/joining into/respawning into region1 and region2;
    Code (Text):
    items:
     first-item:
       d: SKULL_ITEM
       slot: 0
       triggers: region-enter
       enabled-regions: region1, region2
     second-item:
       id: DIAMOND_SWORD
       slot: Arbitrary
       triggers: region-enter
       enabled-regions: region1, region2
     helmet-item:
       id: DIAMOND_HELMET
       slot: Helmet
       triggers: region-enter
       enabled-regions: region1, region2
     chestplate-item:
       id: 299
       slot: Chestplate
       triggers: region-enter, join, respawn, world-change
       enabled-regions: region1, region2
     leggings-item:
       id: DIAMOND_LEGGINGS
       slot: Leggings
       triggers: region-enter, join, respawn, world-change
       enabled-regions: region1, region2
     boots-item:
       id: LEATHER_BOOTS
       slot: Boots
       triggers: region-enter
       enabled-regions: region1, region2
  • Loading...
  • Loading...