MC Flarum Bridge

What it is

McFlarumBridge is a bidirectional bridge between a Minecraft server and a Flarum forum. Public forum discussions are relayed into the game, and in-game commands let players link accounts and report others to a moderation board — so moderators work in the forum UI instead of a database.

Two halves

The repository ships a Flarum extension (PHP 8.1+ / Flarum 2.x) and the Minecraft side, sharing one wire protocol.

Minecraft side — two artifacts

Since 0.0.19 a single jar no longer covers everything:

Both are compiled from one platform-neutral core (cn.stalir.mcbridge, Java 17 bytecode). The core deliberately depends on nothing platform-specific — not even Adventure, because Paper ships it and Minecraft 1.21.1 does not. It renders its own Message and each platform converts at delivery time (Paper → Adventure, NeoForge → net.minecraft.network.chat.Component). NeoForge lives in its own Gradle project so ModDevGradle owns the Minecraft dependency and the core never sees it on the compile classpath. Velocity support was removed in 0.0.19.

Features

• Forum → game. New discussions under selected tags are queued and polled, then announced in-game through any combination of chat, action bar, title, and boss bar.
• Account linking. /bind issues a one-time code that the player consumes in the forum; the bound account is shown on the profile page and as a badge next to post authors.
• Player reports. /report <player> <reason> files a discussion under configurable report tags and records it in mc_reports. It can attach the reported player's own recent public chat (default 10 lines; public chat only — never private messages or commands), rendered inside a code fence sized so a player typing backticks cannot break out of it.
• Report progress. /report status lists the player's own reports and their state, scoped to their UUID and server.
• Report outcome. Closing a report — by moving its discussion into a "resolved"/"rejected" tag, or with php flarum mc-bridge:report <id> --status=... — notifies the reporter in game exactly once, through a targeted outbox message.
• Administration. /mcbridge news|outbox|broadcast|stats|reload, plus forum console commands for the secret, settings, reports, and a full-link self test.
• i18n. Forum (locale/) and game (lang/) translations are independent and both default to Simplified Chinese, with key-parity checks.
• Security. Every machine endpoint is authenticated with HMAC-SHA256 over {timestamp}\n{nonce}\n{METHOD}\n{path}\n{body}, with a ±300 s window, single-use nonces, constant-time comparison, and paths measured from /api/mc-bridge so a sub-directory install works unchanged. Player progress queries are scoped so a player can only read their own reports.

Verification

A static checker (tools/verify.mjs, 384 checks), a protocol suite against a mock Flarum (tools/protocol-test.mjs, 46 checks), and an in-JVM self test (SelfTest, 77 checks) run alongside real Gradle builds of both projects; CI runs all three. Releases are tag-driven and publish both jars.

Current state

Version 0.0.21, published on GitHub Releases and Packagist as stalirmc/mc-flarum-bridge. Honestly unverified: the NeoForge mod has never been loaded by a real server, Folia is compile-and-assert only, and the tag-driven report outcome rests on framework source rather than a live forum. Details are in README.md and VERIFICATION.md.