Inactive [INFO] Help 3 - a Smarter /help [1060]

Help - The Smart /help Menu
Version: 0.3.2
Download: Help.jar

This is a new thread for the Help version that i maintain
(tkelly hasn't been on for about a month as of this submission, and no updates to his version since 531)

Version 0.3 is (finally) out!

(any suggestions for what to work on next are welcome )


Help has support for both GroupManager and Permissions, so you can use either one. You can also use neither if you so choose. Help will not force you to any which one.

What is Help?
Help is a clean and advanced /help menu. Help separates "main" commands from secondary ones, allowing you to have a clean initial menu, but still able to dig down and get access to every possible command.

It is also the first /help menu to take into account permissions; some commands simply aren't applicable to all users, so those commands should clearly not be visible to those users. Now, default users' help menus won't be cluttered with commands for admin tools they have no way of using.

Scroll down for a preview, or see below for how to hook into Help

Help Commands
/help (#) : Shows the /help menu.
/help [plugin] (#): Shows all the help entries for [plugin].
/help plugins : Shows a list of all the plugins with Help entries.
/help search [query] : Searches for [query] within it' entries.
/help reload : Reloads the entries from ExtraHelp.yml.

Plugin Support
Help requires that plugins tell Help about the commands they use. This makes sure that the commands and permissions are accurate and precise (rather than trying to auto fetch commands). Because it's ridiculous to assume that all plugins will instantly jump up and support Help (we can dream can't we? ), server admins can mimic this behavior by supplying...

Custom ExtraHelp/
I'll also cover how you can add custom commands to the /help menu here.

Each command has a "name", this name is only for you, as Help doesn't care about it (they just need to be unique names). In the following example the names are 'versions', 'pluginversions', 'kick' and 'essentialswho'. Within these Nodes you need 2 things: command, description, and plugin. These should be self-explanatory. The two optional pieces are "main" and "permissions"

The previously required "plugin" node has been replaced by the filename itself.

so if you have entries for "Minecraft", put those entries within "Minecraft.yml" in help's ExtreHelp folder.

If you have many commands & don't want them cluttering the same file (like worldedit), you can put them in a folder instead (the folder name will be the name used for plugin)

If you specify a "main", you can choose whether or not the command is important enough to show up on the main /help menu; if you leave it blank or skip it, it will default to 'false'

If you specify a "visible", you can specify whether the command shows up at all. This is useful for overriding other plugins' built-in Help support (in case you don't want all the commands); if you leave it blank or skip it, it will default to 'true'.

If you specify a "permissions", you can choose what is necessary for the user to see the command; and leaving it blank will allow all to see. So in the case of /version, all users can use it, so no permissions. But with /who, you have to have essentials.list, so that was specified. There is also a special permission case, "OP". By specifying this, this will require the user to be an OP to use the command (as is the case with Minecraft's built-in /kick command).

Code:

versions:
    command: version
    description: Show the version of Minecraft and CB
    plugin: CraftBukkit
    main: true
pluginversions:
    command: version [plugin]
    description: Shows the version of [plugin]
    plugin: CraftBukkit
kick:
    command: kick [player]
    description: Kicks [player] from the server
    plugin: Minecraft
    main: true
    permissions: OP
essentialswho:
    command: who
    description: Show who's one the server
    plugin: Essentials
    main: true
    permissions: essentials.list

How To Hook into Help.

Hooking into Help is extremely easy, and very similar to hooking into any permission-plugin. When your plugin is starting up, just grab the Help plugin and register your commands with Help's registerCommand() method; that's it! Here's the API and some examples. If you'd like a concrete example, check out the relevant source code from MyHome and BigBrother.

Help API

Code:

/**
 * Registers the given command, description, and plugin.
 * There are no permissions, so all users can see it.
 * It is also not a "main" help entry.
 * @return Whether or not it was successful
 */
public boolean registerCommand(String command, String description, Plugin plugin);

/**
 * Registers the given command, description, and plugin.
 * There are no permissions, so all users can see it.
 * You can set whether the plugin is a "main" entry or not
 * @return Whether or not it was successful
 */
public boolean registerCommand(String command, String description, Plugin plugin, boolean main);

/**
 * Registers the given command, description, and plugin.
 * You can specify one or more permissions.
 * If a user has permissions for at least (1) of them, he can see this command
 * It is also not a "main" help entry.
 * @return Whether or not it was successful
 */
public boolean registerCommand(String command, String description, Plugin plugin, String... permissions);

/**
 * Registers the given command, description, and plugin.
 * You can specify one or more permissions.
 * If a user has permissions for at least (1) of them, he can see this command
 * You can set whether the plugin is a "main" entry or not
 * @return Whether or not it was successful
 */
public boolean registerCommand(String command, String description, Plugin plugin, boolean main, String... permissions);

/**
* Gets the help text associated with this command
* @param command the command to lookup
* @return help text, or null if none
*/
public String getHelp(String command);

/**
* Gets all of the commands registered with this plugin
* @param plugin plugin to lookup
* @return list of commands
*/
public ArrayList<String> getPluginCommands(String plugin);

Basic Example

Code:

// plugin is the instance of your Plugin registering the commands
Plugin test = plugin.getServer().getPluginManager().getPlugin("Help");
if (test != null) {
    Logger log = Logger.getLogger("Minecraft");
    Help helpPlugin = ((Help) test);
    // Registers a main command. But all users will be able to see it
    helpPlugin.registerCommand("home help", "Help for all MyHome commands", plugin, true);
    // Registers a secondary command to our plugin (MyHome), but the user has to have the permission to see it
    helpPlugin.registerCommand("home", "Go home young chap!", plugin, "myhome.home.basic.home");
    log.log(Level.INFO, "'Help' support enabled.");
} else {
    Logger log = Logger.getLogger("Minecraft");
    log.log(Level.WARNING, "'Help' isn't detected. No /help support.");
}

Slightly More Advanced Example

Code:

Help helpPlugin = ((Help) test);
String[] permissions = new String[]{"bb.admin.watch", "bb.admin.info", "bb.admin.rollback", "bb.admin.cleanse"};
// If a user has any one of those permissions, they'll be able to see /bb help. A main command
helpPlugin.registerCommand("bb help", "Help for all BigBrother commands", plugin, true, permissions);
// If a user has "bb.admin.watch" they'll be able to see /bb watch [player]. A secondary command
helpPlugin.registerCommand("bb watch [player]", "Toggle the watch on [player]", plugin, permissions[0]);

Plugins with Help Support
Here's a quick list of plugins (and version) that have built in Help support.
- MyHome v1.9.2+
- MyWarp v1.10.3+
- BigBrother v1.6.4+
- Citizens v1.0+
- General 3.1+
- TelePlus 1.6+
- Pixl 1.3+
- Vampire 1.3+
- BetterShop 1.6.2+
- Wormhole-X-Treme 0.812+
- Tele++ v1.3.4

ExtraHelp Packs
FabianN put together a repository of entries for your ExtraHelp/ that represent other plugins' commands. It's really awesome and was helped put together by others from the community.

Preview




Changelog

Version 0.3.2 - 7/21/11

• lowered chat fill size.. should fix some wrapping issues

Version 0.3.1 - 7/7/11

• fixed NullPointerException on entry save when no permissions

Version 0.3 - 7/6/11

• fixed loading help & plugin help registering before plugin onEnable

Version 0.3 beta2 - 7/4/11

• plugin console output fixed
• console output width changed for when running windows
• plugin help override can be disabled (default)
  • plugin help registering is ignored if the command exists already
  • alternatively, can be disabled completely
• saving of registered commands can be disabled (also, now saves to file, not "_orig" files)
• ExtraHelp now uses filename as plugin name (plugin field no longer used)
• added formatting options:
  • shortenEntries : can show in old, one-line style
  • chat line (useWordWrap:false) - minecraft chat wraps to next line
  • columns (useWordWrap:true) - command on left, description in word wrap line(s)
    • can be right-aligned (wordWrapRight:true)
• plugin entries can be set to not sorted (listed in the order found in the help file)
• "/help reload" is now op-only
• "ExtraHelp.yml" will now be converted (again.. seems to have been removed somewhere..)
• ExtraHelp supports a multi-directory structure (like FabiaN's help package) (plugin name will be the directory name)
• improved node error messages when loading
• fixed permissions 3x illegalAccessErrors on load (and api errors)

Version 0.2.4.1 - 4/4/11

• another illegalAccessError (hopefully) resolved

Version 0.2.4 - 4/2/11

• updated an illegalAccess error that was occurring in 617

Version 0.2.3 - 3/25/11

• fixed a null pointer exception in plugin help

Version 0.2.2 - 3/24/11

• various null pointer fixes (could have nullpointerException on load without)
• improved help listing
• added console help support

Before i started maintaining:

Help v0.2 [531]
Released 15 Mar, 2011
- Built with latest recommend build (531)
- Multiline support. Descriptions of commands can now be as long as you'd like.
- Separated ExtraHelp.yml into separate YML files (for each plugin, etc).
- Plugin overriding. Don't like how a plugin has their Help support? Completely customize their entries.

Help v0.1.1 [493]
Released 6 Mar, 2011
- Built with latest recommend build (493)
- Updated for GroupManager 1.0

Help v0.1 [440]
Released 28 Feb, 2011
- Intial Release
[\spoiler]