Help Files
From Essentials
For your server to become popular, you need to be able to help the players find their way around your server, including helping them learn the commands. With this in mind Essentials has a number of methods you can keep your players up to date, and can provide custom help to each user.
The most obvious method is the /help command, this command will generally produce a list of commands, unique to that users permissions, of what they can and cant use. There is also the /motd command and MOTD on connect, which can store server broadcasts, as well as the server rules (/rules), and finally /info which can store any other important information you need to keep on hand.
Contents
Help
The help command can be used in 4 ways. The default is to allow essentials to parse your plugins and produce a list of commands they all provide.
Essentials supports a permissions based '/help' system in which if the plugin provides the permission node in its plugin.yml, it will only be shown to the user on /help if they have access to the command.
Essentials will try it's best to create a list of all available commands, but not all plugins follow the rules and properly register their commands with Bukkit, and not many plugins seem to be utilising the permission feature in Bukkit fully, nonetheless there are ways around this, and if you end up showing a few commands to users who can't use them, the worst that can happen is they get a little error message about not having access.
Automatic 1
non-ess-in-help: true hide-permissionless-help: true
In this mode Essentials will loop through all available plugin information and build a customised /help list, of just commands it is certain players can use. In this mode, it is common for server owners, to list the help command for other important plugins in the message of the day.
If a plugin does not provide the appropriate permissions node in its plugin.yml, the commands listed within will be ignored. You can manually add plugins to this list by giving the group access to a special permission. If a group has 'essentials.help.<pluginname>' (lower case) for example 'essentials.help.lwc', that group will see all LWC commands in addition to the normal commands they would see. This is useful for adding a few missing plugins, if you don't mind a few extra commands being added.
Automatic 2
non-ess-in-help: true hide-permissionless-help: false
In this mode, Essentials will hide commands it knows that a user can't use, but will display all the commands it is unsure about. This means that virtually all plugin commands that can be used, will be visible, but often there will be quite a few commands the user can't use.
If a plugin does not provide the appropriate permissions node in its plugin.yml, it is assumed that all players should be able to use it, and it will be displayed in '/help'. If you find a plugin is showing up incorrectly, you have several choices:
- Construct the help files manually using the method shown below.
- Disable essentials from showing any external commands in its /help list (Mode 1 above). And configure the motd or /info for other plugins.
- Modify the plugin's plugin.yml in the root of the plugin's .jar file.
- Contact the plugin owner to get this fixed.
Automatic 3
non-ess-in-help: false
Essentials /help will only list commands from essentials. Players will only be able to see commands from essentials that they have the permission to use.
Manual
If you require a more customizable '/help', and '/info' wont suffice you can define your own '/help' by providing either a 'help.txt' or a 'help_<groupname>.txt' in the essentials folder. This system is similar to the one used by /info with more information below.
Manual Files
Like the help system, the other info commands allows you to provide a separate set of help for different groups.
To use this system, simply create a text file with the correct naming convention in the essentials folder, and place the text you would like to see within it. This system allows for multiple pages (13 lines per page) and allows colours with the same syntax as the other config files. to define chapters, add "#" infront of the chapter name.
You can use the following tags in the manual files:
Display name: {PLAYER}
Username: {USERNAME}
IP: {IP}
Address: {ADDRESS}
Balance: {BALANCE}
Unread mails: {MAILS}
Current world: {WORLD}
Worlds list: {WORLDS}
Number of online players: {ONLINE}
Number of unique players who joined the server: {UNIQUE}
Player list: {PLAYERLIST}
Time of server: {TIME}
Date of server: {DATE}
Time of world PM/AM: {WORLDTIME12}
Time of world: {WORLDTIME24}
Date of world: {WORLDDATE}
Plugin list: {PLUGINS}
Version of Craftbukkit: {VERSION}
Naming convention
In these examples 'info' is the file being shown, these show the 3 different and overlapping systems used to get customised info
To create a global info file which works for all players create the file just called info.txt.
To make group based info files create a file 'info_<groupname>.txt' replacing <groupname> with the name of the group changed to lower case.
To make user based info files create a file 'info_<username>.txt' replacing <username> with the name of the user changed to lower case.
Info
The '/info' command is a useful one in that it can be used to provide a wealth of information to players. This is generally where most of server data can be found hidden, its possible to use keywords, chapters and pages, this can be useful for storing URL, contact information, and even extended help.
The /info command takes its text from a file named info.txt or similar file using the naming convention above.
The info command can also be used via signs, see the Sign Tutorial for more information
The following is an example of an info file containing 3 pages, a default and 2 sub pages.
Welcome to your info file, the following pages are available: /info website /info mumble #website Our website is http://website.com #mumble Our mumble server can be found at mumble.website.com
Motd
Essentials shows a 'message of the day' or MOTD to a user on connect. This is a prime place to both welcome users to the server and provide a quick summary of the commands users can use to get help. This should usually be limited to a few lines as that is all that is visible in the chat window, although you can see a longer message if you open the chat 'dialog'.
The /motd command and automatic greeting takes its text from a file named motd.txt or similar file using the naming convention above.
Essentials moved the MOTD out of the config.yml and into its own file (motd.txt) starting Essentials 2.7.1
Only users with the essentials.motd permission will see the MOTD on join or have access to the /motd command
On connect, up to 18 lines will be read from the top of the motd file, which should coincide with pages 1 and 2 from the /motd command, which like the rest of the commands is limited to 9 lines per page. This means you could inform users to use /motd 3 to continue reading the welcome news, but it would be more common to use pages for this sort of information, like the example below.
Welcome to our server, while your here please behave and follow the rules You can find a list of our rules using /rules You can find most command help using /help You can find a summary of our recent server updates by using /motd more #more We've recently updated to Minecraft 1.0, and are currently in the process of copying buildings....
Rules
The next customisable reference system is the rules. This is typically used to tell the players what they can and can't do.
Essentials moved the rules out of the config.yml and into its own file (rules.txt) starting Essentials 2.7.1
The /rules command takes its text from a file named rules.txt or similar file using the naming convention above.
Help
As mentioned above, you can use the same system to make a customised help command, this system has priority over the built in /help system, so if you place a help.txt file in the Essentials folder, it will read the information from there instead.
One useful feature of this, is that it will allow you to use the dynamic list for established members, while providing a simplified list for newbies or guests. This could be used as a tool to inform guests that they need to register to be promoted or similar means.
Book
In addition to the built in commands, you can also use the same file syntax in the book system. This allows you to spawn books pre-filled with content via commands or kits. This can be useful for creating rule books or used in adventure maps.
Note you cant use manual file tags on a book.
CustomText
Using a similar system to the above mentioned manual files, Essentials has a 'customtext' command which behaves slightly differently.
To use this command, you first need to create the custom.txt, if you type /customtext it should generate you an example copy of this file.
The first step is creating creating a 'chapter':
#vote If you add the correct alias to commands.yml This text here will be shown if you type /vote
Once this 'command' has been defined in the custom.txt, all you need to do is add it to Bukkit. You do this by editing the commands.yml in your Minecraft folder (the one with craftbukkit.jar and the Plugins folder).
You will simply need to add a alias with the command name you listed in custom.txt to the command 'customtext'.
You do this by adding/utilizing the 'aliases' section of the commands.yml.
aliases: vote: - customtext vote $1-
Once this is done, the only extra step you should need to do is give players access to the 'essentials.customtext' permission, so they can use the command.
