Flags

Two kinds of flags

Type	Java type	Typical use	Examples
Environment flag	EnvFlag	Claim environment rules that do not depend on player identity	Flags.FIRE_SPREAD, Flags.CREEPER_EXPLODE
Permission flag	PriFlag	Actions that players, members, groups, and guests may perform	Flags.PLACE, Flags.CONTAINER, Flags.TELEPORT

EnvFlag is mainly consumed by Dominion’s environment events. PriFlag must be checked together with a player and a location. Do not mix the two in checkPrivilegeFlag or checkEnvironmentFlag.

Use built-in flags

boolean canBuild = DominionAPI.getInstance().checkPrivilegeFlagSilence(
        location,
        Flags.PLACE,
        player
);

EnvFlag flag = Flags.getEnvFlag("creeper_explode");
PriFlag privilege = Flags.getPreFlag("container");

The lookup method in the current source is indeed getPreFlag(String). This spelling is part of the released API; do not change it to the nonexistent getPriFlag.

Flags provides these enumeration and lookup methods:

Method	Description
getAllFlags()	All registered flags
getAllEnvFlags() / getAllPriFlags()	All flags by type
getAllFlagsEnable()	Flags where getEnable() is true
getAllEnvFlagsEnable() / getAllPriFlagsEnable()	Enabled flags by type
getFlag(String) / getEnvFlag(String) / getPreFlag(String)	Look up by getFlagName()

Use these lists as read-only snapshots or query results. Do not add objects to them from an addon; use registerEnvFlag or registerPriFlag to register a flag.

Flag metadata

Every Flag contains:

• getFlagName(): the unique programmatic name;
• getDisplayName(), getDescription(): default display text;
• getDefaultValue(): the default when no separate value is configured;
• getEnable(): whether the flag is enabled;
• getMaterial(): the icon material used in Chest UI;
• getDisplayNameKey(), getDescriptionKey(): language-file keys;
• getConfiguration...Key(): configuration-field keys.

Flag metadata can be changed with methods such as setDisplayName, setDescription, setDefaultValue, setEnable, and setMaterial. After changing default configuration or display information, call Flags.applyChanges() and wait for it to complete.

Register custom flags

public static final EnvFlag NO_RAIN = new EnvFlag(
        "no_rain",
        "No Rain",
        "Whether rain is blocked in this dominion.",
        false,
        true,
        Material.SUNFLOWER
);

public static final PriFlag USE_SPECIAL_TOOL = new PriFlag(
        "use_special_tool",
        "Use Special Tool",
        "Whether players may use the special tool.",
        false,
        true,
        Material.BLAZE_ROD
);

boolean envRegistered = Flags.registerEnvFlag(this, NO_RAIN);
boolean priRegistered = Flags.registerPriFlag(this, USE_SPECIAL_TOOL);

if (envRegistered || priRegistered) {
    Flags.applyChanges().thenRun(() ->
            getLogger().info("Dominion custom flags are ready."));
}

Registration fires FlagRegisterEvent. Other plugins can cancel the event, so always check the Boolean returned by the registration method. Flag names must be unique across all registered flags; use lowercase with underscores or hyphens and include your own plugin prefix.

Custom flags do not implement in-game behavior automatically

Registering NO_RAIN does not stop rain automatically, and registering USE_SPECIAL_TOOL does not change interaction permissions automatically. The addon must listen to the relevant Bukkit/Paper events and call:

if (!DominionAPI.getInstance().checkEnvironmentFlag(location, NO_RAIN)) {
    // Decide how your addon handles NO_RAIN.
}

The addon is responsible for the specific event, cancellation timing, and thread handling. A flag only provides Dominion’s storage, query, UI display, and permission-data entry points.

FlagGroup

FlagGroup is only for logical grouping, display, and batch editing; it does not participate in permission calculation. Use EnvFlagGroup for environment flags and PriFlagGroup for permission flags:

EnvFlagGroup weather = new EnvFlagGroup(
        "weather",
        "Weather",
        "Environment rules related to weather.",
        Material.SUNFLOWER
);
weather.addFlag(NO_RAIN);
FlagGroups.registerEnvFlagGroup(this, weather);

Group IDs must match [a-z0-9_-]+ and cannot be the reserved ungrouped. Manage group members with setDisplayName, setDescription, setMaterial, addFlag, removeFlag, and containsFlag.

Main FlagGroups methods:

Method	Description
registerEnvFlagGroup / registerPriFlagGroup	Register an environment or permission group
unregisterEnvFlagGroup / unregisterPriFlagGroup	Unregister a group by ID
getEnvFlagGroup / getPriFlagGroup	Query a group by ID
getEnvFlagGroups / getPriFlagGroups	Get registered groups
getUngroupedEnvFlags / getUngroupedPriFlags	Get dynamic groups of flags not in any group
getRevision()	Get the group registry revision

Apply changes

Flags.applyChanges() returns a CompletableFuture<Void> that can be used to wait for custom flag and group changes to finish:

Flags.applyChanges().thenRun(() -> {
    // The flag application flow is complete here.
});

The old Flags.applyNewCustomFlags() is deprecated and does not provide a completion Future that callers can observe. New code should use applyChanges().