BanchoBot and Commands
Relevant source files
The following files were used as context for generating this wiki page:
The BanchoBot and Commands system provides a robust framework for handling interactive chat-based commands within the Athena osu! server. It allows users to interact with the server through a defined "!" prefix, triggering various functional logic managed by a central registry.
This system is decoupled from the transport layer, ensuring that command logic remains independent of the specific communication protocol (e.g., Bancho binary protocol). It handles parsing, authorization gating, destination validation, and command execution, while the identity of BanchoBot itself is maintained as a system-level entity.
Sources: src/osu_server/services/commands/chat/bancho_bot/command_service.py:1-12, tests/integration/test_chat_e2e.py:220-230
Architecture and Components
The command system follows a modular architecture consisting of a registry for command definitions, a execution service for handling requests, and immutable context objects for passing data to handlers.
System Overview
The following diagram illustrates the high-level flow of a chat message being processed as a potential command.
Key Classes and Data Structures
| Class | Description |
|---|---|
CommandRegistry | A central store that manages CommandDefinition objects, allowing case-insensitive resolution. |
CommandService | The primary execution engine that parses input, validates permissions, and invokes handlers. |
CommandDefinition | An immutable binding between CommandMetadata and an asynchronous handler function. |
CommandContext | A frozen dataclass containing all necessary metadata for a handler (sender, target, args, etc.). |
CommandMetadata | Describes the command properties: name, description, required privileges, and allowed destinations. |
| Sources: src/osu_server/services/commands/chat/bancho_bot/registry.py:20-50, src/osu_server/services/commands/chat/bancho_bot/command_service.py:32-45 |
Command Registration
Commands are registered using a decorator pattern or direct registry calls. The system supports case-insensitive name resolution but stores them in a canonical format to prevent duplicates.
The Registration Decorator
Developers can use the @registry.command decorator to automatically register handlers. This ensures the command is added to the internal mapping and made available for the !help list.
Sources: src/osu_server/services/commands/chat/bancho_bot/registry.py:75-95, tests/unit/services/bancho_bot/test_registry.py:300-320
Execution Logic and Gating
The CommandService performs several validation steps before executing a command handler.
1. Privilege Gating
The system checks if the user possesses the required_privileges defined in the command's metadata. If the user lacks sufficient privileges, the command is treated as unknown to prevent information leakage about administrative tools.
Sources: src/osu_server/services/commands/chat/bancho_bot/command_service.py:53-62
2. Destination Validation
Commands can be restricted to specific chat contexts (Private Message, Channel, or both).
- PM-Only in Channel: Returns an "Unknown command" response to the channel and a private guidance message to the sender.
- Channel-Only in PM: Returns a guidance message directly in the PM.
Sources: src/osu_server/services/commands/chat/bancho_bot/command_service.py:92-112
3. Integrated Help
The service provides a built-in --help flag for all commands. If an argument list starts with --help, the service intercepts the execution and returns the usage/metadata defined in the CommandMetadata instead of running the actual handler.
Sources: src/osu_server/services/commands/chat/bancho_bot/command_service.py:76-90
BanchoBot Identity
BanchoBot is treated as a distinct system entity. Its username is configurable via the bancho_bot_username setting (defaulting to "BanchoBot"). In the transport layer, BanchoBot is assigned a static user ID (often 1) and its presence is bundled into the login roster to ensure clients recognize it as a valid chat participant.
Summary
The BanchoBot and Commands module provides a centralized, extensible way to add server-side interactivity. By separating command registration (CommandRegistry) from execution logic (CommandService), the system achieves high testability and clear authorization boundaries. The use of immutable context and metadata ensures that command handlers are deterministic and cannot inadvertently modify global state outside their defined scope.
Sources: tests/unit/services/bancho_bot/test_registry.py:48-60, src/osu_server/services/commands/chat/bancho_bot/command_service.py:12-25