[ENHANCEMENT] Help API

Discussion in 'Plugin Development' started by Don Redhorse, Aug 14, 2011.

Thread Status:
Not open for further replies.
  1. Offline

    Don Redhorse

    Bukkit and the plugins are great and all people concerned (developers, bukkit team, people helping in the forums) are doing a great job. But bukkit is on a rocky road and the usuability for the admin and user isn't at the point where it should be.

    This thread is ONE part of several threads, please do me the favour and read them all and only reply in here with information which help this thread become productive. Thanks..

    Bukkit has the following issues:

    Permissions... different plugins, different concepts, complicated, error prone and shattered
    Help.. complicated, not to the point, not really translatable / customizable.
    Aliases.. Complicated and plugin specific
    Forums.. Difficult to navigate and missing structures
    Plugins.. Plugin Standards allow for to many issues

    One of the most complicated things for the average user joining a bukkit server is ... what can I do...

    So he does a /help .... and quits...

    /help isn't usefull atm as it shows to much or not enough information, mainly because there is no common base for plugins to build upon. HELP is a core functionality of any program, but bukkit is negleting it.

    What do we need as an output from help?

    /help should give

    /help plugin1: Warp Commands
    /help plugin2: Creative Commands
    /help plugin3: Economic Commands

    /help plugin1 should give
    Warp Plugin x.y
    /help plugin1 command: for more help about this command
    /plugin1 add: add a new warp


    and ofcourse it should only show commands which are available to the player based on permissions.

    So how could a help api look like? Which functions should it support?

    registering the pluginhelp.yml file to show list of plugins with /help
    registering the generic description of the plugin from pluginhelp.yml
    registering the plugin commands from pluginhelp.yml
    registering the plugin command description from pluginhelp.yml
    perhaps even creating the pluginhelp.yml if not existing if the information necessary is already in the plugin atm.
    displaying help information based on permissions

    using a pluginhelp.yml file in the plugindirectory would allow for full translation to other languages than english. It would also allow for more customization like removing some commands from help even if the permission is there.

    Using a structure like above would make help ingame readable again and would allow plugins still to support /plugin3 help: for more help about this plugin..

    Supporting the help api should become a requirement to be an approved plugin.

    What do you think?
     
  2. Offline

    Celtic Minstrel

    I'm not sure if I quite understand your proposal, but I'm going to put forth a (probably similar) proposal of my own. It'll be heavily influenced by the Help plugin, and try to address some of its flaws.

    So, for the most part, the output of /help would be for getting usage info on the various commands. The plugin.yml already has usage info for each command, but it's not flexible enough for some of the more complex commands that plugins provide. The Help plugin associates a command string with usage note, a plugin, and a set of permissions, but requires the help be hard-coded in your code. (It does read from yml files as well, but the expectation is that the server administrator will create those.)

    So, the two main existing methods of providing help for commands are both inadequate.

    Then there's the need for help for other things that are not commands. For example, "how to edit signs using SimpleSignEdit". Or "Rules on this server".

    Most help topics can be linked to either a command or a plugin, though some (such as server rules) would be linked to neither. A help menu would need to be hierarchical, of course; everything belonging to one plugin is listed under that plugin, for example. Mostly what is needed is a storage place for these topics. If that's provided by a Bukkit API, then the actual /help command could still be provided by a plugin (and other plugins might provide other ways of viewing the help database). I will now attempt to define the structure of the help storage.

    So, there's a global list of help topics, probably stored in the Server. There should probably be a help topic interface something like this:
    Code:
    public interface HelpTopic {
      Plugin getPlugin();
      Command getCommand();
      String getName();
      HelpTopic getParent();
      String getHelp();
      Set<Permission> getPermissions(); // or maybe Set<String>?
      Set<HelpTopic> getChildren();
      boolean hasPermission(Permissible who); // see if a Permissible is allowed to view this topic
    
    The following topics would appear at the top level:
    • One topic for each plugin that registers help in its plugin.yml (or similar location). Its subtopics would be:
      • Any "global topics" the plugin registers in its plugin.yml
      • A topic for any "category" that a command has assigned to it; the subtopics of this would be one topic for each command with that category assigned
      • A topic for any command without an assigned category
    • A topic called "Bukkit" which contains as subcategories the help topics for /version, /plugins, and /reload
    • A topic called something like "Vanilla" or "Minecraft" which contains as subcategories the help topics for all the vanilla commands
    • Any "global topics" defined in the server-level help.yml; this could be things like rules, for example

    A command topic may be a leaf topic, or it may have subtopics relating to subcommands or different uses of it.

    Defining help topics would be fairly straightforward; you just need a configuration node such as this:
    Code:
    name: 'My Topic'
    help: |
        This is where the contents of your topic goes
    permissions: [node.the.first, node.the.second]
    children:
      subtopic1: { ... another node here ... }
    
    The Help plugin is basically this plus a "command" key; it may be nice to also support that key as a special case. If so, its contents would be formatted on load according to some rules and it would then be prepended to the contents of the "help" key; once loaded, they would be inseparable (unless you want in-game modification of help, but I think there's little point in allowing that).

    And where would those nodes go?
    • Under the "help" key for a specific command in the plugin.yml. I think the "help" key could either replace or supplement the existing "usage" key. It would deprecate the non-standard "permission" or "permissions" key.
    • Under any key directly under the "help" key at the top level of the plugin.yml
    • Under any key directly under the "children" key of another node
    • Under any top-level key in the server-level help.yml file

    And for the functioning of the /help command? Most basically it should be "/help topic" to view a particular topic, and "/help topic subtopic" and so forth... but with one caveat. The Command class should have a getHelp() method to retrieve its help topic, so if you type "/help command" it's equivalent to typing "/help plugin-that-provides-command command".

    It would also be nice for /help to be contextual, but since the actual behaviour of /help will most likely be left to a plugin, I won't go into that at the moment.
     
  3. Offline

    Supersam654

    @Celtic Minstrel Are you aware of the AutoHelp plugin? It basically makes all plugins compatible with Help. Also, almost everything is completely customizable and I believe you can add in your idea of "tutorials" by creating a couple files of your own. Also, before you start suggesting complex yml configuration options (which IMO are easy to understand and make perfect sense from a dev point of view), take a peak at the Permissions thread. Oh wait, you don't even have to bother going there because most people don't even realize that Permissions problems belong in the Permissions thread. Instead, they simply post them in every single forum ever! Although Permissions has some bugs, 95% of these posts are dealing with incorrectly formatted yaml files. Although your system works and I think would really give knowlegable server owners quite a bit of control over their servers, it is a fancy yaml configuration and Permissions is a testament to how that turns out.
     
  4. Offline

    Celtic Minstrel

    Well, 90% of the configuration work in my proposal would be the developer's responsibility, and a developer really should know how to deal with YAML. So I don't think that particular aspect of your argument is valid. It's true that I mentioned a help.yml for server-global help, but the majority of help would come from each plugin's plugin.yml.

    I am aware of the AutoHelp plugin, but it relies on the limited usage parameter and the non-standard permission parameter to really do its job well. As a result, it does not do its job well in general. Yes, it works, but it's more of a workaround than a true solution.
     
  5. Offline

    Supersam654

    I can't argue too much as far as "work around" is concerned. However, implementing this into bukkit would be a lot of work seeing as there is no existing framework within bukkit that would even begin to deal with this (aside from yaml reading). Because of this, I feel that this issue should really take the backburner or have a plugin dev deal with it simply because IMHO think that there are some far bigger issues that need to be addressed beyond the unruly help system.
     
  6. Offline

    Don Redhorse

    well... why not let somebody code it but integrate it in bukkit? especially as it requires changes to the plugins internally.

    if it isn't a requirement or within bukkit developers will not use it and for the admin it is one more plugin to install to get a core functionaltiy in my opinion.

    I like the idea of @Celtic Minstrel as far as I can follow... which is quite far.

    Concerning yaml... well I agree, but it would be mainly for one file which the admin needs to configure... perhaps using a different syntax and not yaml for that?

    Concerning yaml and permissions and posts... => forum structure... look at the threads... 65000 replies.. thread search very hidden.. and ofcourse people not reading... a night mare for everybody..

    some stuff can be changed but not everything i know
     
  7. Offline

    Celtic Minstrel

    I recall the Bukkit devs liking tkelly's Help quite a bit, so if someone put in a pull request to add help storage to the Bukkit core I think they'd probably at least consider it.
     
  8. Offline

    Don Redhorse

    I have no idea how to do that. Also tkelly's help needs some update in functionality ... but it is quite fine... still using it.. but it doesn't support permission based showing of help.
     
  9. Offline

    Celtic Minstrel

    Uh, yes it does. However, if you're using AutoHelp I could understand how you might think that.
     
Thread Status:
Not open for further replies.

Share This Page