Server Handler

Base Class

class mcdreforged.handler.server_handler.ServerHandler(*args, **kwargs)[source]

The interface class for server handler

Class inheriting tree:

ServerHandler (interface)
├── BasicHandler
└── SpecServerHandler
        └── BuiltinSpecServerHandler
                ├── VanillaHandler
                ├── Beta18Handler
                ├── ForgeHandler
                ├── BukkitHandler
                ├── Bukkit14Handler
                ├── CatServerHandler
                ├── ArclightHandler
                ├── BungeecordHandler
                ├── WaterfallHandler
                └── VelocityHandler
abstractmethod get_name() → str[source]

The name of the server handler

The name is used as the identifier of this server handler in MCDR configuration

get_stop_command() → str[source]

The command to stop the server

The default implementation derives the command from get_stop_method()

Deprecated since version v2.17.0: Use get_stop_method() instead

get_stop_method() → StopMethod[source]

The method to stop the server

At least one of this method and get_stop_command() must be implemented, or the handler class cannot be instantiated. The default implementation wraps the result of get_stop_command()

Added in version v2.17.0.

abstractmethod get_send_message_command(target: str, message: str | RTextBase, server_information: ServerInformation) → str | None[source]

The command to send a message to a target

abstractmethod get_broadcast_message_command(message: str | RTextBase, server_information: ServerInformation) → str | None[source]

The command to broadcast a message in the server

abstractmethod pre_parse_server_stdout(text: str) → str[source]

A parsing preprocessor. Invoked before any parsing operation

Remove useless / annoying things like control characters in the text before parsing

Parameters:

text (str) – A line of the server stdout to be parsed

abstractmethod parse_console_command(text: str) → Info[source]

Parse console input

Parameters:

text (str) – A line of console input to be parsed

Returns:

An Info object as the result

abstractmethod parse_server_stdout(text: str) → Info[source]

Main parsing operation. Parse a string from the stdout of the server and output a parsed info

It may raise any exceptions if the format of the input string is not correct

Parameters:

text (str) – A line of the server stdout to be parsed, processed by pre_parse_server_stdout()

Returns:

An Info object as the result

abstractmethod parse_player_joined(info: Info) → str | None[source]

Check if the info indicating a player joined message

If it is, returns the name of the player, otherwise returns None

Parameters:

info (Info) – The info object to be checked

Returns:

The name of the player, or None

abstractmethod parse_player_left(info: Info) → str | None[source]

Check if the info indicates a player left message

If it is, returns the name of the player, otherwise returns None

Parameters:

info (Info) – The info object to be checked

Returns:

The name of the player, or None

abstractmethod parse_server_version(info: Info) → str | None[source]

Check if the info contains a server version message

If it is, returns server version, otherwise returns None

Parameters:

info (Info) – The info object to be checked

Returns:

The version of the server, or None

abstractmethod parse_server_address(info: Info) → Tuple[str, int] | None[source]

Check if the info contains the address which the server is listening on

If it is, returns server ip and port it’s listening on, otherwise returns None

Parameters:

info (Info) – The info object to be checked

Returns:

A tuple containing the ip and the port, or None

abstractmethod test_server_startup_done(info: Info) → bool[source]

Check if the info indicates a server startup message

Parameters:

info (Info) – The info object to be checked

Returns:

If the info indicates a server startup message

abstractmethod test_rcon_started(info: Info) → bool[source]

Check if rcon has started

Parameters:

info (Info) – The info object to be checked

Returns:

If rcon has started

abstractmethod test_server_stopping(info: Info) → bool[source]

Check if the server is stopping

Parameters:

info (Info) – The info object to be checked

Returns:

If the server is stopping

abstractmethod validate_player_name(name: str) → bool[source]

Check if the given player name is valid

Parameters:

name (str) – The name to be validated

Returns:

True if the name is a valid player name, otherwise False

Added in version v2.16.0.

SpecServerHandler

class mcdreforged.handler.impl.SpecServerHandler(spec: HandlerSpec)[source]

A server handler that works according to a HandlerSpec

Parameters:

spec (HandlerSpec) – The handler spec of this handler

Added in version v2.17.0.

property spec: HandlerSpec

The handler spec of this handler

HandlerSpec

class mcdreforged.handler.handler_spec.HandlerSpec(*, name: str, control: Control, parsing: Parsing, events: Events = <factory>)[source]

The declarative definition of a server handler, as an immutable pydantic model

Field

Type

Description

name

str

Required. The name of the handler

control

HandlerSpec.Control

Required

parsing

HandlerSpec.Parsing

Required

events

HandlerSpec.Events

Optional. Default: no event is recognized

All regular expressions use the Python re syntax. Except the sub of TextTransforms.Sub:

  • A regular expression needs to match the whole text

  • For a list of regular expressions, they are tried in order, and the first matched one is used

  • Named groups listed as required must be present. Other groups are ignored

Added in version v2.17.0.

class Control(*, stop: StopMethod, send_message: SendMessageMethod | None = None, broadcast_message: BroadcastMessageMethod | None = None)[source]

Rules for controlling the server

Field

Type

Description

stop

StopMethod

Required. How to stop the server

send_message

SendMessageMethod or null

Optional. How to send a message to a player. Default: null, not supported

broadcast_message

BroadcastMessageMethod or null

Optional. How to broadcast a message to all players. Default: null, not supported

class Parsing(*, pre_parse: ~typing.List[~mcdreforged.handler.handler_spec.TextTransform] = <factory>, line_transforms: ~typing.List[~mcdreforged.handler.handler_spec.TextTransform] = <factory>, line: ~typing.List[~re.Pattern[str]], player_message: ~typing.List[~re.Pattern[str]] = <factory>, player_name: ~re.Pattern[str])[source]

Rules for parsing the server output

Each line of the server output is processed in the following steps:

  1. Apply the pre_parse text transforms. The result is the raw_content of the info

  2. Apply the line_transforms text transforms to the raw content

  3. Match the result against the line rules. If none of the rules matches, the line is unrecognized, its content is the raw content

  4. Match the content against the player_message rules. If matched, the line is a message from a player

Field

Type

Description

pre_parse

List of TextTransform

Optional. Default: []

line_transforms

List of TextTransform

Optional. Default: []

line

List of regular expressions

Required, at least one. The formats of a line. Named group content is required, as the content of the info. Named groups hour, min, sec and logging are optional, as the hour, min, sec and logging_level of the info

player_message

List of regular expressions

Optional. The formats of a player message. Named groups name and message are required, as the player and the content of the info. A rule is skipped if the player name is invalid. Default: [], player messages are not recognized

player_name

Regular expression

Required. The format of a valid player name

class Events(*, player_joined: List[Pattern[str]] = <factory>, player_left: List[Pattern[str]] = <factory>, server_version: List[Pattern[str]] = <factory>, server_address: List[Pattern[str]] = <factory>, server_startup_done: List[Pattern[str]] = <factory>, rcon_started: List[Pattern[str]] = <factory>, server_stopping: List[Pattern[str]] = <factory>)[source]

Rules for recognizing server events

Each field is an optional list of regular expressions, matched against the content of the info. Default: [], the event is not recognized

Events are only recognized from server output that is not a player message. For rules with the name named group, a rule is skipped if the player name is invalid

Field

Required named groups

player_joined

name

player_left

name

server_version

version

server_address

ip, port

server_startup_done

rcon_started

server_stopping

extend(override: Mapping[str, Any]) → HandlerSpec[source]

Create a new spec by merging the given override onto this spec

Merging rules:

  • control, parsing and events are merged key by key. Keys not present in the override are inherited from this spec

  • Other values are replaced as a whole, including lists, stop methods, message methods and text transforms

  • name is not inherited

Parameters:

override (Mapping[str, Any]) – The override, in the same structure as a handler spec

Returns:

The merged handler spec

Raises:

pydantic.ValidationError – If the merged handler spec is invalid

Server handler spec models for declarative handler configuration

class mcdreforged.handler.handler_spec.TextTransforms[source]

The available forms of TextTransform, which modify a line of text

Added in version v2.17.0.

class Builtin(*, builtin: Name)[source]
builtin: strip_ansi_color

Available values of builtin:

  • strip_ansi_color: Remove ANSI console color codes, e.g. \033[31m

  • strip_minecraft_color: Remove Minecraft color codes, e.g. §a

class Sub(*, sub: Pattern[str], repl: str, count: int = 0)[source]

Replace occurrences of a regular expression, like re.sub()

sub: '^>*\r'  # the pattern to search for anywhere in the text
repl: ''       # the replacement
count: 1       # optional, the maximum number of replacements. Default: 0, replace all
class mcdreforged.handler.handler_spec.StopMethods[source]

The available forms of StopMethod, which stop the server

Added in version v2.17.0.

class Command(*, command: str)[source]

Send a command to the standard input of the server

command: stop
class Signal(*, signal: str | int, scope: Scope = Scope.process)[source]

Send a signal to the server process

signal: SIGTERM       # a signal name like "SIGINT", or a signal number like 15
scope: process_tree   # optional, default: process

Available values of scope:

  • process: Only the server process, i.e. the process started by MCDR

  • process_tree: The server process and all of its child processes

On Windows, only SIGTERM is supported, which terminates the process immediately

class mcdreforged.handler.handler_spec.SendMessageMethods[source]

The available forms of SendMessageMethod, which send a message to a target

Added in version v2.17.0.

class Builtin(*, builtin: Name)[source]
builtin: minecraft_tellraw

Available values of builtin:

  • minecraft_tellraw: The tellraw command of Minecraft

class Template(*, template: str, message_format: Format)[source]

A command built from a template

template: 'tell {target} {message}'
message_format: plain

template uses the str.format() syntax. Available placeholders:

  • {target}: The target of the message

  • {message}: The message, formatted according to message_format

Use {{ and }} for literal braces. Placeholders with conversions or format specs, e.g. {message!r}, are not allowed

Available values of message_format:

  • json: A JSON text component

  • plain: Plain text, with Minecraft color codes like §a removed

class mcdreforged.handler.handler_spec.BroadcastMessageMethods[source]

The available forms of BroadcastMessageMethod, which broadcast a message

Added in version v2.17.0.

class Builtin(*, builtin: Name, target: str)[source]
builtin: minecraft_tellraw
target: '@a'

Same as SendMessageMethods.Builtin, with a fixed target

class Template(*, template: str, message_format: Format)[source]

A command built from a template

template: 'say {message}'
message_format: plain

Same as SendMessageMethods.Template, except that only the {message} placeholder is available

mcdreforged.handler.handler_spec.TextTransform

A text transform, in one of the forms in TextTransforms, determined by the key present

Added in version v2.17.0.

mcdreforged.handler.handler_spec.StopMethod

A stop method, in one of the forms in StopMethods, determined by the key present

Added in version v2.17.0.

mcdreforged.handler.handler_spec.SendMessageMethod

A send message method, in one of the forms in SendMessageMethods, determined by the key present

Added in version v2.17.0.

mcdreforged.handler.handler_spec.BroadcastMessageMethod

A broadcast message method, in one of the forms in BroadcastMessageMethods, determined by the key present

Added in version v2.17.0.

Built-in Handlers

class mcdreforged.handler.impl.BasicHandler(*args, **kwargs)[source]

The basic plain handler, providing the minimum parsed information

During server output parsing, it’s used as the fallback handler when every other dedicated handler failed

class mcdreforged.handler.impl.VanillaHandler(*args, **kwargs)[source]

A handler for vanilla Minecraft servers

class mcdreforged.handler.impl.Beta18Handler(*args, **kwargs)[source]

Yes, a handler for Minecraft beta 1.8

class mcdreforged.handler.impl.ForgeHandler(*args, **kwargs)[source]

A handler for Forge Minecraft servers

class mcdreforged.handler.impl.BukkitHandler(*args, **kwargs)[source]

A handler for bukkit and bukkit-like (e.g. Paper) Minecraft servers

class mcdreforged.handler.impl.Bukkit14Handler(*args, **kwargs)[source]

A handler for bukkit and spigot Minecraft servers in 1.14+

class mcdreforged.handler.impl.CatServerHandler(*args, **kwargs)[source]

A handler for CatServer Minecraft servers

class mcdreforged.handler.impl.ArclightHandler(*args, **kwargs)[source]

A handler for Arclight servers

class mcdreforged.handler.impl.BungeecordHandler(*args, **kwargs)[source]

A handler for Bungeecord servers

class mcdreforged.handler.impl.WaterfallHandler(*args, **kwargs)[source]

A handler for Waterfall servers

class mcdreforged.handler.impl.VelocityHandler(*args, **kwargs)[source]

A handler for Velocity servers