中文 | English

Unified Handler

A profile-driven server handler plugin for MCDReforged. One plugin, all server types. No more juggling a dozen handler plugins.

What problem does it solve?

MCDR's plugin handler system has a couple of quirks:

Only one plugin handler can be active at a time. If plugin A adds "command block support" and plugin B adds "chat prefix parsing" — you have to pick one.
Plugin handlers can't elegantly extend the current handler. Want to tweak just one thing on top of ForgeHandler? You'd have to copy the entire thing.

Unified Handler fixes both with a simple Base ⊕ Features architecture.

How it works

Handler = Base (server type, pick one) ⊕ Features (extras, stack as many as you like)

Base tells the plugin what kind of server you're running. Built-in support for Vanilla, Forge, Bukkit, Velocity, Bedrock BDS, plus community forks like Cleanroom and Leaves.
Features are stackable enhancements — you can enable multiple features at once, in any combination. Command block recognition, chat prefix parsing, subserver message routing — pick and choose like building blocks.

Everything is defined in YAML profiles — readable, editable, and upgrade-safe.

Why not hooks / mixins?

Early on, this project considered exposing hooks so other plugins could inject logic during message processing. Ultimately we chose not to go that route:

More efficient. Profiles are compiled once at load time into pre-processed regex structures. There's no runtime dispatching, no jumping between plugins, no dynamic callback lookup. Every log line matches directly against the compiled profile.
Easier to use. Writing YAML has a much lower barrier than writing Python. No coding knowledge, no MCDR API familiarity needed — just write a few regex patterns that match your server's log format. The built-in profiles are living proof: the Cleanroom and Leaves adapters each took less than 20 lines of YAML.
One handler is enough. MCDR only allows one plugin handler at a time. Base ⊕ Features already covers the vast majority of use cases. Instead of making multiple plugins coordinate at runtime, UnifiedHandler consolidates everything into a single, compile-time solution.

Quick Start

Important

Do not use alongside other handler plugins. MCDR's behavior is undefined when multiple plugin handlers are present — there's no guarantee which one takes effect. If you already have other handler plugins installed, remove them first, then configure UnifiedHandler.

📦 Installation

Run in the MCDR console:

!!MCDR plugin install unified_handler

The plugin auto-generates config/unified_handler/config.yml and deploys built-in profiles — no manual reload needed.

Alternatively, drop the .mcdr file into the plugins/ directory and reload MCDR.

⚙️ Configuration

Note

After configuration, run through the Handler Verification Guide to confirm everything is working.

Edit config/unified_handler/config.yml

✅ Case 1: MCDR's built-in handler covers your server

MCDR's built-in handlers (Vanilla / Forge / Bukkit / Velocity, etc.) handle most cases. You just need some extensions (like Team prefix handling):

Keep the handler field in your MCDR config file
Set base_handler to "auto"
Add the features you want

base_handler: "auto"

features:
  - chat_prefixes     # parse team/rank prefixes in player chat
  - commandblock      # stack as many as you like

🔧 Case 2: MCDR's built-in handler can't handle your server

For servers like BDS, Leaves, etc. — use the plugin's built-in profiles:

Set base_handler to the matching profile name
Add features as needed

base_handler: "bedrock_bds"    # see "Built-in Profiles" below

features:
  - commandblock

If the built-in profiles aren't enough, you can always write your own:

base_handler: "my_custom_server"

Other config fields:

command_prefix: "!!uh" # command prefix
admin_permission: 3    # permission level for UnifiedHandler commands
debug: false           # set to true to enable debug output

Built-in Profiles

UnifiedHandler ships with profiles for common server setups. Thanks to the original plugin authors.

Since these haven't been fully tested on a live server, some profiles might have issues. If you find that any features aren't working as advertised during use, please report it in an Issue.

Base

Name	File	For	Credits
`cleanroom`	`base/cleanroom.yml`	Cleanroom MC	`Cmmmmmm`
`leaves`	`base/leaves.yml`	LeavesMC	`Mooling0602`
`lbs_subserver`	`base/lbs_subserver.yml`	Velocity subserver routing	`Ra1ny_Yuki`
`bedrock_bds`	`base/bedrock_bds.yml`	Bedrock Dedicated Server	`Elec glacier`, `jiangyan`

Features

Name	File	Does	Credits
`commandblock`	`features/commandblock.yml`	`[@]` and `[Server]` output can trigger MCDR commands	`Dainsleif`
`chat_prefixes`	`features/chat_prefixes.yml`	Parse `<[Team]Name>` and rank prefix chat formats	`DCS`, `Mooling0602`

Custom Profiles

Need to adapt a custom server? Just write a few lines of YAML. We provide a full JSON Schema for autocompletion and validation.

Check out the Custom Profile Guide.

Contribute Your Profile

If your profile serves a general use case (a server adapter, a common feature enhancement), we welcome PRs. Before submitting:

Place the file under resources/builtin_profiles/base/ or features/
Include name, version, changelog, and description fields
If adapting an existing plugin's handler, credit the original author in the PR

Commands

All !!uh commands require admin permission.

Command	Does
`!!uh`	Show current Base and active Features
`!!uh status`	Same as above
`!!uh reload`	Reload config and profiles
`!!uh debug [on	off]`
`!!uh update`	Update and overwrite outdated builtin profiles

Compatibility

MCDReforged >= 2.13.0
Zero MCDR core modifications

License

FreeBSD License