API Integration#

Other plugins integrate against the small, versioned FlagForgeApi interface (flagforge-api module), obtained via Bukkit's services manager.

Setting up the dependency#

With development access (the development add-on, or a development-only license), your account page has flagforge-api-<version>.jar, with -sources.jar and -javadoc.jar for your IDE, next to each Stable and Nightly download. Build against the API of the newest stable release at or below the FlagForge version your server runs; the Nightly's API jars are for testing against unreleased changes. FlagForge's own plugin jar already contains these classes at runtime, so compile against the API jar only; never shade it into your plugin.

Gradle (Kotlin DSL), with the three jars in your project's libs/ folder:

dependencies {
    compileOnly(files("libs/flagforge-api-1.1.0.jar"))
}

Maven, after mvn install:install-file -Dfile=flagforge-api-1.1.0.jar -DgroupId=dev.szalik.flagforge -DartifactId=flagforge-api -Dversion=1.1.0 -Dpackaging=jar:

<dependency>
  <groupId>dev.szalik.flagforge</groupId>
  <artifactId>flagforge-api</artifactId>
  <version>1.1.0</version>
  <scope>provided</scope>
</dependency>

In your plugin.yml (or paper-plugin.yml), load after FlagForge without requiring it:

softdepend: [ FlagForge ]

Keep FlagForge optional: look the API up once on enable, and touch FlagForge's classes only when it's there. A plugin that references FlagForgeApi directly in a field or method signature fails to load with NoClassDefFoundError on a server without FlagForge, so keep every FlagForge call in one small class that is only created when the API exists:

// In onEnable:
if (getServer().getPluginManager().isPluginEnabled("FlagForge")) {
    flagForge = new FlagForgeHook(this); // the only class that imports dev.szalik.flagforge.api
}

// Everywhere else:
if (flagForge != null) {
    flagForge.recordReward(player, item);
}
final class FlagForgeHook {
    private final Plugin plugin;
    private final FlagForgeApi api;

    FlagForgeHook(Plugin plugin) {
        this.plugin = plugin;
        this.api = Bukkit.getServicesManager().load(FlagForgeApi.class);
    }

    void recordReward(Player player, ItemStack item) {
        if (api != null) {
            api.recordItemTransaction(plugin, TransactionSpec.forItem(
                "MYPLUGIN_REWARD", player.getUniqueId(), TransactionSpec.Direction.CREDIT,
                item, Duration.ofSeconds(5)));
        }
    }
}

Compile against the API jar of the version your server runs: your account page offers the one that goes with each Stable and Nightly download.

Examples#

FlagForgeApi api = Bukkit.getServicesManager().load(FlagForgeApi.class);
if (api == null) {
    return; // FlagForge isn't installed/enabled
}

// Declare a plugin-granted reward before mutating inventory, so reconciliation doesn't flag it
// as an unexplained gain.
TransactionSpec spec = new TransactionSpec(
    "ECONOMY_REWARD", player.getUniqueId(), TransactionSpec.Direction.CREDIT,
    "minecraft:diamond", 100, Duration.ofSeconds(30));
TransactionHandle handle = api.beginItemTransaction(this, spec);
giveDiamonds(player, 100);
api.completeItemTransaction(handle);

// Items with enchantments, a custom name/lore, custom model data or potion contents must be
// declared exactly - a material-only declaration does not match them and the player is still
// flagged. recordItemTransaction declares and completes in one call, right after giving it.
ItemStack kitSword = createKitSword();
player.getInventory().addItem(kitSword);
api.recordItemTransaction(this, TransactionSpec.forItem(
    "KIT_STARTER", player.getUniqueId(), TransactionSpec.Direction.CREDIT,
    kitSword, Duration.ofSeconds(5)));

// Grant a temporary, scoped exemption (e.g. inside your own arena/minigame plugin).
ExemptionSpec exemption = new ExemptionSpec(
    ExemptionSpec.ScopeType.CATEGORY, "COMBAT", "PvP arena zone", Duration.ofMinutes(10));
ExemptionHandle exemptionHandle = api.exempt(this, player.getUniqueId(), exemption);
// api.revoke(exemptionHandle); once the arena match ends, to end it early.

// Submit a finding from your own detection logic into FlagForge's pipeline/alerting.
api.submitFinding(this, new ExternalFinding(
    "myplugin.suspicious_teleport", Category.MOVEMENT,
    EvidenceClass.HEURISTIC, player.getUniqueId(), 5, 0.6,
    "Teleported across dimensions with no known API cause", Map.of()));

// Read a player's current aggregated risk (available once at least one finding has fired them
// through the policy engine this session).
Optional<PlayerRiskView> risk = api.risk(player.getUniqueId());

// Authorize your own plugin's items to exceed a vanilla limit, so inventory.illegal_item.a /
// inventory.illegal_stack.a never flag them - e.g. a custom enchant plugin's own Efficiency 10
// pickaxes. Server-wide and permanent (not player- or time-scoped) until revoked or this plugin
// disables, at which point every authorization it issued is revoked automatically.
ItemAuthorizationSpec authorization = new ItemAuthorizationSpec(
    "minecraft:diamond_pickaxe", ItemAuthorizationKind.ENCHANTMENT_LEVEL,
    "minecraft:efficiency", 10, "MyEnchantPlugin's crate-exclusive pickaxes");
ItemAuthorizationHandle authorizationHandle = api.authorizeItem(this, authorization);
// api.revokeItemAuthorization(authorizationHandle); if you stop handing these out.

Every handle validates the calling plugin's ownership (a handle from one plugin cannot be completed/revoked by another) and expires — an abandoned or expired handle is ignored, never silently trusted. ItemAuthorizationHandle is the one exception to expiry: it stays active until explicitly revoked or the issuing plugin disables. See the Javadoc on each flagforge-api class for full method contracts.

Finding which plugin caused a flag#

When inventory.reconciliation.a flags an item gain nothing explained, its evidence (shown by /ff finding <id>) includes clues to where the items came from, when there are any:

Field Meaning
recentPluginInventory The last plugin-made inventory the player opened within the last two minutes: <Plugin> (<holder class>) when its holder is a plugin's class, the class alone if FlagForge can't tell which plugin loaded it, or a plugin's chest menu (no holder) for a menu created with Bukkit.createInventory(null, ...).
recentPluginInventorySecondsAgo How long before the inventory snapshot that menu was opened.
recentCommand The last command the player ran within the last two minutes, as its label only (/kit, never /kit starter).
recentCommandSecondsAgo How long before the snapshot it was run.
itemTags The namespaces of the gained item's persistent data tags: a plugin's custom item nearly always carries its own (myplugin for myplugin:rarity).

inventory.illegal_item.a and inventory.illegal_stack.a findings carry itemTags too, which is how to tell a custom enchant or stacker plugin's item from a hacked one. The clues are evidence only: they never decide whether a finding happens. Once you know the plugin, declare the gain (recordItemTransaction) or authorize the item (authorizeItem) there.

Give your menus their own InventoryHolder class so the finding names your plugin and class rather than "no holder".

Which item gains need declaring#

FlagForge records vanilla item movement itself: every inventory click and drag, items a crafting grid or workstation hands back on close, the ender chest and entity inventories, crafting, trading, anvil, grindstone, smithing, stonecutter, loom and cartography outputs, furnace and brewing output, buckets, bottles, stew bowls, signed books, filled maps, picked-up items and arrows, armor stands, lecterns, flower pots and dispensed armor, and /give. Declare only what your plugin puts into a player's inventory directly - kit, crate, shop and reward plugins calling addItem. An item taken out of a GUI inventory your plugin opened is already counted as a transfer from that inventory.

Undeclared gains right after a player used your plugin are usually covered by the plugin safety net, which puts them down to your plugin. Declaring them is still better: the safety net goes by timing and data tags, so it can miss a gain that arrives late, and server owners can turn it off.

Worked example: a shop-gated build tool ("printer" mode)#

A common pattern: a custom Creative-like mode where players place blocks rapidly through a plugin-controlled tool (charged per block via a shop, no commands allowed). The block-placement rate this produces is exactly what world.fastplace.a/world.nuker.a/world.impossible_action.a exist to catch for an ordinary player — but here it's expected and legitimate, since every placement is already gated by your own shop logic.

Don't work around this by intercepting or cancelling packets before FlagForge sees them - that fights the anti-cheat instead of telling it what's actually going on, and breaks the moment FlagForge's internals change. Do grant a scoped exemption for exactly as long as the player is in that mode:

// When a player enters your build tool:
ExemptionSpec printerMode = new ExemptionSpec(
    ExemptionSpec.ScopeType.CATEGORY, "WORLD",
    "Shop-gated build tool - placement rate is expected here", Duration.ofHours(2));
ExemptionHandle handle = api.exempt(this, player.getUniqueId(), printerMode);
activeExemptions.put(player.getUniqueId(), handle); // track it yourself, keyed by player

// When they leave (or disconnect) - revoke immediately rather than waiting out the duration:
ExemptionHandle handle = activeExemptions.remove(player.getUniqueId());
if (handle != null) {
    api.revoke(handle);
}

CATEGORY/"WORLD" covers every world check at once (placement rate, break rate, reach, etc.) for that one player, only while the exemption is active. If you only need to exempt placement specifically and still want break/reach checks active, scope it narrower instead: ExemptionSpec.ScopeType.CHECK with "world.fastplace.a" (one exempt() call per check ID you need). The duration is a safety net, not the primary mechanism - always revoke() on exit so a disconnect or a bug in your own mode-tracking can't leave a player permanently exempted.

Events#

Beyond the interface, flagforge-api also ships three plain Bukkit events other plugins can listen for instead of polling:

  • FlagForgeFindingEvent — fired for every finding, right after it is durably recorded. Cancellable; cancelling suppresses only the policy action that would follow, never the recorded finding itself.
  • FlagForgeActionEvent — fired immediately before a preventable response (CANCEL, SETBACK, KICK, COMMAND) actually executes against a player. Cancellable; cancelling blocks just that one action.
  • FlagForgeRiskChangeEvent — fired when a player's global risk changes by a meaningful amount, rate-limited per player. Informational only, not cancellable.