MosswartOverlord/discord-rare-monitor

Discord Rare Monitor Bot

A Discord bot that monitors the Dereth Tracker WebSocket stream for rare discoveries and posts filtered notifications to Discord channels.

Features

• Real-time Monitoring: Connects to Dereth Tracker WebSocket for instant rare notifications
• Smart Classification: Automatically classifies rares as "common" or "great" based on keywords
• Rich Embeds: Posts formatted Discord embeds with location and timestamp information
• Dual Channels: Posts to separate channels for common and great rares
• Robust Connection: Automatic reconnection with exponential backoff on connection failures

Rare Classification

Common Rares

Items containing these keywords (except "Frore Crystal"):

• Crystal
• Jewel
• Pearl
• Elixir
• Kit

Great Rares

All other rare discoveries not classified as common.

Configuration

The bot is configured via environment variables:

Variable	Default	Description
DISCORD_RARE_BOT_TOKEN	Required	Discord bot token
DERETH_TRACKER_WS_URL	ws://dereth-tracker:8765/ws/position	WebSocket URL
COMMON_RARE_CHANNEL_ID	1355328792184226014	Discord channel for common rares
GREAT_RARE_CHANNEL_ID	1353676584334131211	Discord channel for great rares
LOG_LEVEL	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)

Docker Usage

The bot is designed to run as a Docker container alongside the Dereth Tracker services:

# Build and start all services including the Discord bot
docker-compose up -d

# View bot logs
docker-compose logs discord-rare-monitor

# Restart just the bot
docker-compose restart discord-rare-monitor

Manual Setup

1. Create a Discord application and bot at https://discord.com/developers/applications
2. Get the bot token and invite the bot to your Discord server
3. Set the DISCORD_RARE_BOT_TOKEN environment variable
4. Ensure the bot has permissions to send messages in the target channels

Message Format

The bot listens for WebSocket messages with this structure:

{
  "type": "rare",
  "character_name": "PlayerName",
  "name": "Dark Heart",
  "timestamp": "2025-06-22T16:00:00Z",
  "ew": 12.34,
  "ns": -56.78,
  "z": 10.5
}

Architecture

• WebSocket Client: Connects to Dereth Tracker's WebSocket stream
• Message Filter: Only processes {"type": "rare"} messages
• Classifier: Determines rare type based on name keywords
• Discord Client: Posts formatted embeds to appropriate channels
• Retry Logic: Automatic reconnection with exponential backoff

Dependencies

• discord.py>=2.3.0 - Discord API client
• websockets>=11.0.0 - WebSocket client library

Benefits

• Zero Duplication: Each rare generates exactly one notification
• Real-time: Instant notifications via WebSocket stream
• Lightweight: Minimal resource usage (~50MB RAM)
• Reliable: Robust error handling and reconnection logic
• Integrated: Seamlessly works with existing Dereth Tracker infrastructure