Discord Gameserver Notifier

Overview

The Discord Gameserver Notifier is a Python-based tool for automatic detection of game servers in local networks with Discord notifications via webhooks. It uses opengsq-python for game server communication and provides real-time monitoring of gaming communities.

Perfect for LAN parties, gaming events, and local gaming communities!

Main Features

Supported Games

Installation

Prerequisites

• Python 3.9 or higher
• Network access for UDP broadcast queries
• Discord webhook URL

Available Packages

The tool is available in various package formats:

Option 1: PyPI (Recommended)

# Install from PyPI
pip install Discord-Gameserver-Notifier

# Run directly
discord-gameserver-notifier --help

Option 2: System Packages

Debian/Ubuntu (.deb):

wget https://github.com/lan-dot-party/Discord-Gameserver-Notifier/releases/latest/download/discord-gameserver-notifier_*.deb
sudo dpkg -i discord-gameserver-notifier_*.deb
sudo apt-get install -f  # Fix dependencies if needed

RHEL/Fedora/openSUSE (.rpm):

wget https://github.com/lan-dot-party/Discord-Gameserver-Notifier/releases/latest/download/discord-gameserver-notifier-*.rpm
sudo rpm -i discord-gameserver-notifier-*.rpm

Arch Linux (.pkg.tar.zst):

wget https://github.com/lan-dot-party/Discord-Gameserver-Notifier/releases/latest/download/discord-gameserver-notifier-*.pkg.tar.zst
sudo pacman -U discord-gameserver-notifier-*.pkg.tar.zst

All package installations place the executable in /usr/bin/discord-gameserver-notifier and are ready to use system-wide.

Option 3: Manual Installation (Development)

# Clone repository
git clone https://github.com/lan-dot-party/Discord-Gameserver-Notifier.git
cd Discord-Gameserver-Notifier

# Install dependencies
pip install -r requirements.txt

# Configure
cp config/config.yaml.example config/config.yaml
# Edit config/config.yaml

# Run
python main.py

REST API

The Discord Gameserver Notifier includes an optional HTTP REST API for read-only access to discovered servers:

Configuration

api:
  enabled: true           # Enable/disable API
  host: "0.0.0.0"        # Bind address (0.0.0.0 = all interfaces, 127.0.0.1 = localhost only)
  port: 8080             # API port

Features

• Read-Only Access: Safe, no data modification possible
• JSON Format: Standard REST API with JSON responses
• Active Servers Only: Automatically filters inactive servers
• Thread-Safe: Multiple concurrent requests supported
• Asynchronous: Non-blocking operation with aiohttp

Available Endpoints

• GET / - API information and version
• GET /health - Health check endpoint
• GET /servers - List all active game servers

Use Cases

• Display servers on your LAN party website
• Create Discord bots with server status
• Monitor server utilization with Grafana/Prometheus
• Build mobile apps for your gaming community

Systemd Service (Linux)

For automatic startup and service management on Linux systems, the systemd service is automatically created when installing via package managers (.deb, .rpm, .pkg.tar.zst or PyPI).

Service Features

• Runs as dedicated dgn system user
• Automatic restart on failure
• Proper logging to systemd journal
• Security hardening (restricted filesystem access)
• Configuration in /etc/dgn/config.yaml
• Data stored in /var/lib/dgn/
• Logs in /var/log/dgn/
• Executable located in /usr/bin/discord-gameserver-notifier

Service Commands

# Edit configuration (service file is already created)
sudo nano /etc/dgn/config.yaml

# Enable and start service
sudo systemctl enable discord-gameserver-notifier
sudo systemctl start discord-gameserver-notifier

# Check status
sudo systemctl status discord-gameserver-notifier

# View logs
sudo journalctl -u discord-gameserver-notifier -f

Advanced Features

• Network Discovery Methods: Active broadcasts, passive listening, two-step discovery, multi-protocol support
• Discord Integration: Rich embeds with game-specific colors and emojis, server details, status updates, message management, flexible mentions (global and game-specific), optional self-updating server overview
• Performance Features: Asynchronous operations, connection pooling, response caching, graceful error handling
• Security Features: Network range filtering and secure webhook management
• Comprehensive Logging: Detailed logging with configurable levels and file output
• Database Management: Automatic SQLite database with server history and statistics
• Graceful Shutdown: Proper cleanup and database maintenance on application exit

Downloads & Releases

Download the latest version of the Discord Gameserver Notifier:

Here you'll find all available versions with detailed changelogs and download links for all supported platforms.

Configuration

Copy config/config.yaml.example to config/config.yaml and adjust the settings:

Basic Configuration

network:
  scan_ranges:
    - "192.168.1.0/24"    # Your local network
    - "10.0.0.0/24"       # Additional networks
  scan_interval: 300      # Scan every 5 minutes
  timeout: 5              # Server response timeout
  
  # Ignore specific network ranges
  ignore_ranges:
    - "192.168.100.0/24"  # Test network
    - "10.10.10.0/24"     # Development environment

games:
  enabled:
    - "source"            # Source Engine games
    - "battlefield2"      # Battlefield 2
    - "warcraft3"         # Warcraft III
    - "renegadex"         # Renegade X
    # ... more games

discord:
  webhook_url: "YOUR_WEBHOOK_URL"
  mentions:
    - "@everyone"         # Global for all games

  # Optional: Persistent server overview (own webhook, see "Gameserver Overview" below)
  overview:
    enabled: false
    webhook_url: ""              # or env DGN_DISCORD_OVERVIEW_WEBHOOK_URL
    title: "🎮 Gameserver-Übersicht"
    show_stale: true             # mark servers missing in the last scan with 🟡 (false = hide them)
    refresh_interval: 300        # refresh the timestamp at least every X seconds (0 = only on changes)
    pause_on_shutdown: true      # show "Übersicht pausiert" while DGN is stopped

  game_mentions:
    battlefield2:
      - "<@&ROLE_ID>"    # Additionally for Battlefield 2
    source:
      - "<@&ROLE_ID>"    # Additionally for Source Engine

Discord Setup

1. Create a webhook in your Discord server: Server Settings → Integrations → Webhooks → Create Webhook
2. Copy the webhook URL to your configuration
3. Configure optional mentions and channel settings

Gameserver Overview (optional, since 0.4.0)

In addition to the notifications, DGN can keep a persistent overview of all active servers in a dedicated channel: one message (Discord Components V2) that is edited in place whenever servers appear or disappear, or players or maps change, instead of posting new messages. This gives players one place to see what is running on the LAN right now. The feature is disabled by default; the regular notifications keep working unchanged through discord.webhook_url.

Setup

1. Create a dedicated text channel (e.g. #gameserver-overview) and remove the "Send Messages" permission for @everyone, so that the channel only contains the overview
2. Create a separate webhook in that channel (do not reuse the notification webhook)
3. Enable the overview and set the webhook URL. Using the environment variable DGN_DISCORD_OVERVIEW_WEBHOOK_URL is recommended, so that the secret stays out of the config file

discord:
  overview:
    enabled: true
    webhook_url: ""              # or env DGN_DISCORD_OVERVIEW_WEBHOOK_URL
    title: "🎮 Gameserver-Übersicht"
    show_stale: true             # mark servers missing in the last scan with 🟡 (false = hide them)
    refresh_interval: 300        # refresh the timestamp at least every X seconds (0 = only on changes)
    pause_on_shutdown: true      # show "Übersicht pausiert" while DGN is stopped

What it looks like

• One box, grouped by game. For each server it shows the name, players, map and IP:Port as copyable text
• 🟢 = found in the last scan, 🟡 = not reachable in the last scan (removed after database.inactive_minutes / cleanup_after_fails), 🔒 = password protected
• Footer with timestamp (shown in each viewer's own time zone), server count and player count
• With many servers, the overview is split across several messages (max. 5)

Good to know

• The message IDs are stored in the database (table app_state). After a restart, DGN keeps editing the same message. If the message is deleted manually, DGN posts it again.
• If the database is lost or the webhook is replaced, old overview messages stay in the channel and have to be deleted manually (a webhook cannot list its own messages).
• A "Join" button is not possible. Discord only allows http, https and discord:// in links and buttons, so steam://connect/... is rejected or shown as plain text.
• If the webhook is invalid or deleted, the overview disables itself until the next restart (with an error in the log), so that Discord does not rate-limit DGN for repeated failures.

Usage

After Package Installation

# Standard execution
discord-gameserver-notifier

# With debug logging
discord-gameserver-notifier --log-level DEBUG

# Background execution
nohup discord-gameserver-notifier &

Monitoring

The application provides comprehensive logging:

INFO - Starting main application loop...
INFO - Discovery engine started successfully
INFO - NetworkScanner initialized with 2 scan ranges
INFO - Found 3 source servers
INFO - Discovered source server: Counter-Strike 1.6 Server
INFO - Server details: 192.168.1.100:27015
INFO - Players: 12/32, Map: de_dust2

License & Acknowledgments

This project is licensed under the GNU General Public License v3.0.

Acknowledgments:

• opengsq-python for game server protocol implementations
• Discord community for webhook API documentation
• Game server communities for protocol specifications