Minecraft Tools

RText

API package path: mcdreforged.api.rtext

Advanced text component library for Minecraft

Credit: Pandaria98 ‘s stext API library

Text Styles

class mcdreforged.minecraft.rtext.style.RItem[source]

A general Minecraft text style item

property name: str

Its value in Minecraft text component

class mcdreforged.minecraft.rtext.style.RItemClassic(name: str, mc_code: str, console_code: str)[source]

Bases: RItem, ABC

A type of RItem that can be represented with a classic “§”-prefixed formatting code, or a “\033[31m” styled console ANSI escape code

property mc_code: str

Its code in Minecraft, with “§” prefix

property console_code: str

Its code in console, i.e. ANSI escape code

It might be an empty str if there’s no appropriate code

class mcdreforged.minecraft.rtext.style.RColor(rgb_code: int)[source]

Minecraft text colors

black: RColorClassic = RColorClassic[name=black,mc_code=§0,console_code='\x1b[30m']
dark_blue: RColorClassic = RColorClassic[name=dark_blue,mc_code=§1,console_code='\x1b[34m']
dark_green: RColorClassic = RColorClassic[name=dark_green,mc_code=§2,console_code='\x1b[32m']
dark_aqua: RColorClassic = RColorClassic[name=dark_aqua,mc_code=§3,console_code='\x1b[36m']
dark_red: RColorClassic = RColorClassic[name=dark_red,mc_code=§4,console_code='\x1b[31m']
dark_purple: RColorClassic = RColorClassic[name=dark_purple,mc_code=§5,console_code='\x1b[35m']
gold: RColorClassic = RColorClassic[name=gold,mc_code=§6,console_code='\x1b[33m']
gray: RColorClassic = RColorClassic[name=gray,mc_code=§7,console_code='\x1b[37m\x1b[2m']
dark_gray: RColorClassic = RColorClassic[name=dark_gray,mc_code=§8,console_code='\x1b[37m\x1b[2m']
blue: RColorClassic = RColorClassic[name=blue,mc_code=§9,console_code='\x1b[94m']
green: RColorClassic = RColorClassic[name=green,mc_code=§a,console_code='\x1b[92m']
aqua: RColorClassic = RColorClassic[name=aqua,mc_code=§b,console_code='\x1b[96m']
red: RColorClassic = RColorClassic[name=red,mc_code=§c,console_code='\x1b[91m']
light_purple: RColorClassic = RColorClassic[name=light_purple,mc_code=§d,console_code='\x1b[95m']
yellow: RColorClassic = RColorClassic[name=yellow,mc_code=§e,console_code='\x1b[93m']
white: RColorClassic = RColorClassic[name=white,mc_code=§f,console_code='\x1b[37m']
reset: RColorClassic = RColorClassic[name=reset,mc_code=§r,console_code='\x1b[0m']
classmethod from_mc_value(value: str) RColor[source]

A factory function to create a RColor object from a valid Minecraft color value

Parameters:

value – The value of the color field in Minecraft text component. e.g. "red", "blue", "#00AAFF"

Returns:

A corresponding RColor object

Raises:

ValueError – If the given value is not a valid Minecraft color

property r: int

The red portion of the color in [0, 255]

property g: int

The green portion of the color in [0, 255]

property b: int

The blue portion of the color in [0, 255]

class mcdreforged.minecraft.rtext.style.RColorClassic(name: str, rgb_code: int, mc_code: str, console_code: str)[source]

Bases: RItemClassic, RColor

Classic Minecraft text color defined with color name

Attention

Do not construct the class yourself. Use class fields in RColor if you want to use classic colors

to_rgb() RColorRGB[source]

Converts to the corresponding RColorRGB object with the exact same color

class mcdreforged.minecraft.rtext.style.RColorRGB(rgb_code: int)[source]

Minecraft text color type in hexadecimal color format, with which you can specify the red / green / blue values of the color precisely

Note

Available in Minecraft 1.16+

__init__(rgb_code: int)[source]
Parameters:

rgb_code – An int in hex 0xRRGGBB format, or a str like "RRGGBB", "0xRRGGBB" or "#RRGGBB"

classmethod from_code(rgb_code: str | int) RColorRGB[source]

A factory function to create a RColorRGB object using a single RGB code

Parameters:

rgb_code – An int in hex 0xRRGGBB format, or a str like "RRGGBB", "0xRRGGBB" or "#RRGGBB"

classmethod from_rgb(red: int, green: int, blue: int) RColorRGB[source]

A factory function to create a RColorRGB object using 3 RGB values

Parameters:
  • red – The red portion of the color

  • green – The green portion of the color

  • blue – The blue portion of the color

to_classic() RColorClassic[source]

Converts to the RColorClassic object with the closest Euclidean distance in the RGB color space

class mcdreforged.minecraft.rtext.style.RStyle[source]

Minecraft text styles

bold: RStyleClassic = RStyleClassic[name=bold,mc_code=§l,console_code='\x1b[1m']
italic: RStyleClassic = RStyleClassic[name=italic,mc_code=§o,console_code='']
underlined: RStyleClassic = RStyleClassic[name=underlined,mc_code=§n,console_code='']
strikethrough: RStyleClassic = RStyleClassic[name=strikethrough,mc_code=§m,console_code='']
obfuscated: RStyleClassic = RStyleClassic[name=obfuscated,mc_code=§k,console_code='']
class mcdreforged.minecraft.rtext.style.RStyleClassic(name: str, mc_code: str, console_code: str)[source]

Bases: RItemClassic, RStyle

Classic Minecraft text style with corresponding “§”-prefixed formatting code

class mcdreforged.minecraft.rtext.style.RAction[source]

Minecraft click event actions

suggest_command: RAction = _RActionImpl[name=suggest_command]

Fill the chat bar with given text

run_command: RAction = _RActionImpl[name=run_command]

Run the given text as command

(Minecraft <1.19.1) If the given text doesn’t start with "/", the given text will be considered as a chat message and sent to the server, so it can be used to automatically execute MCDR command after the player click the decorated text

Attention

In vanilla Minecraft >=1.19.1, only strings starting with "/", i.e. command strings, can be used as the text value of run_command action

For other strings that don’t start with "/", the client will reject to send the chat message

See Issue #203

open_url: RAction = _RActionImpl[name=open_url]

Open given url

open_file: RAction = _RActionImpl[name=open_file]

Open file from given path

Note

Actually vanilla Minecraft doesn’t allow texts sent by command contain open_file actions, so don’t be surprised if this open_file doesn’t work

copy_to_clipboard: RAction = _RActionImpl[name=copy_to_clipboard]

Copy given text to clipboard

Note

Available in Minecraft 1.15+

Text Components

class mcdreforged.minecraft.rtext.text.RTextBase[source]

An abstract base class of Minecraft text component

to_json_object() dict | list[source]

Return an object representing its data that can be serialized into a json string

to_json_str() str[source]

Return a json formatted str representing its data

It can be used as the second parameter in Minecraft command /tellraw <target> <message> and more

to_plain_text() str[source]

Return a plain text for console display

Click event and hover event will be ignored

to_colored_text() str[source]

Return a colored text stained with ANSI escape code for console display

Click event and hover event will be ignored

to_legacy_text() str[source]

Return a colored text stained with classic “§”-prefixed Minecraft formatting code

Click event and hover event will be ignored

copy() Self[source]

Return a deep copy version of itself

set_color(color: RColor) Self[source]

Set the color of the text and return the text component itself

set_styles(styles: RStyle | Iterable[RStyle]) Self[source]

Set the styles of the text and return the text component itself

set_click_event(action: RAction, value: str) Self[source]

Set the click event

Method c() is the short form of set_click_event()

Parameters:
  • action – The type of the action

  • value – The string value of the action

Returns:

The text component itself

set_hover_text(*args) Self[source]

Set the hover text

Method h() is the short form of set_hover_text()

Parameters:

args – The elements be used to create a RTextList instance. The RTextList instance is used as the actual hover text

Returns:

The text component itself

c(action: RAction, value: str) Self[source]

The short form of set_click_event()

h(*args) Self[source]

The short form of set_hover_text()

static from_any(text) RTextBase[source]

Convert anything into a RText component

static join(divider: Any, iterable: Iterable[Any]) RTextBase[source]

Just like method str.join(), it concatenates any number of texts with divider

Example:

>>> text = RTextBase.join(',', [RText('1'), '2', 3])
>>> text.to_plain_text()
'1,2,3'
Parameters:
  • divider – The divider between elements. The divider object will be reused

  • iterable – The elements to be joined

static format(fmt: str, *args, **kwargs) RTextBase[source]

Just like method str.format(), it uses *args and **kwargs to build a formatted RText component based on the formatter fmt

Example:

>>> text = RTextBase.format('a={},b={},c={c}', RText('1', color=RColor.blue), '2', c=3)
>>> text.to_plain_text()
'a=1,b=2,c=3'
Parameters:
  • fmt – The formatter string

  • args – The given arguments

  • kwargs – The given keyword arguments

classmethod from_json_object(data: str | list | dict) RTextBase[source]

Convert a json object into a RText component

Example:

>>> text = RTextBase.from_json_object({'text': 'my text', 'color': 'red'})
>>> text.to_plain_text()
'my text'
>>> text.to_json_object()['color']
'red'
Parameters:

data – A json object

New in version v2.4.0.

class mcdreforged.minecraft.rtext.text.RText(text, color: RColor | None = None, styles: RStyle | Iterable[RStyle] | None = None)[source]

Bases: RTextBase

The regular text component class

__init__(text, color: RColor | None = None, styles: RStyle | Iterable[RStyle] | None = None)[source]

Create a RText object with specific text, optional color and optional style

Parameters:
  • text – The content of the text. It will be converted into str

  • color – Optional, the color of the text

  • styles – Optional, the style of the text. It can be a single RStyle or an iterable of RStyle

class mcdreforged.minecraft.rtext.text.RTextList(*args)[source]

Bases: RTextBase

A list of RTextBase objects, a compound text component

__init__(*args)[source]

Use the given *args to create a RTextList

Parameters:

args – The items in this RTextList. They can be str, RTextBase or any class implements __str__ method. All non- RTextBase items will be converted to RText

class mcdreforged.minecraft.rtext.text.RTextTranslation(translation_key: str, color: ~mcdreforged.minecraft.rtext.style.RColor = RColorClassic[name=reset,mc_code=§r,console_code='\x1b[0m'], styles: ~mcdreforged.minecraft.rtext.style.RStyle | ~typing.Iterable[~mcdreforged.minecraft.rtext.style.RStyle] | None = None)[source]

Bases: RText

The translation text component class. It’s almost the same as RText

__init__(translation_key: str, color: ~mcdreforged.minecraft.rtext.style.RColor = RColorClassic[name=reset,mc_code=§r,console_code='\x1b[0m'], styles: ~mcdreforged.minecraft.rtext.style.RStyle | ~typing.Iterable[~mcdreforged.minecraft.rtext.style.RStyle] | None = None)[source]

Create a RTextTranslation object with specific translation key. The rest of the parameters are the same to the constructor of RText

Use method arg() to set the translation arguments, if the translation requires some arguments

Example:

RTextTranslation('advancements.nether.root.title', color=RColor.red)
Parameters:
  • translation_key – The translation key

  • color – Optional, the color of the text

  • styles – Optional, the style of the text. It can be a single RStyle or a collection of RStyle

arg(*args: Any) Self[source]

Set the translation arguments

Parameters:

args – The translation arguments

fallback(fallback: str) Self[source]

Set the translation fallback

Attention

Works in Minecraft >= 1.19.4 only

Parameters:

fallback – The fallback text if the translation is unknown

class mcdreforged.translation.translation_text.RTextMCDRTranslation(translation_key: str, *args, **kwargs)[source]

Bases: RTextBase

The translation text component used in MCDR

When MCDR is running, it will use the tr() method in ServerInterface class as the translating method, and the language of MCDR as the fallback translation language

New in version v2.1.0.

__init__(translation_key: str, *args, **kwargs)[source]

Create a RTextMCDRTranslation component with necessary parameters for translation

Parameters:
  • translation_key – The translation key

  • args – The translation arguments

  • kwargs – The translation keyword arguments

classmethod language_context(language: str)[source]

Create a context where all RTextMCDRTranslation will use the given language to translate within

It’s mostly used when you want a translated str or Minecraft json text object corresponding to this component under a specific language

MCDR will automatically apply this context with user’s preferred language right before sending messages to a player or the console

Example:

def log_message_line_by_line(server: ServerInterface):
    with RTextMCDRTranslation.language_context('en_us'):
        text: RTextMCDRTranslation = server.rtr('my_plugin.some_message')
        text_as_str: str = text.to_plain_text()  # The translation operation happens here
        server.logger.info('Lines of my translation')
        for line in text_as_str.splitlines():
            server.logger.info('- {}'.format(line))
Parameters:

language – The language to be used during translation inside the context

Rcon

API package path: mcdreforged.api.rcon

class mcdreforged.minecraft.rcon.rcon_connection.RconConnection(address: str, port: int, password: str, *, logger: Logger | None = None)[source]

A simply rcon client for connect to any Minecraft servers that supports rcon protocol

__init__(address: str, port: int, password: str, *, logger: Logger | None = None)[source]

Create a rcon client instance

Parameters:
  • address – The address of the rcon server

  • port – The port if the rcon server

  • password – The password of the rcon connection

Keyword Arguments:

logger – Optional, an instance of logging.Logger. It’s used to output some warning information like failing to receive a packet

connect() bool[source]

Start a connection to the rcon server and try to log in

Returns:

If connect and login success

disconnect()[source]

Disconnect from the server

send_command(command: str, max_retry_time: int = 3) str | None[source]

Send a command to the rcon server

Parameters:
  • command – The command you want to send to the server

  • max_retry_time – The maximum retry time of the operation

Returns:

The command execution result form the server, or None if max_retry_time retries exceeded