Milo Discord Bot

Milo is StoneHavenSMP's custom Discord bot, developed by SwornHero to connect Minecraft activity with the StoneHaven community on Discord. It brings conversations, server information, and selected staff tools into one place, helping members stay connected even when they are away from the game.

Milo runs as a separate Python application. Players do not need to install an additional Minecraft mod to use its Discord commands or participate in its text bridge.

What Milo does

Chat between Discord and Minecraft

Milo can bridge text chat in both directions. Minecraft messages are read from the server's log stream and posted to Discord with a Minecraft label and the player's name. Eligible messages in the configured Discord bridge channel are sent into Minecraft with a blue Discord label and the sender's display name.

To participate from Discord, send your message in the designated bridge channel. Milo checks the sender's configured member, moderator, or administrator role. The Discord server owner and users with Discord Administrator permission also have access. Messages from bots are ignored to prevent loops.

Discord formatting is adapted for Minecraft: mentions become readable text, custom emoji become text labels, and attachments or stickers are represented by short indicators. Images are not displayed inside Minecraft chat. Long messages are shortened to 200 characters in the rendered message body.

Forwarded Minecraft chat and event notifications suppress Discord mentions, so player text cannot turn into an everyone ping. If an authorized Discord message fails to reach Minecraft, Milo attempts to add a warning reaction to the original message.

This is a text bridge. For proximity voice communication, see Simple Voice Chat.

Commands for members

These are Discord slash commands. Type them in Discord and select Milo's command entry.

Discord's channel and application-command permissions also affect where commands are available.

Understanding server status

Milo can maintain a pinned status message by editing the same message on each refresh. Members can also request a separate snapshot with /status.

Status information includes server availability, version, player counts, ping, and tracked uptime. TPS and MSPT are available when a compatible performance command is configured and its response can be parsed.

• Ping measures the bot's connection latency to the Minecraft server; it is not your personal in-game ping.
• TPS means ticks per second, a measure of the server's simulation rate.
• MSPT means milliseconds per tick, a measure of how long server ticks take to process.
• Tracked uptime reflects the bot's observations and stored state, rather than an authoritative operating-system process timer.

The online/offline indicator comes from Minecraft's server-list ping. Uptime additionally uses an RCON probe because a hosting proxy may still answer pings while the game process restarts. Two consecutive RCON probe failures reset the stored uptime when server-list ping still reports online; a failed server-list ping resets it immediately. Brief connection issues can therefore affect reporting, and restarts that occur entirely while Milo is offline may be missed.

Event notifications and staff support

Milo's log parser recognizes player joins, departures, deaths, and advancement, challenge, or goal messages and can turn them into Discord embeds. Chat, events, staff alerts, and general console output can be routed to separate configured channels.

Staff-alert forwarding requires another server-side component to emit a log line in the format Milo expects. Milo does not itself install an in-game /staffalert command. Where this integration is configured, Milo can send an alert embed and ping a designated staff role.

For help with a problem, Submit a Ticket(opens in a new tab). Automated notifications do not guarantee an immediate staff response.

Tools for authorized staff

Milo includes Discord commands for server operations. These are permission-controlled tools, not member self-service commands.

Configured administrator access includes moderator and member access; moderator access includes member access. The Discord server owner and users with Discord Administrator permission bypass the configured role checks. These bot tiers describe permissions and do not replace StoneHaven's staff titles or policies.

Whitelist operations support the primary survival target and an optional second RCON target, reporting each target's result separately. This is a specific whitelist feature, not evidence that chat and status are synchronized across multiple servers.

How Milo is built

Milo uses Python with an asynchronous architecture. Discord features are organized into cogs, while services handle Minecraft connections, server status, and log streaming. Database and utility modules keep persistence, parsing, formatting, and permission checks separate from command handlers.

A custom asynchronous RCON client

Milo implements the Minecraft RCON protocol using Python's asynchronous network streams. It reuses a connection, serializes commands with an asynchronous lock, applies timeouts, and reconnects once after a failed command attempt. It also collects fragmented responses and checks outgoing command size before transmission.

This service is shared by chat relaying, staff commands, and status probes. Discord chat is encoded as structured JSON for Minecraft's tellraw command, allowing labels and hover text without manually constructing JSON from message content.

Two ways to receive server logs

Local file mode tails a Minecraft log file when that file is accessible to the bot. The log service supports rotation so monitoring can follow changes to the log file.

Pterodactyl mode receives console output through a panel WebSocket when direct file access is unavailable. It obtains WebSocket credentials through the panel API, refreshes expiring tokens, and reconnects after transient failures using increasing retry delays. Fatal authentication failures stop that log-stream loop and require operator attention and a restart after correction.

The log parser classifies incoming lines before the console cog routes them to Discord. This separates the transport from the meaning of the message.

Persistence and reliability

SQLite stores the status-message ID so Milo can resume editing the existing message after a bot restart. It also stores the observed online-since timestamp, allowing uptime tracking to survive a bot restart when the database is retained. The current schema is small operational state, not a chat-history archive; relayed messages still appear in their destination Discord channels and operational logs may contain message content.

Other safeguards include Minecraft username validation, normalization of moderation reasons, bot-message filtering, and Discord mention controls. Raw RCON includes a short denylist for selected disruptive commands, but it remains a powerful interface intended for trusted staff.

Deployment and maintenance

The repository documents running Milo as a persistent Python process, including a PebbleHost deployment workflow. The application starts with python main.py, using dependencies from requirements.txt and configuration supplied through environment variables or a host-side .env file.

Deployment involves providing the Discord connection, role and channel mappings, Minecraft status target, RCON connection, log source, and a writable SQLite location. Operators choose local-file or panel-WebSocket logging based on whether the bot can access the game server's log file. Persistent database storage preserves the status-message reference and uptime state across process restarts.

The Discord-to-Minecraft bridge requests Message Content intent only when its channel is configured. Slash commands and log mirroring can operate without that intent when the bridge is disabled.

The repository's GitHub Actions workflow runs pytest on Python 3.12 for pushes to main and pull requests. Tests cover areas including formatting, log parsing, permissions, Minecraft input validation, RCON behavior, and uptime tracking. This workflow checks code; it does not automatically deploy Milo.

These are the documented deployment capabilities. The public guide does not assert a particular live host, deployment automation, or active configuration.

Troubleshooting

Include the approximate time and affected feature when reporting a problem. Submit a Ticket(opens in a new tab) if you need assistance.

About the project

Milo is developed and maintained by SwornHero for StoneHavenSMP. It combines community-facing features with hands-on work in asynchronous Python, network protocols, event processing, permissions, and service deployment.

Read Milo's Terms of Service and Privacy Policy for the applicable usage and data-handling information.