OrzMC
A Paper server management plugin that unifies QQ, Telegram, Discord, Feishu and WeChat bots through the EasyBot gateway.
🌐 English | 简体中文
This plugin is built for PaperMC servers, and runs on Folia as well (declared via
folia-supported: true). Since thePaperAPIis compatible with theBukkitAPIandSpigotAPI, it is also friendly to developers with Bukkit and Spigot plugin development experience.It currently runs on my private server to assist with administration, and is published on Hangar and Modrinth.
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. 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. |
| 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 is YAML-configurable so server owners can tailor the onboarding. |
| 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.
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: trueand runs on both Paper and Folia with the same JAR. A CIfolia-smokejob boots a real Folia server on every PR to catch region-thread regressions that single-threaded unit/integration tests cannot.
Optional dependency: LuckPerms (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
ranktrack and missing groups on startup — no manual LuckPerms setup required.
Bot setup (EasyBot gateway)
All OrzMC bot features connect through the external EasyBot IM gateway.
EasyBot unifies QQ / Telegram / Discord / Feishu / WeChat:
- Deploy the EasyBot gateway service
- Fill in the EasyBot connection address in the plugin's
easybot.yml - Obtain the
api_keyby creating a customer-service API Key in the EasyBot console - Target values such as
admin_groupare 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
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) orbeta(dev-devbuilds).update.auto_download:falseby default — a new version only prints a console notice, and admins run/update nowto download. Set totrueto auto-download intoplugins/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 intoplugins/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 editconfig-versionby hand. See config schema governance for the full rules and boundaries.
Feedback
If you run into any issues, we'd love to hear from you — please open an issue.
You can also join our QQ channel for feedback:
Contributing
- Contribution guide (development notes and iteration conventions)
- Documentation index (reader-role navigation across all docs)
- Plugin architecture
- Config schema governance
- Changelog
Pinned Versions
- B26.2
Pages
GitHub Repo
Create Issues
Bot Service
Members
2
Admin
Admin