Developer API/Flag Registration
Registering a New Flag
Single Flag Registration
If you intend to create your own custom flags, you will need to tell Flags to monitor it. To do this, we register the flag in one of two ways, depending on the functions you want to be available. If you intend for your flag to be player based, you may want to allow messages and trust lists. If your flag is world based, then it is not necessary to provide the extra information. Below is a list of details about your flag that you will need to register with Flags. As with much of the the methods you will want to gain access to, you will use the Flags API class to access the active Registrar class.
| Name | This should be as unique as possible, other plugins using the same name could cause conflicts. Choose wisely, once you start using a flag name, changing it will cause a disconnect with the data users have created. | String |
| Description | This is the description of your flag that will appear when using the /flag help command. | String |
| Default | Boolean value to specify the normal state of the flag. | boolean |
| Group | The group the flag is filed under on /flag help command. If you don't have a group use your plugin's this.getName(). Do not include spaces as these will cause the group name to be viewed as two arguments when using the help command. | String |
| AreaMessage | The default message to use for defined areas. | String |
| WildernessMessage | The default message to use for undefined areas of the world. | String |
Example:
Registrar flagsRegistrar = FlagsAPI.getRegistrar(); // Register a non-player flag Flag flag = flagsRegistrar.register(name, description, def, group); // Register a player flag Flag playerFlag = flagsRegistrar.register(name, description, def, group, areaMessage, wildernessMessage);
Batch Registration
It is now possible to register multiple flags from a YAML file provided from your plugin's resources. However this YAML file has a very specific format.
YAML Formatting
Flags uses the ConfigurationSection of your choice to do a batch registration. All flags must be immediately below this key and no other data should be below this key. Below the ConfigurationSection can be any number of keys that are named exactly as the flag will be named. Below the flag name can be a number of options.
| Value | Data Type | Description | Required |
| Description | String | Provides the help description of the flag | Y |
| Default | Boolean | Sets the default value, true if not specified. | N |
| Player | Boolean | Sets if the flag is meant to be a player flag, false if not specified. | N |
| MinimumAPI | String | Sets the minimum Bukkit API version (x.x.x) this flag applies to. If the API is too low, the flag is not registered. It is strongly recommended that you omit this entirely if your flag runs on 1.7.5 (minimum version for Flags v2). | N |
| AreaMessage | String | Sets the default message for the player flag. Required if Player is true. | Y* |
| WildernessMessage | String | Sets the default wilderness message for the player flag. Required if Player is true. | Y* |
Example
MyFlagName: Description: 'This is my flag!' Default: false Player: true AreaMessage: 'You have activated my flag in an area!' WildernessMessage: 'You have activated my flag in the wilderness!' MinimumAPI: 1.8.0
Registration
Registration is done by creating a ConfigurationSection (or subinterface such as YamlConfiguration) that points directly to the location of the Flag name keys. There should be nothing but intended Flags in this ConfigurationSection. You may use any String as a group name, however the plugin name (this.getName()) makes a good choice.
YamlConfiguration flagConfig = YamlConfiguration.loadConfiguration(getResource("flags.yml")); Collection<Flag> flags = FlagsAPI.getRegistrar().register(flagConfig, this.getName());
Comments