Developer API
Flags supports a full compliment of hooks to allow developers to create new flags, monitor the state of existing flags in specific areas, and create event handlers to manage the effects of a flag. You can use these tools in your existing plugin or you can create a new plugin just for creating flags (called a "module").
Note to system developers: If you are reading this and you are the developer of one of the supported land management systems or other plugin dependencies, please be aware that you CAN NOT put flags into that plugin. To do so would create a circular soft dependency. Flags must be added as a separate module in that case.
The following documentation has been updated to reflect the new and improved Flags v2 API coming soon.Flags v2 Javadocs
Project Source
| Flags Source Code | Flags Javadocs | Core Module |
| Block Module | Border Patrol Module | Creature Spawn Module |
| Damage Module | Player Module | Vehicle Module |
For an example of integrating optional flags into existing plugins, take a look at the RocketTeleport or HardcoreClaims source.
Before You Begin
This guide covers the basic set of tools designed for implementing flags in a plugin. However the API is powerful and capable of being used for area work without adding any flags at all. This tutorial is not exhaustive list of the API capabilities. If you need further help, you should take a look at the source code and javadocs. If you've done all of that and your still at a loss, post a Flags related question on the Flags Developer Forum. For general Bukkit questions, visit the Bukkit Plugin Development Forum.
Validation
Flags does not do your job as a programmer for you. There is no "defensive validation" in Flags, but the API has been annotated with @Nullable and @Nonnull and this should be treated as a contract. I recommend using the JetBrains IntelliJ IDEA compiler as it makes full use of the annotations and warns you when you may be passing a null object into an annotated method, other compilers may or may not. It also makes Maven and GitHub much easier than alternatives.
Standards & Guidelines
There is nothing required about your implementation of Flags, however in order to be consistent and not confuse users, below are a set of recommended guidelines you can follow. I do not police plugins or restrict them from appearing on the Flags page for not following these guidelines. They are merely suggestions.
- Use the built-in bypass permission, rather than creating your own OR create your own but have the bypass permission mimic it. Flags creates a permission node and registers it with Bukkit for all flags on the system. This node is "flags.bypass.<flagname>" and can be retrieved automatically from the Flag class Flag.getBypassPermission(). Flags does creates this bypass permission for you and uses it in the hasTrust method. It is up to you to implement it. Leaving the bypass permission unimplemented may leave players wondering why it isn't working and hasTrust will be ineffective for the bypass permission.
- Do not use the flag or bundle permission. The flag permission (Flag.getPermission()) is used to determine if the player is allowed to set a flag, this is handled by Flags' itself and there is no need to implement this permission. It is not recommended that you use it for other purposes.
- Bypass permissions and Trust Lists typically override the 'off' state of the flag. The off state could be true or false, but when your denying all players an action, the bypass permission and trust lists should allow those players to do it anyway.
- Trust Lists should not override the 'on' state of the flag. If the flag is set to allow everyone to do something, the trust list should be ignored rather than overriding the flag's state. I.E. The presence of a name on the trust lists should not automatically change the state of the flag.