§14 API Integration
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.