# 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-<version>.jar` |
| 1.20.6 | 50.2.10 | 21 | `xfeservermanager-forge-1.20.6-<version>.jar` |
| 1.21.1 | 52.1.16 | 21 | `xfeservermanager-forge-1.21.1-<version>.jar` |
| 1.21.11 | 61.2.1 | 21 | `xfeservermanager-forge-1.21.11-<version>.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.
