Configuration

The configuration file of MCDR is config.yml. It’s located and should be located in the working directory of MCDR

At startup, MCDR will try to load the configuration file. If the configuration file is not present, MCDR will generate a default config file and exit. Otherwise, MCDR will load the config file and compare its content with the default configuration file. If your configuration file has any missing options, MCDR will add default values to the end of your configuration file

The configuration file use YAML format

You can use command !!MCDR reload config or its short form !!MCDR r cfg to reload the config file when MCDR is running

Basic Configuration

Basic configs of MCDR

language

The language that MCDR will use to display information

Option type: str
Default value: en_us
Available options: en_us, zh_cn

Server configuration

Configs for the server that MCDR starts and controls

working_directory

The working directory of the server. You should probably put all the files related to the server int this directory

Option type: str
Default value: server

start_command

The console command to launch the server. It can be a string or a list of string

(shell mode) If it’s a string, the command will be executed as a shell command in a shell environment. It’s the suggested way to use due to its simpleness
start_command: echo Hello world from MCDReforged
(exec mode) If it’s a list of strings, the command will be executed directly using exec. It’s useful when you want the server process directly managed by MCDR (MCDR - server), instead of having a shell process in the middle of the process chain (MCDR - shell - server)
Flatten
start_command: - echo - Hello world from MCDReforged
Inline
start_command: ['echo', 'Hello world from MCDReforged']
Added in version v2.13.0.

handler

Different Minecraft server has different kind of output, and event different kind of command. Server handlers are the modules to handle between all kind of servers and the interface for MCDR to control the server

Handler determines the specific way to parse the standard output text of the server, and uses the correct command for server control

Here is a table of current built-in handlers and their suitable server types

Handler	Compatible server types
vanilla_handler	For Vanilla / Carpet / Fabric server. Use this if your server is vanilla enough
beta18_handler	For Vanilla server in legacy versions, e.g. < 1.7, or even beta1.8. Tested in 1.6.4 and beta1.8.1.
bukkit_handler	For Bukkit / Spigot server with Minecraft version below 1.14, and Paper / Mohistmc server in all version.
bukkit14_handler	For Bukkit / Spigot server with Minecraft version 1.14 and above
forge_handler	For Forge server
cat_server_handler	For CatServer server
arclight_handler	For Arclight server. Tested with arclight-forge-1.20.1-1.0.1.jar
bungeecord_handler	For Bungeecord. Please add `-Djline.terminal=jline.UnsupportedTerminal` before `-jar` in the start command for MCDR support. From here
waterfall_handler	For Waterfall server
velocity_handler	For Velocity server
basic_handler	The handler that parse nothing and return the raw text from the server. Don’t use this unless you want to use MCDR to lanuch non Minecraft related servers.

Option type: str
Default value: vanilla_handler

encoding, decoding

The codec format to encode messages to stdin / decode messages from stdout of the server

Leave it blank for MCDR to use the system encoding. If it doesn’t work (e.g. random characters appear in the console), you need to manually set them to the correct encoding / decoding methods used by the server

For vanilla Minecraft servers, if you are on an operating system that doesn’t using UTF-8 as the default charset, it’s highly suggested to ensure all encoding / decoding use UTF-8 charset, due to the following facts:

Python 3 uses UTF-8 to store strings
Vanilla Minecraft servers always use UTF-8 for reading stdin
Vanilla Minecraft servers use the default charset of the operating system for writing stdout / stderr / log files
The default charset of your operating system might not be UTF-8. For example, Windows may use GBK as the default charset for Chinese users
Non-UTF-8 charset tends to cause annoying codec problems during encoding / decoding, resulting in MCDR being unable to communicate normally with the server

sequenceDiagram participant MCDR participant pipe participant Minecraft MCDR->>pipe: send "hello" (encoding) pipe->>Minecraft: stdin (UTF-8) Minecraft-->>pipe: stdout/stderr (OS charset) pipe-->>MCDR: receive "world" (decoding)

To make everything related to the server use UTF-8, you can follow the steps below:

Ask MCDR to use UTF-8 to communicate with the Minecraft server, i.e. set both encoding and decoding in the MCDR configuration to utf8
```
encoding: utf8
decoding: utf8
```
Make sure the JVM that launches Minecraft also uses UTF-8 as the default charset. To achieve that, you can apply the following JVM properties for the Minecraft process
Java >= 19
-Dfile.encoding=UTF-8 -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8

If you are using a Long-Term-Support Java version (e.g. 8, 11, 17), you can always use this as a universal Java UTF-8 solution no matter what your Java version is. Those unrecognized system properties stdout.encoding and stderr.encoding are harmless

See also: The “Explanation of the above JVM properties” section below
Java 18
-Dfile.encoding=UTF-8 -Dsun.stdout.encoding=UTF-8 -Dsun.stderr.encoding=UTF-8

Notes that -Dsun.stdout.encoding and -Dsun.stderr.encoding are unspecified API. See also: JEP 400
Java <= 17
-Dfile.encoding=UTF-8
To apply the JVM properties, you can:
- (Recommend) Modify the start command for your server. Add the following arguments before the -jar argument
```
start_command: java -Xms1G -Xmx2G -Dfile.encoding=UTF-8 -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8 -jar minecraft_server.jar
#                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ insert these ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
```
- Insert the arguments you need into environment variable JAVA_TOOL_OPTIONS, in case you can’t modify the server start command
```
export JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF-8 -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8"
```

Then, the Minecraft server should run using UTF-8 as the charset for its standard IO streams, and MCDR should be able communicate with the server perfectly

Of course, if you’re sure that your operating system uses UTF-8 as the default character set, then there’s no need for any configuration. You can even leave these 2 options encoding/ decoding blank to use the default system charset

If you server has mixed encoding output, you can provide multiple decoding method by supplying a list of string as the value, In this case, MCDR will try all decoding methods one by one until one succeeds

Example scenario: In Windows, the shell outputs with OS-charset (let’s say GBK), and the server outputs with UTF-8
Example solution: decoding: ['utf8', 'gbk']

encoding

Option type: Optional[str]
Default value: utf8
Examples: utf8, gbk

decoding

Option type: Optional[str] or List[str]
Default value: utf8
Examples: utf8, gbk, ['utf8', 'gbk']

Explanation of the above JVM properties

For Minecraft server, it has 2 common way to print stuffs to stdout / stderr:

(a) Log with log4j

Vanilla Minecraft server uses the log4j library for logging. It configures log4j to use ConsoleAppender for logging messages to stdout, which eventually uses Charset.defaultCharset() to get the default charset

UTF-8 solution for this case: -Dfile.encoding=UTF-8

(b) Print with System.out or System.err

Sometimes Minecraft server might directly print stuffs into stdout / stderr. In this case, we need to ensure both of System.out and System.err use UTF-8 charset as the encoding method

UTF-8 solution for this case:

Java Version

JVM args to ensure UTF-8

<= 1.17

-Dfile.encoding=UTF-8

1.18

-Dsun.stdout.encoding=UTF-8 -Dsun.stderr.encoding=UTF-8 (unspecified API)

>= 1.19

-Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8

See also:

JEP 400: UTF-8 by Default

https://bugs.openjdk.org/browse/JDK-8285492

rcon

The setting for rcon. If rcon is enabled, MCDR will start a rcon client to connect to the server after server rcon has started up. Then plugins can use rcon to query command from the server

rcon.enable

The switch of rcon

Option type: bool
Default value: false

rcon.address

The address of the rcon server

Option type: str
Default value: 127.0.0.1

rcon.port

The port of the rcon server

Option type: int
Default value: 25575

rcon.password

The password to connect to the rcon server

Option type: str
Default value: password

Plugin configuration

MCDR plugin related configs

plugin_directories

The list of directory path where MCDR will search for plugins to load

Option type: List[str]
Default value:

plugin_directories:
  - plugins

Example:

plugin_directories:
  - plugins
  - path/to/my/plugin/directory
  - /another/plugin/directory

catalogue_meta_cache_ttl

The cache TTL of a fetched plugin catalogue meta

MCDR will use the cached meta as the data source for catalogue plugin operations within the TTL

Option type: float
Default value: 1200 (20 min)

catalogue_meta_fetch_timeout

The timeout in seconds for a plugin catalogue meta fetch

Option type: float
Default value: 15

catalogue_meta_url

Override the URL pointing to the “everything.json” or “everything_slim.json” file, which is used to fetch the plugin catalogue meta

If it ends with “.gz” (gzip) or “.xz” (lzma), corresponding decompression operation will be applied

If not provided, the url will be https://api.mcdreforged.com/catalogue/everything_slim.json.xz

Example value (using the original url from raw.githubusercontent.com):

catalogue_meta_url: 'https://raw.githubusercontent.com/MCDReforged/PluginCatalogue/meta/everything_slim.json.xz'

Option type: Optional[str]
Default value: empty

plugin_download_url

Note

A to-be-downloaded plugin file from the plugin catalogue is a valid GitHub release asset

Plugin file download override. Should be a valid python str.format() string

Available variables:

{url}: The original GitHub asset download url
{repos_owner}: The name of the owner of the GitHub repository
{repos_name}: The name of the GitHub repository
{tag}: Name of the git tag associated with the release
{asset_name}: Name of the asset file, i.e. name of the plugin file
{asset_id}: The GitHub asset ID

As an example, to use ghproxy, you can set it to:

plugin_download_url: 'https://mirror.ghproxy.com/{url}'

Another example of a manual concatenation of the GitHub release asset default url. It’s useless, but a good example to demonstrate how this work:

plugin-download_url: 'https://github.com/{repos_owner}/{repos_name}/releases/download/{tag}/{asset_name}'

If not provided, the origin GitHub asset download url will be directly used

Option type: Optional[str]
Default value: empty

plugin_download_timeout

The timeout in seconds for a plugin file download

Option type: float
Default value: 15

plugin_pip_install_extra_args

Extra arguments passed to the pip subprocess for installing required python packages during plugin installation

plugin_pip_install_extra_args: -i https://pypi.tuna.tsinghua.edu.cn/simple --proxy http://localhost:8080

Option type: Optional[str]
Default value: empty

Misc configuration

Miscellaneous configs of MCDR

check_update

If set to true, MCDR will detect if there’s a new version every 24h

Option type: bool
Default value: true

advanced_console

Advance console switch powered by prompt-toolkit

Set it to false if you need to redirect the stdin/stdout of MCDR or just don’t like it

Option type: bool
Default value: true

http_proxy, https_proxy

HTTP(s) proxy setting for all external HTTP requests in MCDR

It’s suggested to set value for http_proxy and https_proxy at the same time

Example values:

http_proxy: 'http://127.0.0.1:1081'
https_proxy: 'http://127.0.0.1:1081'

http_proxy: 'http://user:pass@192.168.0.1:8888'
https_proxy: 'http://user:pass@192.168.0.1:8888'

Option type: Optional[str]
Default value: empty

Advanced configuration

Configuration options for advanced users

disable_console_thread

When set to true, MCDR will not start the console thread for handling console command input

Don’t change it to true unless you know what you are doing

Option type: bool
Default value: false

disable_console_color

When set to true, MCDR will removed all console font formatter codes in before any message gets printed onto the console

Option type: bool
Default value: false

custom_handlers

A list of custom Server Handler classes. The classed need to be subclasses of ServerHandler

Then you can use the name of your handler in the handler option above to use your handler

The name of a handler is defined in the get_name() method

Option type: Optional[List[str]]
Default value:

custom_handlers:

Example:

custom_handlers:
  - handlers.my_handler.MyHandler

In this example the custom handler package path is handlers.my_handler and the class is name MyHandler

custom_info_reactors

A list of custom Info Reactor classes to handle the info instance. The classed need to be subclasses of ServerHandler

All custom info reactors will be registered to the reactor list to process information from the server

Option type: Optional[List[str]]
Default value:

custom_info_reactors:

Example:

custom_info_reactors:
  - my.customize.reactor.MyInfoReactor

In this example the custom reactor package path is my.custom.reactor and the class name is MyInfoReactor

watchdog_threshold

The required time interval in second for Watchdog to consider the task executor thread is not responding. Set it to 0 to disable Watchdog

Option type: int or float
Default value:

watchdog_threshold: 10

handler_detection

By default, MCDR will start a handler detection on MCDR startup for a while, to detect possible configuration mistake of the handler option

Set it to false to disable the handler detection for a few less performance loss after MCDR startup, mostly for profiling MCDR

Option type: bool
Default value:

handler_detection: true

Debug configuration

Configurations for debugging MCDR

debug

Debug logging switches. Set all to true to enable all debug logging, or set the specific option to enable specific debug logging

Default value:

debug:
  all: false
  mcdr: false
  handler: false
  reactor: false
  plugin: false
  permission: false
  command: false