XFEServerManager

XFEServerManager is a server-side Minecraft Forge administration mod with a browser-based control plane, semantic command policies, live health metrics, audited player operations, and an extensible governance layer. It is currently a development implementation, not a production release.

The project targets four explicit Forge baselines. It does not claim that a single jar works across Minecraft versions.

Repository layout

• common/api — neutral public records and extension SPI.
• common/core — policy, authorization, operations, and audit domain logic.
• common/infra — embedded HTTP, authentication, persistence, and telemetry.
• web-ui — React/TypeScript administration console.
• platform — one isolated Forge build root per supported Minecraft version.
• docs — security, API, deployment, and compatibility documentation.

Build

The repository includes Gradle wrappers; a global Gradle installation is not required. Java 17 builds the common modules and the 1.20.1 adapter. Java 21 is required for the newer adapters.

./gradlew check
cd web-ui && npm ci && npm test && npm run build
./scripts/build-all.sh

On Windows, use gradlew.bat and scripts/build-all.ps1.

The web server binds to 127.0.0.1:8765 by default. Put it behind a trusted HTTPS reverse proxy before exposing it outside the host.

See README.zh-CN.md for Chinese documentation.

First start

1. Install exactly one artifact matching the server's Minecraft and Forge versions. The mod deliberately registers no client-required content or network channel; the vanilla-client handshake still requires acceptance testing for every target version before release. Installing the same version-matched JAR on a client is optional and enables enhanced visual UI menus; clients without it receive the menu's safe clickable-chat fallback.
2. Start the dedicated server and keep the management listener on loopback.
3. From the physical server console, run /xfesm web bootstrap.
4. Use the ten-minute, single-use code to create the first owner, then enroll TOTP before enabling privileged Web features.

Configuration and databases are written under the server's XFEServerManager data directory. Back them up only after a WAL checkpoint or a clean shutdown.

The top of the Web Settings page contains editable feature switches, the default message sender (XFEServerManager unless changed), and the complete startup configuration. Messages without an explicit sender inherit this live setting; individual rich messages may override or hide it. Runtime-safe feature changes apply immediately; listener, proxy, executor/session and OpenMetrics initialization changes remain pending until a graceful restart. The Triggers page is the single source of truth for scheduled announcements, first/per-login welcome messages, once-per-player/day bulletins, rule and maintenance notices, and other event automation. Existing message settings are migrated once into an editable Migrated messages group. Administrators normally compose event, condition and ordered action modules visually; the same model can be authored as bounded XFE Script. Arbitrary command actions remain owner-only. Command policies use multiple independently enabled named groups with visual rule and constraint controls; JSON remains an advanced read-only preview. Saving and applying a validated policy atomically hot-swaps it without restarting the server. The UI menus page provides a positioned canvas, fourteen control types, rich text and trigger variables, searchable uploaded/vanilla/mod images, submenus, and per-control event bindings. Menu documents and sessions remain server-authoritative. The optional client renderer sends only bounded session events back to the server, which revalidates player ownership, expiry, revision, control and event before executing a trigger. The Economy page manages up to 64 exact decimal currencies, searchable icons, primary-currency defaults, balance bounds, account adjustments, atomic player transfers and an immutable ledger. /xfesm-money player commands pass through the same command-policy audit path; economy variables, events and actions are available to triggers and UI menus.

Settings → Crash protection provides hot-reloadable limits for dropped items, mobs, total and third-party-mod entities, spawn bursts, command-block rates, loaded chunks, slow ticks, and heap pressure. Entity limits never reject players, automatic cleanup only removes excess dropped items, and nine protection.* events connect the observations to trigger notifications and responses.

A graceful-stop schedule announces its target as soon as it is created, repeats every five minutes through the final hour, counts down every second through the final minute, and then runs save-all flush, the SQLite checkpoint, and vanilla stop.

OP level 4 or the physical console can use /xfesm tick <0|1..1000> to control the server tick rate. A value of 0 freezes world simulation while retaining player movement and network handling; use /xfesm tick status to inspect the current state.

Documentation

• Architecture
• Triggers and automation
• Crash protection and automation
• Multi-currency economy
• Security model
• Deployment and operations
• Build and release
• Compatibility boundaries
• OpenAPI 3.1 contract
• Implementation and acceptance status

Development status

The repository connects the platform-neutral policy, player, authentication, SQLite, HTTP/SSE and Web-console implementation with v2 moderation, maintenance schedules, chunk claims, Forge event enforcement, world journaling, previewed rollback, pause/resume and redo. All four Forge source sets compile against their matching mapped APIs; runtime acceptance is still required. See the implementation status.

A build is not a production release until each generated JAR passes the dedicated-server start, vanilla-client handshake, clean-stop and database-recovery acceptance checks listed in the compatibility documentation.

Loopback binding, explicit policy publication, owner isolation, least-privilege command reparse and audited mutations are implemented safety defaults. They do not replace the outstanding production acceptance tests.

License

MIT © XFEstudio.