Astral Gates

First off, the name doesn't quite reflect the plugin anymore because I coined the name before I started adding features as I went. With that out of the way, we now continue on to your regularly scheduled programming.

AstralGates is an easy-to-use menu plugin, with many different features. As of AG 2.3.x, AG is now 1.8 compatible. As of the AG 2.x complete rewrite, here are the newest features:

1. You can now have multiple menus: This is a huge improvement as before you were only able to have one.
2. More actions: You can now use the 'MENU' action which allows you to specify a menu to open the player to.
3. Prerequisites: These will be explained below.
4. Fixed menus (slots are specified).
5. Hopper and Dispenser inventories are allowed (please note: if you use more items then they can hold it will default to chest).
6. Color codes are now allowed everywhere.
7. Items can now be enchanted in the menus.
8. You can do multiple actions for a given item.

Commands:

• /astralgates open [name] - opens the menu (note: name is the file name for the menu)
• /astralgates opener [name] - get the item that opens the specified menu (where name = file name -.yml)
• /astralgates reload - reloads the config and all menus

Config:

• bungeecord: [true/false] - allow bungeecord integration (note: you can only use this to send players to another server)

The menus:
Menus are composed of serveral parts. The bullets replicate (sort of) the nesting of the YAML files.

• title: [String] - The name of the inventory in the window
• enabled: [true/false] - Whether the menu will load at all
• permission: [String] - Permission needed to open the menu (use two apostrophes (') to disable or leave out entirely)
• fixed: [true/false] - If enabled, the menu will put the items in the slot specified
• type: ["CHEST"/"HOPPER"/"DISPENSER"] - what kind of inventory to open. Note that if you exceed the number of items a hopper or dispenser can have (5 & 9 respectively), it will default to chest and if you exceed 54 (how many a chest can have at max), it will stop adding items
• rows: [1-6] - How many rows the chest will display (note: will expand if needed)
• item - section for the opener item (when players right/left click with it it will open the menu)
  • enabled: [true/false] - whether to load an opener item (note: if disabled, the rest of the item settings will be ignored)
  • Generic Item Data (see below) (while you can specify an amount, it is highly recommended you keep it at 1)
• gates - The items in the menu
  • unique name - This isn't used other than as a unique identifier for when loading the config. Just make sure there are no duplicates.
    • slot: [#] - (Only applies if using a fixed menu) Slot in the menu the item will go in.
    • permission: [String] - (Optional) Specify a permission needed to view and use the item. If no permission, it won't even show up.
    • item: [Generic Item Data] - Item for the menu slot.
    • prerequisites: - Things that need to occur for the actions to occur (note: all must come back true)
      • unique name: - works the same as above
        • needall: [true/false] - If true, all prereqs must be true in order for it to be true. If false, only one needs to be.
        • world: [list of Strings] - Each String counts as a separate prereq. Player must be in world [String]
        • worldnot: [list of Strings] - Inverse of above. Player must not be in world [String]
        • permission: [list of Strings] - Each String counts as a seperate prereq. Player must have permission [String]. Can be used to have players able to view an item, but not use it unless they have a different permission.
        • permissionnot: [list of Strings] - Inverse of above. Player can not have permission [String]
    • actions: - Things that occur when it works
      • unique name: - Same (again) (Note: only one action per UN)
        • action: ["COMMAND_PLAYER"/"COMMAND_CONSOLE"/"SERVER"/"MENU"] - Action to do. COMMAND_PLAYER runs a command as the player who used the menu, COMMAND_CONSOLE runs a command as console, SERVER sends the player to the specified server (needs BungeeCord and bungeecord enabled in the config), and MENU opens a menu to the player. Note: TELEPORT was removed due to being a pain to do. Please use CONSOLE_COMMAND and /tp instead.
        • data: - Data used in the action listed above
          • COMMAND: [String] - Command to run. Preceding slash not required. Note: If doing a command with multiple slashes at the beginning, you need all of them. Has the variables %PLAYER% which turns into the player's name and %WORLD% which is the name of the world the player is in.
          • SERVER: [String] - Name of server to connect to
          • MENU: [String] - Name of menu to open (note: uses the menu's filename without the .yml)

How to make an item (aka Generic Item Data):

• material: [Material] - Material for the icon (uses Bukkit names)
• name: [String] - Custom item name (can have colors)
• lore: [list of Strings] - List of lore lines (can have colors)
• amount: [1-a lot] - Number of items in the stack (if over 64 it will increase the max. allowed stack size to match the amount)
• durability: [#] - Item durability (damage picks, change wool color, etc.)
• enchantments
  • [enchantment name (according to Bukkit)]: [Level of enchant]

I tried to use all of the features in the config, so if you are wondering how to set something up, look there.
All items data are based on the Material.getMaterial() method from bukkit's documentation (the string based version).

Common Errors:

• Unable to create a menu/menu item:
  • Chances are you're using an 'illegal' character in your name. The ones that I've noticed are the parentheses ( '(' & ')' ), ampersands (&), and colons ). There may be a few more though. To fix this surround the entire string in a single apostrophe on both sides and then don't use any single apostrophes in the string.

To-do:

• Vault integration for economy
• More item data (such as play head names and potion effects on potions, leather armor color)
• Open a menu via a sign
• API