mudpuppy_core

The mudpuppy_core module offers low-level access to Mudpuppy.

mudpuppy_core: MudpuppyCore

A MudpuppyCore instance for interacting with the client.

It is automatically set up when Mudpuppy is running and has loaded your scripts.

You will typically want to call functions on the mudpuppy_core.mudpuppy_core instance to interact with the client. For example,

from mudpuppy_core import mudpuppy_core
version = mudpuppy_core.version()
print(f"running {version}")

event_handlers: EventHandlers

An EventHandlers instance for registering EventHandler instances with the client.

It is automatically set up when Mudpuppy is running and has loaded your scripts.

You will typically want to use the mudpuppy decorators (e.g. mudpuppy.on_event()) instead of directly interacting with the EventHandlers.

To manually register an EventHandler, you can use EventHandlers.add_handler():

from mudpuppy_core import mudpuppy_core, event_handlers, Event, EventType

async def on_gmcp_enabled(event: Event):
    print(f"GMCP enabled for session {event.id}")
    await mudpuppy_core.gmcp_register(event.id, "Char")

event_handlers.add_handler(EventType.GmcpEnabled, on_gmcp_enabled, __name__)

class MudpuppyCore:

def config(self) -> Config:

Returns a Config instance.

Note that when the configuration changes old Config instances are not automatically updated. You should use a EventType.ConfigReloaded event handler to respond to updates to Config.

@staticmethod

def config_dir() -> str:

Returns the path to the Mudpuppy configuration directory.

This is the place where you should place .py scripts to be automatically loaded, and the default location for the Config file.

@staticmethod

def data_dir() -> str:

Returns the path to the Mudpuppy data directory.

This is the place where Mudpuppy writes its logfile.

@staticmethod

def name() -> str:

Returns the name of the program.

@staticmethod

def version() -> str:

Returns the version of the program.

async def print(self, *args, sep: Optional[str] = None, end: Optional[str] = None):

Outputs each line of the rendered arguments as debug output items in the currently active mudpuppy session (if any).

The arguments and behaviour match that of builtins.print.

For more control over output, use MudpuppyCore.add_output() instead.

async def active_session_id(self) -> Optional[int]:

Returns the ID of the currently active session, or None if no session is active.

async def sessions(self) -> list[SessionInfo]:

Returns a list of SessionInfo instances for all sessions.

async def session_info(self, session_id: int) -> SessionInfo:

Returns a SessionInfo instance for the given session ID.

async def status(self, session_id: int) -> Status:

Returns connection Status information for the given session ID.

async def mud_config(self, session_id: int) -> Optional[Mud]:

Returns the Mud configuration for the given session ID, if it exists.

async def send_line(self, session_id: int, line: str):

Sends a line of text to the given session ID as if it were input sent by the user.

The input will be marked as "scripted" to differentiate it from true user input typed at the keyboard.

Command splitting works the same as for normal user input.

Unlike true user input, aliases are not evaluated for send_line() input. This also means it isn't possible to send slash command input in this manner.

Prefer using MudpuppyCore.send_lines() for sending multiple lines.

Example:

from mudpuppy_core import mudpuppy_core
session_id = ...
mudpuppy_core.send_line(session_id, "hello") # Sends 'hello'
mudpuppy_core.send_line(session_id, "hello;;wave") # Sends 'hello' and then 'wave'

async def send_lines(self, session_id: int, lines: list[str]):

Sends a list of lines of text to the given session ID as if they were input sent by the user.

The input will be marked as "scripted" to differentiate it from true user input typed at the keyboard.

Prefer using MudpuppyCore.send_line() for sending a single line.

async def connect(self, session_id: int):

Connects the given session ID if it isn't already connected.

You can use MudpuppyCore.status() to determine a session's connection Status before calling connect().

A EventType.Connection event will be emitted with the new Status.

async def disconnect(self, session_id: int):

Disconnects the given session ID if it isn't already disconnected.

You can use MudpuppyCore.status() to determine a session's connection Status before calling connect().

A EventType.Connection event will be emitted with the new Status.

async def request_enable_option(self, session_id: int, option: int):

Requests that the MUD server enable a telnet option for the given session ID.

If the option is enabled by the server a EventType.OptionEnabled event will be emitted with the same session ID.

async def request_disable_option(self, session_id: int, option: int):

Requests that the MUD server disable a telnet option for the given session ID.

If the option is disabled by the server a EventType.OptionDisabled event will be emitted with the same session ID.

async def send_subnegotiation(self, session_id: int, option: int, data: bytes):

Sends a telnet subnegotiation to the given session.

The data should be the raw bytes of the subnegotiation payload for the given option code.

async def new_trigger( self, session_id: int, config: TriggerConfig, module: str) -> int:

Creates a new trigger for the given session ID for the given TriggerConfig.

Returns an int trigger ID that can be used with MudpuppyCore.get_trigger(), MudpuppyCore.disable_trigger() and MudpuppyCore.remove_trigger().

The module str is used to associate the trigger with a specific Python module that created it so that if the module is reloaded, the trigger will be deleted first to avoid duplicates when the module re-creates it at load.

async def get_trigger( self, session_id: int, trigger_id: int) -> Optional[Trigger]:

Returns the Trigger for the given trigger ID if it exists for the provided session ID.

See MudpuppyCore.new_trigger() for creating triggers.

async def disable_trigger(self, session_id: int, trigger_id: int):

Disables the trigger with the given trigger ID for the given session ID if it is currently enabled.

The trigger will no longer be evaluated when new input is received, even if it matches the trigger's pattern.

You can use MudpuppyCore.get_trigger() to get a Trigger to determine if it is currently enabled or disabled. Use MudpuppyCore.enable_trigger() to enable the trigger again.

async def enable_trigger(self, session_id: int, trigger_id: int):

Enables the trigger with the given trigger ID for the given session ID if it was previously disabled.

You can use MudpuppyCore.get_trigger() to get a Trigger to determine if it is currently enabled or disabled. Use MudpuppyCore.disable_trigger() to disable the trigger again.

async def remove_trigger(self, session_id: int, trigger_id: int):

Removes the trigger with the given trigger ID for the given session ID if it exists.

The trigger will be deleted and its trigger ID will no longer be valid. You will need to recreate it with MudpuppyCore.new_trigger() if you want to restore the TriggerConfig.

Prefer MudpuppyCore.disable_trigger() if you think you'll want the trigger to be used again in the future.

async def remove_module_triggers(self, session_id: int, module: str):

Removes all triggers created by the given module for the given session ID.

This is useful when a module is reloaded and triggers need to be recreated to avoid duplicates.

async def triggers(self, session_id: int) -> list[Trigger]:

Returns a list of Trigger instances for the given session ID.

async def new_alias( self, session_id: int, config: AliasConfig, module: str) -> int:

Creates a new Alias for the given session ID for the given AliasConfig.

Returns an int alias ID that can be used with MudpuppyCore.get_alias(), MudpuppyCore.disable_alias() and MudpuppyCore.remove_alias().

The module str is used to associate the alias with a specific Python module that created it so that if the module is reloaded, the alias will be deleted first to avoid duplicates when the module re-creates it at load.

async def get_alias(self, session_id: int, alias_id: int) -> Optional[Alias]:

Returns the Alias for the given alias ID if it exists for the provided session ID.

See MudpuppyCore.new_alias() for creating aliases.

async def disable_alias(self, session_id: int, alias_id: int):

Disables the alias with the given alias ID for the given session if it is currently enabled.

The alias will no longer be evaluated when new input is received, even if it matches the alias's pattern.

You can use MudpuppyCore.get_alias() to get a Alias to determine if it is currently enabled or disabled. Use MudpuppyCore.enable_alias() to enable the alias again.

async def enable_alias(self, session_id: int, alias_id: int):

Enables the alias with the given alias ID for the given session ID if it was previously disabled.

You can use MudpuppyCore.get_alias() to get a Alias to determine if it is currently enabled or disabled. Use MudpuppyCore.disable_alias() to disable the alias again.

async def remove_alias(self, session_id: int, alias_id: int):

Removes the alias with the given alias ID for the given session ID if it exists.

The alias will be deleted and its alias ID will no longer be valid. You will need to recreate it with MudpuppyCore.new_alias() if you want to restore the AliasConfig.

Prefer MudpuppyCore.disable_alias() if you think you'll want the alias to be used again in the future.

async def remove_module_aliases(self, session_id: int, module: str):

Removes all aliases created by the given module for the given session ID.

This is useful when a module is reloaded and aliases need to be recreated to avoid duplicates.

async def aliases(self, session_id: int) -> list[Alias]:

Returns a list of Alias instances for the given session ID.

async def new_timer(self, config: TimerConfig, module: str) -> int:

Creates a new Timer configured with the given TimerConfig.

Returns an int timer ID that can be used with MudpuppyCore.get_timer(), MudpuppyCore.stop_timer() and MudpuppyCore.remove_timer().

The module str is used to associate the timer with a specific Python module that created it so that if the module is reloaded, the timer will be deleted first to avoid duplicates when the module re-creates it at load.

async def get_timer(self, timer_id: int) -> Optional[Timer]:

Returns the Timer for the given timer ID if it exists.

See MudpuppyCore.new_timer() for creating timers.

async def stop_timer(self, timer_id: int):

Disables the timer with the given timer ID if it is currently enabled.

The timer will no longer be evaluated when the timer interval elapses.

You can use MudpuppyCore.get_timer() to get a Timer to determine if it is currently enabled or disabled. Use MudpuppyCore.enable_timer() to enable the timer again.

async def start_timer(self, timer_id: int):

Starts a timer with the given timer ID if it was previously stopped.

You can use MudpuppyCore.get_timer() to get a Timer to determine if it is currently enabled or disabled. Use MudpuppyCore.disable_timer() to disable the timer again.

async def remove_timer(self, timer_id: int):

Removes the timer with the given timer ID if it exists.

The timer will be deleted and its timer ID will no longer be valid. You will need to recreate it with MudpuppyCore.new_timer() if you want to restore the TimerConfig.

Prefer MudpuppyCore.disable_timer() if you think you'll want the timer to be used again in the future.

async def remove_module_timers(self, module: str):

Removes all timers created by the given module.

This is useful when a module is reloaded and timers need to be recreated to avoid duplicates.

async def timers(self) -> list[Timer]:

Returns a list of Timer instances.

async def input(self, session_id: int) -> Input:

Returns the Input for the given session ID.

The Input provides access to queued input typed by the user and has functions to query/edit/replace that input.

async def add_output(self, session_id: int, output: OutputItem):

Adds an OutputItem to the main output buffer for the given session ID.

This is the primary mechanism of displaying data to the user.

Use MudpuppyCore.add_outputs() if you have a list[OutputItem] to add.

async def add_outputs(self, session_id: int, outputs: list[OutputItem]):

Adds a list of OutputItem instances to the main output buffer for the given session ID.

USe MudpuppyCore.add_output() if you only have one OutputItem to add.

async def dimensions(self, session_id: int) -> tuple[int, int]:

Returns the width and height of the output area for the given session ID.

Note that this is not the overall width/height of the window, but just the area just to display output from the MUD. These dimensions match the dimensions sent to the MUD using the Telnet NAWS option if supported.

See also MudpuppyCore.gmcp_enabled().

GmcpMessage = <EventType.GmcpMessage: 'gmcpmessage'>

An event emitted when a GMCP message is received.

ResumeSession = <EventType.ResumeSession: 'resumesession'>

An event emitted for each session ID after a PythonReloaded event.

type EventHandler = Callable[[Event], Awaitable[NoneType]]

An async function that handles a mudpuppy_core.Event object as its sole argument.

Example:

async def my_event_handler(event: mudpuppy_core.Event):
    print(f"my_event_handler received event {event}")

class EventHandlers:

A collection of event handlers that will be invoked for specific registered EventTypes.

def add_handler( self, event_type: EventType, handler: EventHandler, module: str):

Adds a new event handler for the given EventType.

The async handler will be invoked when an event of the given type is emitted.

The module string is used to associate the handler with a specific Python module so that when the module is reloaded, the handler can be removed to avoid duplicates.

The handler should have a signature like:

async def handler(event: Event):
    ...

def get_handlers( self, event_type: EventType) -> Optional[list[EventHandler]]:

Returns a list of handlers for the given EventType if any are registered.

def get_handler_events(self) -> list[EventType]:

Returns a list of EventTypes for which handlers are registered.

class Alias:

A AliasConfig associated with a int alias ID after being created with MudpuppyCore.new_alias()

id: int

The Alias's ID.

enabled: bool

Whether the Alias is currently enabled.

Mutate using MudpuppyCore.enable_alias() and MudpuppyCore.disable_alias().

module: str

The module that created the Alias.

Used in association with MudpuppyCore.remove_module_aliases().

config: AliasConfig

The AliasConfig for the Alias.

type AliasCallable = Callable[[int, int, str, list[str]], Awaitable[NoneType]]

An async function that is called when input sent to a MUD matches an alias pattern. Typically you will assign an AliasCallable to the callback property of an AliasConfig. Alternatively, see mudpuppy.alias() for a simple @alias() decorator.

The handler is called with:

the int session ID of the session that received the input
the int alias ID of the Alias that matched.
the str input that matched the alias pattern, and
a list[str] of captured groups from the alias pattern (if any).

Example:

from mudpuppy_core import mudpuppy_core, Alias

async def my_alias_handler(session_id: int, alias_id: int, line: str, _groups: list[str]):
    alias: Alias = await mudpuppy_core.get_alias(session_id, alias_id)
    print(f"alias {alias.config.name} has matched input: {line}")
    print(f"this alias has matched input {alias.config.hits} times so far")

class AliasConfig:

Configuration for an Alias.

You can create a new AliasConfig by specifying a regexp pattern and a name:

alias_config = AliasConfig(r"^hello$", "hello trigger")
alias_config.expansion = "say HELLO!"

AliasConfig( pattern: str, name: str, callback: Optional[AliasCallable] = None, expansion: Optional[str] = None)

Create a new AliasConfig with a pattern and a name.

You can optionally provide a callback and an expansion string.

A friendly name to identify the alias.

callback: Optional[AliasCallable] = None

An optional async AliasCallable to invoke when the alias matches.

hit_count: int

The number of times InputLines have matched this AliasConfig since it was created.

def pattern(self) -> str:

Return a string representation of the AliasConfig regexp pattern.

expansion: Optional[str]

An optional string that will be expanded into an InputLine sent to the MUD whenever the alias matches if it is non-empty.

This value will become the InputLine.sent value sent to the game, and the line that was matched by the alias will be set to the InputLine.original value.

The sent InputLine.scripted property will be set to True.

class Trigger:

A TriggerConfig associated with a int trigger ID after being created with MudpuppyCore.new_trigger()

id: int

The Trigger's ID.

enabled: bool

Whether the Trigger is currently enabled.

Mutate using MudpuppyCore.enable_trigger().

module: bool

The module that created the Trigger.

Used in association with MudpuppyCore.remove_module_triggers().

config: TriggerConfig

The TriggerConfig for the Trigger.

type TriggerCallable = Callable[[int, int, MudLine, list[str]], Awaitable[NoneType]]

An async function that is called when output sent from a MUD matches a trigger pattern. Typically assigned to a TriggerConfig's callback property, alternatively see mudpuppy.trigger() for a simple @trigger() decorator.

The handler is called with:

the int session ID of the session that received the output
the int trigger ID of the mudpuppy_core.Trigger that matched.
the str output that matched the trigger pattern, and
a list[str] of captured groups from the trigger pattern (if any).

Example:

from mudpuppy_core import mudpuppy_core

async def my_trigger_handler(
    session_id: int,
    trigger_id: int,
    line: str,
    _groups: list[str]
):
    trigger: Trigger = await mudpuppy_core.get_trigger(session_id, trigger_id)
    print(f"trigger {trigger.config.name} has matched output: {line}")
    print(f"this trigger has matched output {trigger.config.hits} times so far")

type HighlightCallable = Callable[[MudLine, list[str]], MudLine]

A non-async function that is called when a line of output from the MUD matches a highlight pattern. Typically assigned to a TriggerConfig's highlight property. Alternatively see mudpuppy.highlight() for a simple @highlight() decorator.

The handler is called with:

a MudLine object representing the line of output from the MUD
a list[str] of captured groups from the highlight pattern (if any)

It must return a MudLine to display. This can be the same line object passed in, or a new line object.

Unlike AliasCallable, TriggerCallable, and most other callables mudpuppy_core uses this callable is not async. This is because the handler is expected to mutate the MudLine object in place to apply the desired highlighting. This also means you can not await other mudpuppy_core functions from within a highlight and should prefer using TriggerCallable() handlers for those tasks.

For example, you could use MudLine.set_line() to mutate the provided line to add ANSI colours using cformat:

from cformat import cformat

# Note: **not async**!
def example_highlight_callable(line: MudLine, groups):
    assert len(groups) == 1
    new_line = line.__str__().replace(
        groups[0], cformat(f"<bold><cyan>{groups[0]}<reset>")
    )
    line.set(new_line)
    return line

class TriggerConfig:

Configuration for a Trigger.

You can create a new TriggerConfig by specifying a regexp pattern and a name:

trigger_config = TriggerConfig(r".*Hello.*", "hello trigger")
trigger_config.gag = True

TriggerConfig( pattern: str, name: str, *, strip_ansi: bool = False, prompt: bool = False, gag: bool = False, callback: Optional[TriggerCallable] = None, highlight: Optional[HighlightCallable] = None, expansion: Optional[str] = None)

Create a new TriggerConfig with a pattern and a name.

Optionally you may specify strip_ansi, prompt, gag, callback, highlight, and expansion.

A friendly name to identify the trigger.

strip_ansi: bool

Whether or not ANSI colours should be stripped before the trigger pattern is matched.

Typically you will want this to be True unless you want to write a pattern that matches on specific colours.

prompt: bool

Whether or not the MudLine is required to have MudLine.prompt be equal to True in addition to the pattern matching for the trigger to fire.

Set this to True if you only want the trigger to match lines that generate a EventType.Prompt event.

gag: bool

Whether or not MudLines matched by this trigger should be gagged (e.g. not displayed).

Set this to True to suppress (gag) matched lines.

callback: Optional[TriggerCallable] = None

An optional async TriggerCallable to invoke when the trigger matches.

highlight: Optional[HighlightCallable] = None

An optional synchronous HighlightCallable to invoke when the pattern matches to provide a new MudLine to display.

The MudLine returned by the callback function will replace the matched MudLine allowing you to (for example) add ANSI highlights colours.

expansion: Optional[str] = None

An optional string that will be expanded into an InputLine sent to the MUD whenever the trigger matches if it is non-empty.

The sent MudLine will have MudLine.scripted set to True to differentiate it from human input.

The expansion will be used after both the optional callback and highlight functions have been called.

hit_count: int

The number of times OutputLines have matched this Trigger since it was created.

def pattern(self) -> str:

Return a string representation of the TriggerConfig regexp pattern.

class TimerConfig:

Configuration for a Timer.

You can create a new TimerConfig by specifying a name, a duration_ms, a callback and optionally an int session ID:

timer_config = TimerConfig("Test Timer", 1000, my_timer_callback, None)

TimerConfig( name: str, duration_ms: int, callback: TimerCallable, session: Optional[int] = None)

Create a new TimerConfig with a name that will be run every duration_ms milliseconds, invoking callback. The timer may optionally be associated with an int session ID.

A friendly name to identify the timer.

duration: datetime.timedelta

The duration that the timer should wait before firing.

callback: TimerCallable

An async function that receives an int timer ID and optionally an int session ID when the timer fires.

Your timer callback function should have a signature like:

async def my_timer_callback(timer_id: int, sesh: Optional[int]):
    ...

session_id: Optional[int]

An optional int session ID that the timer is associated with. Can be both read and set.

max_ticks: Optional[int]

An optional maximum number of times the callback should be invoked before the timer is automatically removed. Can be both read and set.

class Timer:

A TimerConfig associated with an int timer ID after being created with MudpuppyCore.new_timer()

id: int

The Timer's ID.

running: bool

Whether the Timer is currently running.

Mutate using MudpuppyCore.start_timer() and MudpuppyCore.stop_timer().

module: str

The module that created the Timer.

Used in association with MudpuppyCore.remove_module_timers().

config: TimerConfig

The TimerConfig for the Timer.

class Shortcut(enum.StrEnum):

A recognized keyboard shortcut.

Quit = <Shortcut.Quit: 'quit'>

A shortcut to quit the client

TabNext = <Shortcut.TabNext: 'tabnext'>

A shortcut to change to the next tab.

TabPrev = <Shortcut.TabPrev: 'tabprev'>

A shortcut to change to the previous tab.

TabClose = <Shortcut.TabClose: 'tabclose'>

A shortcut to close the current tab.

TabSwapLeft = <Shortcut.TabSwapLeft: 'tabswapleft'>

A shortcut to swap the current tab with the tab to the left.

TabSwapRight = <Shortcut.TabSwapRight: 'tabswapright'>

A shortcut to swap the current tab with the tab to the right.

MudListNext = <Shortcut.MudListNext: 'mudlistnext'>

A shortcut to select the next MUD from the MUD list.

MudListPrev = <Shortcut.MudListPrev: 'mudlistprev'>

A shortcut to select the previous MUD from the MUD list.

MudListConnect = <Shortcut.MudListConnect: 'mudlistconnect'>

A shortcut to connect to the selected MUD from the MUD list.

ToggleLineWrap = <Shortcut.ToggleLineWrap: 'togglelinewrap'>

A shortcut to toggle line wrapping in the output area.

ToggleInputEcho = <Shortcut.ToggleInputEcho: 'toggleinputecho'>

A shortcut to toggle whether InputLines are displayed in the output buffer.

HistoryNext = <Shortcut.HistoryNext: 'historynext'>

A shortcut to navigate to the next line in the input history.

HistoryPrevious = <Shortcut.HistoryPrevious: 'historyprevious'>

A shortcut to navigate to the previous line in the input history.

ScrollUp = <Shortcut.ScrollUp: 'scrollup'>

A shortcut to scroll the output buffer up.

ScrollDown = <Shortcut.ScrollDown: 'scrolldown'>

A shortcut to scroll the output buffer down.

ScrollTop = <Shortcut.ScrollTop: 'scrolltop'>

A shortcut to scroll the output buffer to the top.

ScrollBottom = <Shortcut.ScrollBottom: 'scrollbottom'>

A shortcut to scroll the output buffer to the bottom.

class PromptSignal(enum.StrEnum):

Describes a possible way of signalling the a partial line is a prompt and not part of a line waiting for the other part with the line terminator to be received.

EndOfRecord = <PromptSignal.EndOfRecord: 'endofrecord'>

Prompts are signalled by the telnet end of record (EOR) IAC signal.

GoAhead = <PromptSignal.GoAhead: 'goahead'>

Prompts are signalled by the telnet go ahead (GA) IAC signal.

class PromptMode:

The mode the MUD is using for handling prompt lines.

class PromptMode.Unsignalled:

The MUD does not explicitly signal prompt lines.

Instead, after timeout if we find we have received a partial line without a normal \r\n line terminator, we flush the partial line as an assumed unterminated prompt.

If another bit of data is received before the timeout, we reset the timeout process.

timeout: datetime.timedelta

The timeout after which a partial line is assumed to be a prompt.

class PromptMode.Signalled:

The MUD explicitly signals prompt lines using a specified PromptSignal.

signal: PromptSignal

The PromptSignal used to indicate prompt lines.

class Status:

Connection status information.

Typically retrieved using MudpuppyCore.status() with an int session ID.

class Status.Disconnected:

The session is not connected.

class Status.Connecting:

The session is in the process of connecting.

class Status.Connected:

The session is connected and info holds the StreamInfo describing the server the stream is connected to.

info: StreamInfo

The StreamInfo for the connected stream.

This will be a StreamInfo.Tcp or StreamInfo.Tls instance depending on the Mud that was used to create the stream.

class StreamInfo:

Information about a connection stream.

class StreamInfo.Tcp:

A normal Telnet TCP stream without any encryption or authentication.

ip: str

The IP address the stream is connected to, in string format.

This may be an IPv4 or IPv6 address.

port: int

The port the stream is connected to.

class StreamInfo.Tls:

A TLS encrypted stream.

ip: str

The IP address the stream is connected to, in string format.

This may be an IPv4 or IPv6 address.

port: int

The port the stream is connected to.

protocol: str

The TLS protocol version in use, in string format.

ciphersuite: str

The TLS ciphersuite in use, in string format.

verify_skipped: bool

Whether the TLS certificate verification was skipped.

When verify_skipped is True, the stream was configured to ignore any certificate errors (dangerous!).

class OutputItem:

An item to be displayed in the output area of a session.

@staticmethod

def mud(line: MudLine) -> OutputItem:

Construct a Mud OutputItem with the given MudLine.

@staticmethod

def command_result(msg: str) -> OutputItem:

Construct a CommandResult OutputItem with the given msg.

The CommandResult.error will be False. For a failed command result output item, use failed_command_result().

@staticmethod

def failed_command_result(msg: str) -> OutputItem:

Construct a failed CommandResult OutputItem with the given msg.

The CommandResult.error will be True.

@staticmethod

def previous_session(line: MudLine) -> OutputItem:

Construct a PreviousSession OutputItem with the given line.

@staticmethod

def debug(line: str) -> OutputItem:

Construct a Debug OutputItem with the given line.

class OutputItem.Mud:

A line of text from the MUD.

line: MudLine

The MudLine to be displayed.

class OutputItem.Input:

A line of text from the user.

line: InputLine

The InputLine to be displayed.

class OutputItem.Prompt:

A prompt line.

line: MudLine

The prompt MudLine to be displayed.

class OutputItem.HeldPrompt:

A prompt line that has been held at the bottom of the MUD buffer for consistent display as output scrolls.

line: MudLine

The held prompt MudLine to be displayed.

class OutputItem.ConnectionEvent:

A connection event to be displayed in the output buffer.

status: Status

The updated Status of the connection.

class OutputItem.CommandResult:

A command result to be displayed in the output buffer.

message: str

The message produced from running the command.

error: bool

Whether the command succeeded or produced an error.

class OutputItem.PreviousSession:

A message loaded from a previous session log.

line: MudLine

The MudLine from the previous session.

class OutputItem.Debug:

A debug message to be displayed in the output buffer.

line: str

The debug line.

class Output:

A collection of OutputItem instances displayed in an ExtraBuffer.

def len(self) -> int:

Returns the number of OutputItem instances in the collection.

def is_empty(self) -> bool:

Returns True if the collection is empty, False otherwise.

def push(self, item: OutputItem):

Appends an OutputItem to the collection.

The BufferConfig.direction will determine whether items added at the end of the collection are rendered first, or last.

def set(self, items: list[OutputItem]):

Sets the collection of OutputItem instances to items.

Replaces the existing content with the items list.

class Input:

The input area of the client window.

def value(self) -> InputLine:

Returns the current value of the input area.

def cursor(self) -> int:

Returns the current cursor position in the input area.

def visual_cursor(self) -> int:

Returns the visual cursor position in the input area.

def visual_scroll(self, width: int) -> int:

Returns the visual scroll position in the input area.

def telnet_echo(self) -> EchoState:

Returns the current telnet echo state of the input area.

def reset(self):

Resets the input area to its default state.

def pop(self) -> Optional[InputLine]:

Removes and returns the input from the input area.

def set_value(self, value: InputLine):

Sets the value of the input area, adjusting the cursor to the end.

def set_telnet_echo(self, state: EchoState):

Sets the telnet echo state of the input area.

def set_cursor(self, pos: int):

Sets the cursor position in the input area.

def insert(self, c: str):

Inserts a character at the cursor position.

def delete_prev(self):

Deletes the character before the cursor.

def delete_next(self):

Deletes the character after the cursor.

def delete_word_left(self):

Deletes the word to the left of the cursor.

def delete_word_right(self):

Deletes the word to the right of the cursor.

def delete_to_end(self):

Deletes from the cursor to the end of the input.

def cursor_left(self):

Moves the cursor left.

def cursor_right(self):

Moves the cursor right.

def cursor_word_left(self):

Moves the cursor to the left word boundary.

def cursor_word_right(self):

Moves the cursor to the right word boundary.

def cursor_start(self):

Moves the cursor to the start of the input.

def cursor_end(self):

Moves the cursor to the end of the input.

def drop_index(self, index: int):

Drops the character at the given index.

def add_markup(self, index: int, ansi_markup: str):

Adds the provided ansi_markup as a decoration to the input area at the given index.

def remove_markup(self, index: int):

Removes the ansi_markup decoration from the given index.

def clear_markup(self):

Clears all ansi_markup decorations from the input area.

def markup(self) -> dict[int, str]:

Returns a dictionary of ansi_markup decorations in the input area.

def decorated_value(self) -> str:

Returns the input area's value with the ANSI markup interposed at the correct positions.

class EchoState(enum.StrEnum):

The echo state for an InputLine

Enabled = <EchoState.Enabled: 'enabled'>

Echo was enabled and the InputLine was displayed normally.

Password = <EchoState.Password: 'password'>

Telnet echo was disabled because the InputLine was a password.

It should be displayed masked (e.g. *****)

class LayoutNode:

Each layout node describes a section in the layout tree.

LayoutNode(name: str)

Creates a new LayoutNode with the given name.

Name of the section. Can be both read and set.

direction: Direction

Direction the sub-sections are laid out. Can be both read and set.

margin: int

Margin between sub-sections. Can be both read and set.

sections: list[typing.Tuple[Constraint, LayoutNode]]

The list of sub-sections (if any). Can be both read and set.

Each sub-section is described as a Tuple holding a Constraint and a LayoutNode.

def add_section( self, section: LayoutNode, constraint: Constraint):

Adds a LayoutNode as a child section of this node, with size described by the given constraint.

def find_section( self, name: str) -> tuple[Constraint, LayoutNode]:

Returns the Constraint and LayoutNode for the section with the given name.

Raises an exception if name is not a known section name under the LayoutNode.

def all_layouts(self) -> dict[str, LayoutNode]:

Returns a dictionary of all the LayoutNode instances in the layout tree, keyed by their section name.

class Constraint:

A LayoutNode constraint.

percentage: Optional[int] = None

Set when the Constraint is a percentage constraint.

ratio: Optional[tuple[int, int]] = None

Set when the Constraint is a ratio constraint.

length: Optional[int] = None

Set when the Constraint is a length constraint.

max: Optional[int] = None

Set when the Constraint is a max constraint.

min: Optional[int] = None

Set when the Constraint is a min constraint.

@staticmethod

def with_percentage(percentage: int) -> Constraint:

Creates a new Constraint with a percentage constraint.

def set_percentage(self, percentage: int):

Sets the percentage constraint.

@staticmethod

def with_ratio(ratio: tuple[int, int]) -> Constraint:

Creates a new Constraint with a ratio constraint.

def set_ratio(self, ratio: tuple[int, int]):

Sets the ratio constraint.

@staticmethod

def with_length(length: int) -> Constraint:

Creates a new Constraint with a length constraint.

def set_length(self, length: int):

Sets the length constraint.

@staticmethod

def with_max(max: int) -> Constraint:

Creates a new Constraint with a max constraint.

def set_max(self, max: int):

Sets the max constraint.

@staticmethod

def with_min(min: int) -> Constraint:

Creates a new Constraint with a min constraint.

def set_min(self, min: int):

Sets the min constraint.

def set_from(self, other: Constraint):

Sets the values of this Constraint from another Constraint.

class Direction(enum.StrEnum):

A direction to use when creating new layout nodes.

Horizontal = <Direction.Horizontal: 'horizontal'>

Create new sections in the horizontal direction.

Vertical = <Direction.Vertical: 'vertical'>

Create new sections in the vertical direction.

class BufferConfig:

Configuration for an ExtraBuffer.

See MudpuppyCore.new_buffer() for more information.

BufferConfig(layout_name: str)

Create a new BufferConfig with the given layout_name.

layout_name: str

The name of the layout section that the buffer should be displayed in.

See layout.LayoutManager for more information.

line_wrap: bool

Whether the content in the ExtraBuffer should be line-wrapped.

border_top: bool

Whether the top border of the ExtraBuffer should be displayed.

border_bottom: bool

Whether the bottom border of the ExtraBuffer should be displayed.

border_left: bool

Whether the left border of the ExtraBuffer should be displayed.

border_right: bool

Whether the right border of the ExtraBuffer should be displayed.

direction: BufferDirection

The BufferDirection that the content of the ExtraBuffer should be displayed in.

output: Output

The Output collection of OutputItems to be displayed in the ExtraBuffer.

scroll_pos: int

The scroll position of the ExtraBuffer.

max_scroll: int

The maximum scroll_pos of the ExtraBuffer.

class BufferDirection(enum.StrEnum):

Describes what direction an ExtraBuffer should render its contents.

BottomToTop = <BufferDirection.BottomToTop: 'bottomtotop'>

The default direction, and the way the standard MUD output buffer works.

Newer items should be rendered first, at the bottom of the buffer. Older items will be rendered afterwards towards the top of the buffer.

TopToBottom = <BufferDirection.TopToBottom: 'toptobottom'>

Older items should be rendered first, at the top of the buffer. Newer items will be rendered afterwards, towards the bottom of the buffer.

class ExtraBuffer:

A BufferConfig associated with an int buffer ID after being created with MudpuppyCore.new_buffer()

An extra buffer for displaying output. Typically created by and used by scripts.

id: int

The int buffer ID assigned to the buffer.

config: BufferConfig

The BufferConfig of the ExtraBuffer

class Gauge:

A gauge widget that can be created with MudpuppyCore.new_gauge().

id: int

The read-only int ID assigned to the gauge.

layout_name: str

The layout name where the Gauge should be drawn.

Can be both read and set.

value: float

The gauge's current value.

Can be both read and set.

max: float

The gauge's maximum value.

Can be both read and set.

title: str

The title label for the gauge.

def set_colour(self, r: int, g: int, b: int):

Set the colour of the gauge to the RGB values provided.

def set_color(self, r: int, g: int, b: int):

Set the color of the gauge to the RGB values provided.

class Button:

A button widget that can be created with MudpuppyCore.new_button().

id: int

The read-only int ID assigned to the button.

layout_name: str

The layout name where the Button should be drawn.

Can be both read and set.

label: str

The label for the button.

callback: ButtonCallable

type ButtonCallable = Callable[[int, int], Awaitable[NoneType]]

An async function that is called when a button is clicked.

Typically assigned to a Button's callback property.

The callable is called with:

the int session ID of the session that owns the button that was clicked.
the int button ID of the button that was clicked.