|
This page has been suggested for inclusion in the Official Documentation
|
Help.yml is a file that provides you with a wide variety of options for configuring the help system in your CraftBukkit server. The help system can be accessed from the chat window or server console by typing the /help command.
By default you should not need to modify help.yml. Help topics for all plugin commands are automatically provided by or extracted from your installed plugins. You only need to modify help.yml if you wish to add new help pages, add new index topics, or override the help pages of existing plugin commands.
Preview of /help
Sections in the YAML[]
The headings listed below are the top-level keys in the YAML file.
general-topics[]
The general-topics section is made up of a list of topics with attributes describing them. General topics are added the internal help index as separate items along with all the plugin command topics.
- Topic Name: (string) This is the name the /help command will use to locate a topic. Spaces are allowed and can be used to create sub-topics. Note: "Topic Name" is not the name of a yaml key. Use the actual name of your topic instead.
- shortText: (string) The short text is a brief description of a topic displayed next to the topic name in help indexes.
- fullText: (string) The full text is the full description of a help topic displayed when the user requests the help topic. This text can be as long as you like. The help system will automatically break it up into multiple pages.
- permission: (string) The permission node required to see a help topic. If left blank (Ex: permission: [] ), the help topic will be visible to all players.
Preview of general-topics
Example
general-topics:
Rules:
shortText: Rules of the server
fullText: |
&61. Be kind to your fellow players.
&B2. No griefing.
&D3. No swearing.
permission: topics.rules
index-topics[]
Index topics are similar to general topics, except instead of displaying pages of information they display a list of more help topics. Index topics are added to the internal help index as separate items along with all the plugin command topics.
Index topics are automatically security trimmed so that no player sees any commands requiring permissions they do not have. When an index topic is displayed, the user's permission set is compared against the permission requirements of each topic in the index and any that do not match are omitted.
Note: To override the default help index displayed when /help is called with no arguments, create an index topic called "Default".
- Topic Name: (string) This is the name the /help command will use to locate a topic. Spaces are allowed and can be used to create sub-topics. Note: "Topic Name" is not the name of a yaml key. Use the actual name of your topic instead.
- shortText: (string) The short text is a brief description of a topic displayed when an index topic is included in another index topic.
- preamble: (string) A message to display on the first page of an index topic before any of the topics in the index.
- permission: (string) The permission node required to see a help topic. If left blank (Ex: permission: [] ), the help topic will be visible to all players.
- commands: (string list) A list of help topic names included in the index. Any command that can be displayed using the /help command can be included here. Use the same name here as you would use to display a topic in the /help command.
Preview of Help Index
Example
index-topics:
Ban Commands:
shortText: Player banning commands
preamble: Moderator - do not abuse these commands
permission: op
commands:
- /ban
- /ban-ip
- /banlist
- Rules
amend-topics[]
Topic amendments are used to modify or replace the contents or permission requirement for any automatically generated help topic. You can use topic amendments to complete the help topics for plugins that do not yet properly support the Bukkit help system or augment those topics with your own commentary.
Note: When amending a topic's short or full text, you can use the string "<text>" to insert the existing topic text.
- Topic Name: (string) This is the name of the topic you wish to amend. This topic name must match the name used to display the help topic exactly.
- shortText: (string) The new short text for the topic. Can be omitted.
- fullText: (string) The new full text for the topic. Can be omitted.
- permission: (string) A new permission node to apply to the topic. Can be left blank (Ex: permission: [] ).
Example
amended-topics:
/stop:
shortText: Stops the server cold....in its tracks!
fullText: <text> - This kills the server.
permission: you.dont.have
ignore-plugins[]
The ignored plugins list is a list of plugins that the help system will skip when generating automatic help topics. Ignored plugin names must exactly match the plugin name as displayed in the /plugins command. Ignore "Bukkit" to skip the standard Bukkit commands. Ignore "All" to completely disable automatic help topic generation.
Example
ignore-plugins: - PluginName - Bukkit - All
If you still want automatically generated help topics for plugin commands but do not want them filling up your default help index, set command-topics-in-master-index to false. The automatically generated help topics will still be available to the /help command and can be included in custom index topics, but they will no longer be shown in the default help index. Only general topics and index topics will remain.
Example
command-topics-in-master-index: true
Text Color And Formatting[]
All text fields in help.yml support Minecraft color codes. The color code escape character is "&" followed by a Minecraft color or formatting code.
| Code | Effect |
|---|---|
| &0 | Black |
| &1 | Dark Blue |
| &2 | Dark Green |
| &3 | Dark Aqua |
| &4 | Dark Red |
| &5 | Dark Purple |
| &6 | Gold |
| &7 | Gray |
| &8 | Dark Gray |
| &9 | Blue |
| &A | Green |
| &B | Aqua |
| &C | Red |
| &D | Light Purple |
| &E | Yellow |
| &F | White |
| &K | Magic |
| &L | Bold |
| &M | Strike through |
| &N | Underline |
| &O | Italic |
| &R | Reset |
Example
&B2. No griefing.
Preview of Plugin Commands
Preview of Plugin Indexes
Preview of Default Alias Topics
Automatically Generated Help Topics[]
The Bukkit help system automatically populates the internal help index with topics derived from the loaded plugins. Four different type of topics are created:
- Command topics are created from the plugin's command descriptions in the [plugin.yml] file.
- Plugin indexes are created for each plugin and list all the commands owned by that plugin.
- Alias topics are created for each command alias.
- An Aliases index is created to list all the command aliases registered in the server.
Automatic Plugin Commands[]
The default command topics contain name, description, usage, and alias information for each command.
Automatic Plugin Indexes[]
Plugin index topics list all the commands owned by a plugin and are listed under the plugin's name.
Automatic Alias Topics[]
Alias topics automatically display the help for the command they are an alias for. Alias topics are not included in the default help index and are instead only displayed in the Aliases help index. (/help Aliases)
Topic Load Order[]
Normally, topic load order is not something you need to worry about as the Bukkit help system is designed to do the right thing. Topic load order only comes into play when two help topics have exactly the same name. In the event of a name conflict, the help topic registered first keeps the name. The second help topic is completely ignored. Because general and index topics in help.yml are loaded before any automatically generated topics, they will mask out any content created for a plugin.
The topic load order is:
- general-topics in top-to-bottom order
- index-topics in top-to-bottom order
- Topics programmatically added by plugins at load time
- Automatically generated plugin command topics
- Automatically generated command alias topics
- Automatically generated bukkit command topics
- The Aliases index topic
- Plugin index topics
- Apply amend-topic content and permission amendments