Getting Started#

Requirements#

  • A server running Paper or Purpur, version 1.21.10.
  • Java 21 (whatever your Paper/Purpur install already requires to run).

FlagForge refuses to enable a single gameplay-observing listener or any enforcement on any other Minecraft version:

  • Older (e.g. Paper 1.21.9): rejected outright by Paper's own api-version gate — FlagForge never even runs.
  • Newer (e.g. Paper 1.21.11): the jar loads, but FlagForge's own internal version guard detects the mismatch and skips registering every listener.

Installing#

  1. Download flagforge-<version>.jar from your account (sign in with Discord; the Stable download is the one for a live server) and copy it into your server's plugins/ directory.
  2. (Optional) To enable movement.timer.a, packet.rate.a, packet.sequence.a and packet.payload.b (see the Check Catalog) and the protection.yml features, including the crash guard (see Configuration § protection.yml), also install PacketEvents 2.12 or newer as its own separate plugin (2.12.2 and 2.14.0 are tested). FlagForge boots fine and simply leaves those checks registered-but-disabled without it.
  3. Start the server. FlagForge creates plugins/FlagForge/config.yml, checks.yml, actions.yml, alerts.yml, messages.yml, storage.yml, and protection.yml with safe, conservative defaults, connects and migrates its SQLite database (plugins/FlagForge/flagforge.db by default), then prints a startup summary to console showing the detected server version/brand, operating mode, enabled/experimental checks, and available capabilities.
  4. Run /ff status (alias of /flagforge status, requires flagforge.command.status, granted to operators by default) to see the same summary in-game, plus live persistence and Discord queue metrics.

Upgrading#

Drop in the new jar and restart. checks.yml/actions.yml/etc. are never overwritten once they exist, so any tuning you've done survives an upgrade; a newly-added config key you want just isn't read from an old file (falls back to its documented default) until you add it yourself.

A check added in the new release has no entry in your old checks.yml. FlagForge fills it in from the built-in checks.yml with its shipped settings, but disabled, and console lists each one on startup ("checks.yml has no entry for ..."). Turn one on with /ff check <id> enable; to keep it on across restarts, copy its entry from the Check Parameter Reference into your checks.yml. The same applies to any check whose entry you delete: it stays off. The SQLite schema is migrated automatically on startup; back up flagforge.db before a major version bump if you want to be able to roll back.

Next steps#