# 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. | Minecraft | Forge | Java | Artifact | | --- | --- | --- | --- | | 1.20.1 | 47.4.0 | 17 | `xfeservermanager-forge-1.20.1-.jar` | | 1.20.6 | 50.2.10 | 21 | `xfeservermanager-forge-1.20.6-.jar` | | 1.21.1 | 52.1.16 | 21 | `xfeservermanager-forge-1.21.1-.jar` | | 1.21.11 | 61.2.1 | 21 | `xfeservermanager-forge-1.21.11-.jar` | ## 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. ```text ./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](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](docs/architecture.md) - [Triggers and automation](docs/triggers.md) - [Crash protection and automation](docs/crash-protection.md) - [Multi-currency economy](docs/economy.md) - [Security model](docs/security.md) - [Deployment and operations](docs/deployment.md) - [Build and release](docs/building.md) - [Compatibility boundaries](docs/compatibility.md) - [OpenAPI 3.1 contract](docs/openapi.yaml) - [Implementation and acceptance status](docs/implementation-status.md) ## 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](docs/implementation-status.md). 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.