Welcome to the Hangar Open Beta. Please report any issue you encounter on GitHub!
Avatar for OrzMC
Avatar for OrzMC
OrzMC /

OrzMC

A Paper server management plugin with multi-platform bot control via EasyBot.

Download
Paper26.2 and 1 more

Report OrzMC?

OrzMC

Pull Request Build Check codecov Test Count Coverage Dependabot Updates Publish

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 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 to assist with administration, and is published on Hangar and Modrinth.

Features

Feature Description
Permission system (Rank & Review) 4-level player rank chain (guest → member → builder → admin) 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; three blacklist modes (exact IP / CIDR / wildcard); 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 (off by default, whitelist when enabled).
World maintenance One-click world backup or optimization with real-time progress reports; the server list MOTD switches automatically during maintenance.
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 25 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: 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 (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 (EasyBot gateway)

All OrzMC bot features connect through the external EasyBot IM gateway.

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

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

PaperMC provides an update/ directory inside the plugin directory. Put the new plugin JAR there; on the next server restart it is moved into plugins/ automatically, completing the update.

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:
OrzMC feedback group QR code

Contributing

Information

Category
Admin Tools
Published
July 16, 2025
License
GPL
117Downloads
0Stars

Pinned Versions

Pages

GitHub Repo

OrzMCPlugin

Create Issues

Github Issues

Bot Service

EasyBot

Members

2