OrzMC

# OrzMC [](https://github.com/OrzMC/OrzMCPlugin/actions/workflows/build.yml) [](https://codecov.io/gh/OrzMC/OrzMCPlugin) [](https://github.com/OrzMC/OrzMCPlugin/actions) [](https://github.com/OrzMC/OrzMCPlugin/actions) [](https://github.com/OrzMC/OrzMCPlugin/actions/workflows/dependabot/dependabot-updates) [](https://github.com/OrzMC/OrzMCPlugin/actions/workflows/publish.yml) A Paper server management plugin that unifies QQ, Telegram, Discord, Feishu and WeChat bots through the EasyBot gateway — or through its own built-in direct channel — and ships a bilingual (English / Chinese) UI out of the box. > 🌐 **English** | [简体中文](README.zh-CN.md) > > This plugin is built for [PaperMC](https://papermc.io/) servers, and runs on > [Folia](https://papermc.io/software/folia) as well (declared via > `folia-supported: true`). Since the `PaperAPI` is compatible with the > `BukkitAPI` and `SpigotAPI`, it is also friendly to developers with Bukkit and > Spigot plugin development experience. > > It currently runs on my [private server](https://orzmc.jokerhub.cn) to assist > with administration, and is published on [Hangar](https://hangar.papermc.io/OrzMC/OrzMC) > and [Modrinth](https://modrinth.com/plugin/orzmc). ## Features | Feature | Description | |---------|-------------| | Permission system (Rank & Review) | 4-level player rank chain (default → member → builder → admin, "default" 显示名为 guest/访客) powered by LuckPerms with auto-promotion, apply-and-review workflow (`/apply` / `/review` / `$v`), and manual promotion/demotion (`$p`). Zero setup: auto-creates the track and missing groups on startup; degrades gracefully when LuckPerms is absent. | | Whitelist management | Control server access. Admins add/remove players via bot commands (`$a` / `$r` / `$w`); inactive players are cleaned up automatically; kicked non-whitelisted players receive a helpful notice. | | Multi-platform bot system | Unify QQ, Telegram, Discord, Feishu and WeChat through the EasyBot gateway, or connect to the platform APIs directly with the built-in channel (QQ / Feishu / Telegram / Discord, no extra process) — pick one via `im.yml` → `backend` ([channel comparison](docs/manuals/channel-comparison.md)). 11 bot commands for player management, queries and interaction; console commands (`$e`) return full output to the group — including async plugin output (e.g. Essentials/LuckPerms) captured via a log window, with noise filtering and 30-line truncation; 50+ customizable message templates push server events to the matching group or channel. | | Multi-language (i18n) | Built-in English / Chinese message packs cover in-game feedback, bot replies, event notifications and the `/config` panels; in-game text follows each player's client locale, bot replies are configurable per platform, and server owners can override any message via `messages_custom_.yml`. | | Cross-server portals | Admins create or remove portals; players stepping on a portal are transferred across servers. Optional LoginSecurity verification before transfer. | | TNT protection | Restrict where TNT can be placed, with per-area whitelist exemption; explosion notifications to the group chat; control respawn anchor explosion behavior. Burst explosions are aggregated into a single alert (`×N` with first-event coordinates) so dispenser/explosion spam never floods the group. | | Security controls | Restrict joins by GeoIP country; IP blacklist modes (exact IP / CIDR / wildcard); player-name deny rules (exact / prefix / suffix / contains / glob / regex); optional LoginSecurity secondary verification. | | Teleport bow | Shoot an arrow to teleport to its landing spot with automatic safe-landing detection; chunks along the flight path are force-loaded so long shots always land; configurable entity teleport policy (restricted by default — only whitelisted passive/neutral entities can be teleported by commands/plugins; nether portal traversal is always allowed). | | World maintenance | One-click world backup or optimization with real-time progress reports; the server list MOTD switches automatically during maintenance. | | Plugin self-update | Periodically checks Hangar for a new version (release / beta channel), verifies the sha256 and auto-downloads into `plugins/update/` — a server restart completes the upgrade. Admins can also run `/update check` to query and `/update now` to download manually. | | Player notifications | Push join/quit/kick details (world, coordinates, online count, permission group) to the group chat; the online list shows each player's game mode and rank group. | | Guide book | First-join players automatically receive a guide book. Content uses a minimal YAML format (one line = one sentence, one page = one list, `**bold**` / `[text](url)` markup); edits apply after `/orzmc config reload` ([3-minute guide](docs/guide-book.md), Chinese). | | Runtime configuration | Manage 29 configuration options in-game with `/config`; changes hot-reload without restarting the server. | | OrzMC menu | Open an in-game feature menu with quick access to every operation (in development). | For the full feature list, see [docs/features.md](docs/features.md). ## Installation Download the plugin, drop it into the `plugins/` directory of your PaperMC (or Folia) server, and start the server. The plugin creates a data directory with the same name on first run. During operation, configuration is loaded into memory and written back to the config files when the server stops. > **Folia**: the plugin declares `folia-supported: true` and runs on both > Paper and Folia with the same JAR. A CI `folia-smoke` job boots a real Folia > server on every PR to catch region-thread regressions that single-threaded > unit/integration tests cannot. > **Optional dependency**: [LuckPerms](https://luckperms.net/) (v5.5+) enables > the rank & review permission system. Without it the plugin runs normally but > permission features are disabled. When LuckPerms is present, the plugin > auto-creates the `rank` track and missing groups on startup — no manual > LuckPerms setup required. ## Bot setup OrzMC supports two interchangeable IM channels, selected globally by `backend` in `im.yml`: the external **EasyBot gateway** (default) or the **built-in direct** channel (QQ / Feishu / Telegram / Discord, no extra process). Differences, trade-offs and multi-instance notes: [channel comparison](docs/manuals/channel-comparison.md). ### Option A — EasyBot gateway (default) All OrzMC bot features connect through the external EasyBot IM gateway. [EasyBot](https://github.com/easyIndie/EasyBot) unifies QQ / Telegram / Discord / Feishu / WeChat: 1. Deploy the EasyBot gateway service 2. Fill in the EasyBot connection address in the plugin's `easybot.yml` 3. Obtain the `api_key` by creating a **customer-service API Key** in the EasyBot console 4. Target values such as `admin_group` are not native platform IDs — get the **session key** from the EasyBot console's **Session Management** (e.g. `qq:conv_xxxxxxxx`) > Detailed routing rules: [EasyBot configuration guide](docs/features.md#25-easybot-网关配置指南) ### Option B — Built-in direct channel The plugin talks to the platform APIs itself — no gateway process, text-only, credentials configured in `im.yml`: 1. Set `backend: builtin` and fill in `platforms.` credentials in `im.yml` 2. Restart the server, send a message in the target group / channel, then bind the discovered session with `/config im bind` 3. Verify with `/config im status` and `/config im test` > Step-by-step guides: [built-in common skeleton](docs/manuals/bot-builtin-common.md) → [QQ](docs/manuals/bot-qq.md) / [Feishu](docs/manuals/bot-feishu.md) / [Telegram](docs/manuals/bot-telegram.md) / [Discord](docs/manuals/bot-discord.md). ### Migrating from the old setup The legacy `bot.yml` is no longer loaded. Before upgrading, migrate any values you still need — `cmd_prompt_char`, `discord_server_link`, `qq_group_id` and `log_throttle_ms` — into `easybot.yml`, and finish the per-platform session setup in the EasyBot console. The old NapCatQQ, Discord JDA and Feishu Webhook direct-connection parameters are no longer needed and can be removed. ## Updating ### Built-in auto-update (recommended) The plugin checks Hangar for new versions on startup and every `update.check_interval_hours` (default 12 h), all off the server thread: - **`update.channel`**: `release` (stable, default) or `beta` (dev `-dev` builds). - **`update.auto_download`**: `false` by default — a new version only prints a console notice, and admins run `/update now` to download. Set to `true` to auto-download into `plugins/update/` (sha256-verified before it is staged). - Admins can always run `/update check` (query) and `/update now` (download); after the download finishes, **restart the server** and Paper swaps in the new JAR automatically. > Manual updating still works: drop the new plugin JAR into the `update/` > directory; on the next restart Paper moves it into `plugins/` automatically. > **Configuration files** (`config.yml` / `templates.yml` / `easybot.yml`) are > migrated **automatically on startup**: the previous file is kept as `*.bak`, > missing default keys are merged in (existing values are never overwritten), > and documented old defaults are flipped only when they were left untouched. > No manual delete-and-regenerate is needed. Do not edit `config-version` by > hand. See [config schema governance](docs/dev/config-schema-governance.md) > for the full rules and boundaries. ## Feedback If you run into any issues, we'd love to hear from you — please open an [issue](https://github.com/OrzMC/OrzMCPlugin/issues/new/choose). You can also join our QQ channel for feedback:
 ## Contributing - [Contribution guide](CONTRIBUTING.md) (development notes and iteration conventions) — day-to-day PRs target **`develop`** (the default branch); `main` is the release line (milestones & approved hotfixes only) - [**Documentation index**](docs/README.md) (reader-role navigation across all docs) - [Plugin architecture](docs/architecture.md) - [Config schema governance](docs/dev/config-schema-governance.md) - [Changelog](CHANGELOG.md)