External Bridges Guide¶

This guide covers configuring MAID's external service bridges for Discord, IRC, and RSS/Atom feeds.

Overview¶

MAID can bridge game communication channels to external services, enabling: - Discord Bridge - Bidirectional chat between game and Discord channels - IRC Bridge - Bidirectional chat between game and IRC channels - RSS/Atom Feeds - Server announcements and world events published as feeds

All bridges are optional and disabled by default.

Discord Bridge¶

The Discord bridge connects MAID game channels to Discord server channels using a Discord bot.

Prerequisites¶

A Discord account with a server you can manage
A Discord Application with a Bot
The discord.py library installed

Install the optional Discord dependency:

uv sync --extra discord
# or
pip install discord.py

Creating a Discord Bot¶

Go to the Discord Developer Portal
Click "New Application" and give it a name (e.g., "MAID Bot")
Go to the "Bot" section and click "Add Bot"
Under "Privileged Gateway Intents", enable:
Message Content Intent (required to read messages)
Server Members Intent (optional, for member info)
Click "Reset Token" and copy the bot token

Inviting the Bot to Your Server¶

Go to "OAuth2" > "URL Generator"
Select scopes: bot
Select bot permissions:
Read Messages/View Channels
Send Messages
Embed Links (for rich embeds)
Read Message History
Copy the generated URL and open it in your browser
Select your server and authorize the bot

Configuration¶

# .env file

# Enable Discord bridge
MAID_BRIDGES__DISCORD__ENABLED=true

# Bot token (from Discord Developer Portal)
MAID_BRIDGES__DISCORD__BOT_TOKEN=your-bot-token-here

# Optional: Restrict to a specific guild (server) ID
MAID_BRIDGES__DISCORD__GUILD_ID=123456789012345678

# Command prefix for bot commands
MAID_BRIDGES__DISCORD__COMMAND_PREFIX=!

# Show player join/quit messages
MAID_BRIDGES__DISCORD__SHOW_GAME_JOINS=true
MAID_BRIDGES__DISCORD__SHOW_GAME_QUITS=true

Discord Settings Reference¶

Setting	Type	Default	Description
`enabled`	bool	`false`	Enable the Discord bridge
`bot_token`	str	`""`	Discord bot token (required)
`guild_id`	int	None	Restrict to one server (optional)
`command_prefix`	str	`"!"`	Prefix for bot commands
`show_game_joins`	bool	`true`	Announce player joins in Discord
`show_game_quits`	bool	`true`	Announce player quits in Discord

Required Discord Intents¶

The bot automatically configures the following intents: - message_content - Read message content - guilds - Access guild information

Message Formatting¶

Messages from Discord to game strip Discord-specific formatting: - Custom emojis are removed - User mentions become [user] - Channel mentions become [channel] - Role mentions become [role] - Spoiler tags are removed

Messages from game to Discord escape markdown characters to prevent formatting issues.

Rich Embeds¶

The bridge can send rich embeds for special events:

# Example: Send an announcement as an embed
await bridge.send_embed(
    channel_id="123456789",
    title="Server Event",
    description="A dragon has appeared in the Northern Mountains!",
    color=0xFF0000,  # Red
    fields=[
        ("Location", "Northern Mountains", True),
        ("Difficulty", "Epic", True),
    ],
)

IRC Bridge¶

The IRC bridge connects MAID game channels to IRC server channels.

Prerequisites¶

The IRC bridge uses a built-in asyncio implementation and has no external dependencies.

Configuration¶

# .env file

# Enable IRC bridge
MAID_BRIDGES__IRC__ENABLED=true

# IRC server settings
MAID_BRIDGES__IRC__SERVER=irc.example.com
MAID_BRIDGES__IRC__PORT=6667
MAID_BRIDGES__IRC__SSL=false

# Bot identity
MAID_BRIDGES__IRC__NICKNAME=MAIDBot
MAID_BRIDGES__IRC__PASSWORD=optional-server-password

# Channels to join (JSON array format)
MAID_BRIDGES__IRC__CHANNELS=["#maid-game","#maid-ooc"]

# Reconnection delay in seconds
MAID_BRIDGES__IRC__RECONNECT_DELAY=30

IRC Settings Reference¶

Setting	Type	Default	Description
`enabled`	bool	`false`	Enable the IRC bridge
`server`	str	`""`	IRC server hostname (required)
`port`	int	`6667`	IRC server port
`ssl`	bool	`false`	Use SSL/TLS connection
`nickname`	str	`"MAIDBot"`	Bot nickname
`password`	str	None	Server password (optional)
`channels`	list	`[]`	Channels to join
`reconnect_delay`	int	`30`	Seconds between reconnect attempts

SSL/TLS for IRC¶

For secure IRC connections:

MAID_BRIDGES__IRC__SSL=true
MAID_BRIDGES__IRC__PORT=6697  # Standard SSL port

Message Splitting¶

IRC has a message length limit (~400 characters). Long messages are automatically split:

Long message part 1...
Long message part 2...

Formatted Messages¶

Since IRC doesn't support rich embeds, formatted messages use IRC formatting codes:

[Server Event] | Dragon has appeared in the Northern Mountains! | Location: Northern Mountains | Difficulty: Epic

Bold text uses the IRC bold control character (\x02).

RSS/Atom Feeds¶

MAID can publish server announcements and world events as RSS 2.0 and Atom 1.0 feeds.

Configuration¶

# .env file

# Enable RSS feeds
MAID_BRIDGES__RSS__ENABLED=true

# Feed metadata
MAID_BRIDGES__RSS__TITLE=MAID Server News
MAID_BRIDGES__RSS__DESCRIPTION=News and updates from our MAID game server
MAID_BRIDGES__RSS__LINK=https://yourgame.example.com

# Feed settings
MAID_BRIDGES__RSS__MAX_ITEMS=50
MAID_BRIDGES__RSS__INCLUDE_ANNOUNCEMENTS=true
MAID_BRIDGES__RSS__INCLUDE_WORLD_EVENTS=true

RSS Settings Reference¶

Setting	Type	Default	Description
`enabled`	bool	`false`	Enable RSS/Atom feeds
`title`	str	`"MAID Server News"`	Feed title
`description`	str	`"News and updates..."`	Feed description
`link`	str	`"http://localhost:8080"`	Base URL for the server
`max_items`	int	`50`	Maximum items in feed
`include_announcements`	bool	`true`	Include server announcements
`include_world_events`	bool	`true`	Include world events

Feed Endpoints¶

When enabled, the following endpoints are available:

Endpoint	Format	Content-Type
`/feeds/rss.xml`	RSS 2.0	`application/rss+xml`
`/feeds/atom.xml`	Atom 1.0	`application/atom+xml`

Caching¶

The feeds support HTTP caching headers:

ETag - Content hash for conditional requests
Last-Modified - Timestamp of last update
Cache-Control - TTL based on feed configuration

Clients can use If-None-Match or If-Modified-Since headers for efficient polling.

Feed Item Categories¶

Items are categorized for filtering: - announcement - Server announcements - world_event - In-game world events

Example Feed Subscription¶

Subscribe with any RSS reader: - RSS URL: https://yourgame.example.com/feeds/rss.xml - Atom URL: https://yourgame.example.com/feeds/atom.xml

Channel Mappings¶

Channel mappings connect game channels to external service channels.

Configuration¶

Channel mappings are configured as a JSON array:

# In your .env file (as JSON string)
MAID_BRIDGES__CHANNEL_MAPPINGS='[{"external_channel_id":"123456789","external_channel_name":"#game-chat","game_channel":"ooc","service":"discord","bidirectional":true,"format_template":"[{service}] {username}: {message}"}]'

Or in Python configuration:

from maid_engine.config.settings import Settings, BridgeSettings

settings = Settings(
    bridges=BridgeSettings(
        channel_mappings=[
            {
                "external_channel_id": "123456789012345678",
                "external_channel_name": "#game-chat",
                "game_channel": "ooc",
                "service": "discord",
                "bidirectional": True,
                "format_template": "[{service}] {username}: {message}",
            },
            {
                "external_channel_id": "#maid-chat",
                "external_channel_name": "#maid-chat",
                "game_channel": "chat",
                "service": "irc",
                "bidirectional": True,
                "format_template": "[IRC] {username}: {message}",
            },
        ],
    ),
)

Mapping Fields¶

Field	Type	Required	Description
`external_channel_id`	str	Yes	Channel ID (Discord snowflake) or name (IRC)
`external_channel_name`	str	Yes	Human-readable channel name
`game_channel`	str	Yes	Game channel name (e.g., "ooc", "chat")
`service`	str	Yes	Service name: "discord" or "irc"
`bidirectional`	bool	No	Enable both directions (default: true)
`format_template`	str	No	Message format template

Format Template Variables¶

Variable	Description
`{service}`	Service name (discord, irc)
`{username}`	Sender's username
`{message}`	Message content

Direction Control¶

bidirectional: true - Messages flow both ways
bidirectional: false - Game to external only (announcements, broadcasts)

Bridge Manager¶

The BridgeManager handles all bridge lifecycle and message routing.

Integration with Game Engine¶

The bridge manager integrates automatically when bridges are configured:

# In your game initialization
from maid_engine.core.engine import GameEngine
from maid_engine.config.settings import Settings

settings = Settings()  # Loads from environment
engine = GameEngine(settings)

# Bridges start with the engine
await engine.start()

# Relay a message to external services
await engine.bridge_manager.relay_to_external(
    game_channel="ooc",
    sender_name="Player1",
    message="Hello from the game!"
)

# Bridges stop with the engine
await engine.stop()

Bridge States¶

Each bridge tracks its connection state:

State	Description
`DISCONNECTED`	Not connected
`CONNECTING`	Connection in progress
`CONNECTED`	Active and ready
`RECONNECTING`	Reconnecting after disconnect
`ERROR`	Connection failed

Programmatic Usage¶

Sending Messages¶

from maid_engine.bridges import BridgeManager

# Get the bridge manager from the engine
bridge_manager = engine.bridge_manager

# Send to a specific service channel
discord_bridge = bridge_manager.get_bridge("discord")
if discord_bridge and discord_bridge.state == BridgeState.CONNECTED:
    await discord_bridge.send_message(
        channel_id="123456789",
        content="Hello Discord!",
        sender_name="Server",
    )

Sending Rich Embeds¶

# Send a rich embed (Discord) or formatted text (IRC)
await discord_bridge.send_embed(
    channel_id="123456789",
    title="World Event",
    description="A rare creature has appeared!",
    color=0x00FF00,  # Green
    fields=[
        ("Location", "Forest of Shadows", True),
        ("Reward", "500 gold", True),
    ],
)

Adding RSS Items¶

from maid_engine.bridges.rss_feed import RSSFeedManager

# Get or create feed manager
feed_manager = engine.rss_feed_manager

# Add an announcement
feed_manager.add_announcement(
    title="Server Maintenance",
    description="The server will restart at midnight for updates.",
    author="Admin",
)

# Add a world event
feed_manager.add_world_event(
    title="Dragon Defeated",
    description="The dragon Infernus has been slain by brave adventurers!",
)

Troubleshooting¶

Discord Bot Not Connecting¶

Symptoms: Bot shows as offline, no messages relayed

Solutions: 1. Verify the bot token is correct 2. Check that the bot was invited to the server 3. Ensure Message Content Intent is enabled in Discord Developer Portal 4. Check server logs for connection errors

IRC Connection Refused¶

Symptoms: Cannot connect to IRC server

Solutions: 1. Verify server hostname and port 2. Check if SSL is required (MAID_BRIDGES__IRC__SSL=true) 3. Verify no firewall blocking the connection 4. Check if server requires a password

Messages Not Relaying¶

Symptoms: Messages sent but not appearing

Solutions: 1. Verify channel mappings are configured correctly 2. Check that bidirectional is set correctly 3. Ensure the channel IDs match (Discord IDs are numbers) 4. Check server logs for relay errors

RSS Feed Not Updating¶

Symptoms: Feed shows old items, new items not appearing

Solutions: 1. Verify RSS is enabled: MAID_BRIDGES__RSS__ENABLED=true 2. Check the feed endpoint is accessible: /feeds/rss.xml 3. Clear your RSS reader's cache 4. Verify items are being added (check server logs)

Character Encoding Issues¶

Symptoms: Special characters appear garbled

Solutions: 1. Ensure IRC server supports UTF-8 2. Check Discord message content is properly escaped 3. Verify feed XML encoding is UTF-8

Best Practices¶

Use separate channels for different purposes - Keep OOC chat, announcements, and game events separate
Configure bidirectional carefully - One-way for announcements, two-way for chat
Monitor bridge states - Set up logging to catch disconnections
Use format templates - Clearly identify message sources
Restrict Discord guild - Use guild_id to prevent cross-server issues
Set appropriate reconnect delays - Avoid flooding servers with reconnect attempts
Use SSL for IRC when available - Secure your connections
Keep RSS feeds focused - Don't spam subscribers with too many events

SSL Configuration Guide - Secure connections
REST API Documentation - API integration
Admin API Reference - Administrative endpoints

External Bridges Guide¶

Overview¶

Discord Bridge¶

Prerequisites¶

Creating a Discord Bot¶

Inviting the Bot to Your Server¶

Configuration¶

Discord Settings Reference¶

Required Discord Intents¶

Message Formatting¶

Rich Embeds¶

IRC Bridge¶

Prerequisites¶

Configuration¶

IRC Settings Reference¶

SSL/TLS for IRC¶

Message Splitting¶

Formatted Messages¶

RSS/Atom Feeds¶

Configuration¶

RSS Settings Reference¶

Feed Endpoints¶

Caching¶

Feed Item Categories¶

Example Feed Subscription¶

Channel Mappings¶

Configuration¶

Mapping Fields¶

Format Template Variables¶

Direction Control¶

Bridge Manager¶

Integration with Game Engine¶

Bridge States¶

Programmatic Usage¶

Sending Messages¶

Sending Rich Embeds¶

Adding RSS Items¶

Troubleshooting¶

Discord Bot Not Connecting¶

IRC Connection Refused¶

Messages Not Relaying¶

RSS Feed Not Updating¶

Character Encoding Issues¶

Best Practices¶

Related Documentation¶