OrzMC

OrzMC

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

120 downloads 0 followers

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 — or through its own built-in direct channel — and ships a bilingual (English / Chinese) UI out of the box.

🌐 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 (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). 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_<lang>.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, 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.

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

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.

Option A — EasyBot gateway (default)

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

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.<id> 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 → QQ / Feishu / Telegram / Discord.

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 (into config.yml → bot:) 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 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:
OrzMC feedback group QR code

Contributing

No gallery available for this project.

Version Minecraft Loader Download

1.0.30

26.2
folia, paper
Download

1.0.30-dev.431

26.2
folia, paper
Download

1.0.30-dev.430

26.2
folia, paper
Download

1.0.30-dev.429

26.2
folia, paper
Download

1.0.29

26.2
folia, paper
Download

1.0.29-dev.427

26.2
folia, paper
Download

1.0.28

26.2
folia, paper
Download

1.0.28-dev.425

26.2
folia, paper
Download

1.0.28-dev.424

26.2
folia, paper
Download

1.0.27

26.2
folia, paper
Download

1.0.27-dev.422

26.2
folia, paper
Download

1.0.27-dev.421

26.2
folia, paper
Download

1.0.27-dev.420

26.2
folia, paper
Download

1.0.27-dev.419

26.2
folia, paper
Download

1.0.26

26.2
folia, paper
Download

1.0.25

26.2
folia, paper
Download

1.0.25-dev.416

26.2
folia, paper
Download

1.0.25-dev.415

26.2
folia, paper
Download

1.0.25-dev.414

26.2
folia, paper
Download

1.0.25-dev.413

26.2
folia, paper
Download

1.0.25-dev.411

26.2
folia, paper
Download

1.0.24

26.2
folia, paper
Download

1.0.24-dev.409

26.2
folia, paper
Download

1.0.24-dev.408

26.2
folia, paper
Download

1.0.24-dev.407

26.2
folia, paper
Download

1.0.24-dev.406

26.2
folia, paper
Download

1.0.24-dev.398

26.2
folia, paper
Download

1.0.24-dev.396

26.2
folia, paper
Download

1.0.24-dev.397

26.2
folia, paper
Download

1.0.24-dev.395

26.2
folia, paper
Download

1.0.24-dev.394

26.2
folia, paper
Download

1.0.24-dev.393

26.2
folia, paper
Download

1.0.24-dev.392

26.2
folia, paper
Download

1.0.24-dev.391

26.2
folia, paper
Download

1.0.24-dev.390

26.2
folia, paper
Download

1.0.24-dev.389

26.2
folia, paper
Download

1.0.24-dev.388

26.2
folia, paper
Download

1.0.24-dev.387

26.2
folia, paper
Download

1.0.24-dev.386

26.2
folia, paper
Download

1.0.24-dev.385

26.2
folia, paper
Download

1.0.24-dev.384

26.2
folia, paper
Download

1.0.24-dev.383

26.2
folia, paper
Download

1.0.24-dev.382

26.2
folia, paper
Download

1.0.24-dev.381

26.2
folia, paper
Download

1.0.24-dev.380

26.2
folia, paper
Download

1.0.24-dev.379

26.2
folia, paper
Download

1.0.24-dev.378

26.2
folia, paper
Download

1.0.24-dev.377

26.2
folia, paper
Download

1.0.24-dev.376

26.2
folia, paper
Download

1.0.24-dev.375

26.2
folia, paper
Download

1.0.24-dev.374

26.2
folia, paper
Download

1.0.24-dev.373

26.2
folia, paper
Download

1.0.24-dev.372

26.2
folia, paper
Download

1.0.24-dev.371

26.2
folia, paper
Download

1.0.24-dev.368

26.2
folia, paper
Download

1.0.24-dev.370

26.2
folia, paper
Download

1.0.24-dev.369

26.2
folia, paper
Download

1.0.24-dev.367

26.2
folia, paper
Download

1.0.24-dev.366

26.2
folia, paper
Download

1.0.24-dev.365

26.2
folia, paper
Download

1.0.24-dev.364

26.2
folia, paper
Download

1.0.24-dev.363

26.2
folia, paper
Download

1.0.24-dev.362

26.2
folia, paper
Download

1.0.24-dev.361

26.2
folia, paper
Download

1.0.24-dev.360

26.2
folia, paper
Download

1.0.24-dev.359

26.2
folia, paper
Download

1.0.24-dev.358

26.2
folia, paper
Download

1.0.24-dev.357

26.2
folia, paper
Download

1.0.24-dev.356

26.2
folia, paper
Download

1.0.24-dev.355

26.2
folia, paper
Download

1.0.24-dev.354

26.2
folia, paper
Download

1.0.24-dev.353

26.2
folia, paper
Download

1.0.24-dev.352

26.2
folia, paper
Download

1.0.24-dev.351

26.2
folia, paper
Download

1.0.24-dev.350

26.2
folia, paper
Download

1.0.24-dev.349

26.2
folia, paper
Download

1.0.24-dev.348

26.2
folia, paper
Download

1.0.24-dev.347

26.2
folia, paper
Download

1.0.24-dev.346

26.2
folia, paper
Download

1.0.24-dev.345

26.2
folia, paper
Download

1.0.24-dev.344

26.2
folia, paper
Download

1.0.24-dev.343

26.2
folia, paper
Download

1.0.24-dev.342

26.2
folia, paper
Download

1.0.24-dev.341

26.2
folia, paper
Download

1.0.24-dev.340

26.1, 26.2
folia, paper
Download

1.0.24-dev.339

26.1, 26.2
folia, paper
Download

1.0.24-dev.338

26.1, 26.2
folia, paper
Download

1.0.24-dev.337

26.1, 26.2
folia, paper
Download

1.0.23

26.1, 26.2
folia, paper
Download

1.0.23-dev.335

26.1, 26.2
folia, paper
Download

1.0.23-dev.334

26.1, 26.2
folia, paper
Download

1.0.23-dev.333

26.1, 26.2
folia, paper
Download

1.0.22

26.1, 26.2
folia, paper
Download

1.0.22-dev.331

26.1, 26.2
folia, paper
Download

1.0.21-dev.330

26.1, 26.2
folia, paper
Download

1.0.21-dev.329

26.1, 26.2
folia, paper
Download

1.0.21-dev.328

26.1, 26.2
folia, paper
Download

1.0.20

26.1, 26.2
folia, paper
Download

1.0.20-dev.326

26.1, 26.2
folia, paper
Download

1.0.20-dev.325

26.1, 26.2
folia, paper
Download

1.0.19

26.1, 26.2
folia, paper
Download

1.0.19-dev.323

26.1, 26.2
folia, paper
Download

1.0.19-dev.322

26.1, 26.2
folia, paper
Download

1.0.19-dev.321

26.1, 26.2
folia, paper
Download

1.0.19-dev.320

26.1, 26.2
folia, paper
Download

1.0.19-dev.319

26.1, 26.2
folia, paper
Download

1.0.19-dev.318

26.1, 26.2
folia, paper
Download

1.0.19-dev.317

26.1, 26.2
folia, paper
Download

1.0.19-dev.316

26.1, 26.2
folia, paper
Download

1.0.19-dev.315

26.1, 26.2
folia, paper
Download

1.0.19-dev.314

26.1, 26.2
folia, paper
Download

1.0.19-dev.313

26.1, 26.2
folia, paper
Download

1.0.19-dev.312

26.1, 26.2
folia, paper
Download

1.0.19-dev.311

26.1, 26.2
folia, paper
Download

1.0.19-dev.310

26.1, 26.2
folia, paper
Download

1.0.18

26.1, 26.2
folia, paper
Download

1.0.18-dev.308

26.1, 26.2
folia, paper
Download

1.0.18-dev.307

26.1, 26.2
folia, paper
Download

1.0.18-dev.306

26.1, 26.2
folia, paper
Download

1.0.18-dev.305

26.1, 26.2
folia, paper
Download

1.0.18-dev.304

26.1, 26.2
folia, paper
Download

1.0.18-dev.303

26.1, 26.2
folia, paper
Download

1.0.18-dev.302

26.1, 26.2
folia, paper
Download

1.0.18-dev.301

26.1, 26.2
folia, paper
Download

1.0.18-dev.300

26.1, 26.2
folia, paper
Download

1.0.18-dev.299

26.1, 26.2
folia, paper
Download

1.0.18-dev.298

26.1, 26.2
folia, paper
Download

1.0.18-dev.297

26.1, 26.2
folia, paper
Download

1.0.18-dev.296

26.1, 26.2
folia, paper
Download

1.0.18-dev.295

26.1, 26.2
folia, paper
Download

1.0.18-dev.294

26.1, 26.2
paper
Download

1.0.18-dev.293

26.1, 26.2
paper
Download

1.0.18-dev.292

26.1, 26.2
paper
Download

1.0.18-dev.291

26.1, 26.2
paper
Download

1.0.18-dev.289

26.1, 26.2
paper
Download

1.0.18-dev.288

26.1, 26.2
paper
Download

1.0.18-dev.287

26.1, 26.2
paper
Download

1.0.18-dev.286

26.1, 26.2
paper
Download

1.0.18-dev.285

26.1, 26.2
paper
Download

1.0.18-dev.284

26.1, 26.2
paper
Download

1.0.18-dev.283

26.1, 26.2
paper
Download

1.0.18-dev.282

26.1, 26.2
paper
Download

1.0.18-dev.281

26.1, 26.2
paper
Download

1.0.18-dev.280

26.1, 26.2
paper
Download

1.0.18-dev.279

26.1, 26.2
paper
Download

1.0.18-dev.278

26.1, 26.2
paper
Download

1.0.18-dev.277

26.1, 26.2
paper
Download

1.0.18-dev.276

26.1, 26.2
paper
Download

1.0.18-dev.275

26.1, 26.2
paper
Download

1.0.18-dev.274

26.1, 26.2
paper
Download

1.0.18-dev.273

26.1, 26.2
paper
Download

1.0.18-dev.272

26.1, 26.2
paper
Download

1.0.18-dev.271

26.1, 26.2
paper
Download

1.0.18-dev.270

26.1, 26.2
paper
Download

1.0.17

26.1, 26.2
paper
Download

1.0.17-dev.268

26.1, 26.2
paper
Download

1.0.17-dev.267

26.1, 26.2
paper
Download

1.0.17-dev.266

26.1, 26.2
paper
Download

1.0.17-dev.265

26.1, 26.2
paper
Download

1.0.17-dev.264

26.1, 26.2
paper
Download

1.0.17-dev.263

26.1, 26.2
paper
Download

1.0.17-dev.262

26.1, 26.2
paper
Download

1.0.17-dev.261

26.1, 26.2
paper
Download

1.0.17-dev.260

26.1, 26.2
paper
Download

1.0.17-dev.259

26.1, 26.2
paper
Download

1.0.16

26.1, 26.2
paper
Download

1.0.16-dev.257

26.1, 26.2
paper
Download

1.0.16-dev.256

26.1, 26.2
paper
Download

1.0.16-dev.255

26.1, 26.2
paper
Download

1.0.16-dev.254

26.1, 26.2
paper
Download

1.0.16-dev.253

26.1, 26.2
paper
Download

1.0.16-dev.252

26.1, 26.2
paper
Download

1.0.16-dev.251

26.1, 26.2
paper
Download

1.0.16-dev.250

26.1, 26.2
paper
Download

1.0.15

26.1, 26.2
paper
Download

1.0.15-dev.242

26.1, 26.2
paper
Download

1.0.14

26.1, 26.2
paper
Download

1.0.14-dev.240

26.1, 26.2
paper
Download

1.0.14-dev.239

26.1, 26.2
paper
Download

1.0.14-dev.238

26.1, 26.2
paper
Download

1.0.14-dev.237

26.1, 26.2
paper
Download

1.0.14-dev.236

26.1, 26.2
paper
Download

1.0.14-dev.235

26.1, 26.2
paper
Download

1.0.13-dev.234

26.1
paper
Download

1.0.13-dev.233

26.1
paper
Download

1.0.13-dev.232

26.1
paper
Download

1.0.13-dev.231

26.1
paper
Download

1.0.13-dev.230

26.1
paper
Download

1.0.13-dev.229

26.1
paper
Download

1.0.13-dev.228

26.1
paper
Download

1.0.13-dev.227

26.1
paper
Download

1.0.13-dev.226

26.1
paper
Download

1.0.13-dev.225

26.1
paper
Download

1.0.13-dev.224

26.1
paper
Download

1.0.13-dev.223

26.1
paper
Download

1.0.13-dev.222

26.1
paper
Download

1.0.13-dev.221

26.1
paper
Download

1.0.12

26.1
paper
Download

1.0.12-dev.219

26.1
paper
Download

1.0.12-dev.217

26.1
paper
Download

1.0.12-dev.215

26.1
paper
Download

1.0.12-dev.213

26.1
paper
Download

1.0.12-dev.211

26.1
paper
Download

1.0.12-dev.199

26.1
paper
Download

1.0.12-dev.198

26.1
paper
Download

1.0.11

26.1
paper
Download

1.0.11-dev.196

26.1
paper
Download

1.0.11-dev.195

26.1
paper
Download

1.0.11-dev.194

26.1
paper
Download

1.0.11-dev.193

26.1
paper
Download

1.0.11-dev.192

26.1
paper
Download

1.0.10

26.1
paper
Download

1.0.10-dev.190

26.1
paper
Download

1.0.9

26.1
paper
Download

1.0.9-dev.187

26.1
paper
Download

1.0.8

26.1
paper
Download

1.0.8-dev.185

26.1
paper
Download