Skip to content

eman225511/RustPlusRaidAlarms

BranchesTags

Repository files navigation

🚨 RustPlus Raid Alarms

Never miss a raid again! Get instant notifications on your phone, auto-launch Rust, flash your lights, and more when your base is under attack.

Python PySide6 License: MIT Telegram

Sleek desktop app that monitors Telegram for raid alerts from Rust+ (via IFTTT) and triggers customizable plugins—no coding required!

🚀 Quick Start • 📚 Documentation • 🔌 Plugins • 🤝 Contributing

✨ Features

📱 Telegram Integration
  • ⚡ Real-time message polling with configurable rate (default: 2 seconds)
  • 🔍 Optional keyword filtering for selective alerts
  • 👥 Support for channels and group chats
  • ⚙️ Easy configuration via in-app Settings dialog
  • 🔄 Auto-retry on connection failures
🎮 IFTTT + Rust+ Integration
  • 🔗 Connect your Rust server to automatically send raid alarms
  • 🎯 Trigger on events: raids, cargo ship, helicopter, player activity
  • 📝 Customize alert messages with smart-alarm data
  • 📺 Video tutorials included! See IFTTT Setup Guide
🔌 Plugin Architecture
  • 🛒 Built-in Plugin Store with search + one-click install/update/uninstall
  • 🔍 Auto-discovered from plugins/ folder every 5 seconds
  • 🔥 Hot-reload: add/remove plugins without restarting
  • 📄 Supports both single-file (plugin.py) and package (plugin/__init__.py) formats
  • 🛠️ Plugin base API for UI widgets, config persistence, Telegram hooks
  • 📖 Example plugins included as development templates
🎨 Modern Dark UI
  • 🃏 Card-based layout with hero sections
  • 📑 Left-side navigation with plugin tabs
  • 🌑 Unified dark theme (#1e1e1e background, #131418 cards, #0e639c accents)
  • 🖱️ Drag-and-drop plugin tab reordering
  • ✅ Per-plugin enable/disable toggles
  • 🧹 Clear log button in Activity Log
  • 📐 Responsive design with proper spacing and padding

🚀 Quick Start

Click to expand setup instructions

🪟 Windows Users (Easiest Method)

Just double-click run.bat!

The script will automatically:

  • ✅ Check for Python (downloads portable version if needed)
  • ✅ Create virtual environment
  • ✅ Install all dependencies
  • ✅ Launch the application

No manual setup required! 🎉

🐧 Manual Setup (All Platforms)

1️⃣ Clone the Repository

git clone https://github.com/eman225511/RustPlusRaidAlarms.git
cd RustPlusRaidAlarms

2️⃣ Install Dependencies

pip install -r requirements.txt

3️⃣ Set Up Telegram

4️⃣ Connect IFTTT + Rust+ (optional)

5️⃣ Run the App

Windows:

run.bat

macOS/Linux:

python main.py

6️⃣ Customize Plugins (optional)

  • Navigate to plugin tabs in the left sidebar
  • Configure LED devices, phone numbers, audio files, Discord webhooks, etc.
  • Use the ❓ help buttons for setup guides
  • Click test buttons to verify everything works
  • Enable the plugins you want with the checkboxes!

🔌 Plugins

Plugins are automatically loaded from the plugins/ directory and appear in the left sidebar. No core code changes needed—just drop in your plugin and it's ready!

🛒 Plugin Store (recommended)

  • Open Plugins → Store in the app
  • Use the search bar to filter by name/author/tag
  • Click Install or Update; uninstall from the Installed tab
  • Plugins live in your local plugins/ folder (not committed to git)

💡 Built-in Plugins

Plugin Description Guide
💡 LED Controller Flash WLED, Govee, or Philips Hue lights when raided 📖 Guide
🎮 Rust Auto-Connect Automatically launch Rust and join your server 📖 Guide
📞 Twilio Caller Call multiple phone numbers to wake you up 📖 Guide
🔊 Audio Alert Play custom sounds on multiple audio devices 📖 Guide
💬 Discord Webhook Post raid alerts to Discord with @mentions 📖 Guide
🛠️ Creating Your Own Plugins

Plugin Types

  • 📄 Single-file: plugins/my_plugin.py (simple plugins)
  • 📦 Package: plugins/my_plugin/__init__.py (complex plugins with multiple files)

Learn More

See the Plugin Development Guide for:

  • ✅ Plugin base class and required methods
  • 🎨 UI creation with PySide6/Qt
  • 💾 Config persistence patterns
  • 📨 Telegram message hooks
  • 🎨 Styling guidelines
  • 💻 Complete skeleton code

Submit your plugin to the store

  1. Build your plugin (single-file or package) and include metadata methods (get_version, get_author, get_homepage).
  2. Zip the plugin folder/file and host it (GitHub release or raw link).
  3. Add an entry to index.json in the RustPlusRaidAlarmPlugins repo with your metadata and download URL, then open a PR.
  4. Keep version numbers updated for smooth Update prompts.

Example Plugins

  • plugins/example_plugin/ — Package-based plugin with advanced features
  • plugins/simple_example.py — Minimal single-file implementation

📚 Documentation

🚀 Getting Started

🔌 Plugin Guides

🛠️ Advanced

💡 LED Controller Plugin

Control smart LED devices with trigger-on-message support → Full Guide

Supported Devices

  • WLED — WiFi-enabled LED controllers
  • Govee — Cloud-based smart lighting (requires API key)
  • Philips Hue — Zigbee bridge-based smart bulbs

Actions

  • On/Off — Simple power control
  • Color — RGB color picker with hex preview
  • Effect — WLED animated effects (0–255)
  • Preset — WLED saved presets (0–255)
  • Scene — Govee predefined scenes (0–50)
  • Brightness — Intensity control (WLED: 0–255, Govee: 0–100%)

Configuration

Each device type requires specific credentials:

  • WLED: Device IP address
  • Govee: API key, device ID, device model
  • Philips Hue: Bridge IP, bridge username

See the LED Plugin Guide for detailed setup instructions and troubleshooting.

⚙️ Configuration

All settings are stored in config.json (auto-created on first launch)

📱 Telegram Settings

  • Bot token and chat ID (configured via Settings dialog)
  • Polling rate (seconds between checks)
  • Keyword filter toggle and keyword

💡 LED Settings

  • Device type (WLED/Govee/Hue)
  • Device credentials (IP/API keys/bridge info)
  • Default action and parameters (color, effect, preset, scene, brightness)

✏️ Editing Config

Method Description
✅ Recommended Use the in-app Settings dialog and plugin UIs
📝 Manual Edit config.json directly (close app first to avoid overwrites)
🔄 Reset Delete config.json to restore defaults
📄 Template config.example.json is provided; copy to config.json if needed

🔧 Feature Toggles

  • show_example_plugins — show/hide example plugins in sidebar
  • plugin_enabled_<PluginName> — per-plugin enable/disable state

💡 See the Configuration Guide for the complete config.json schema and field descriptions.

📁 Project Structure

Click to view folder layout 
RustPlusRaidAlarms/
├── main.py                    # App shell, plugin loader, dark theme
├── telegram_service.py        # Telegram polling with auto-retry
├── plugin_base.py             # Abstract plugin base class
├── config.json                # Auto-generated config [gitignored]
├── config.example.json        # Template config file
├── requirements.txt           # Python dependencies
│
├── plugins/
│   ├── led_plugin/            # 💡 LED controller (WLED/Govee/Hue)
│   ├── rust_connect.py        # 🎮 Rust auto-connect
│   ├── twilio_plugin/         # 📞 Twilio phone calls
│   ├── audio_alert.py         # 🔊 Custom sound alerts
│   ├── discord_webhook.py     # 💬 Discord notifications
│   ├── example_plugin/        # Development template (package)
│   └── simple_example.py      # Development template (single-file)
│
└── docs/
    ├── TELEGRAM_SETUP.md      # Bot creation with video guides
    ├── IFTTT_RUST_SETUP.md    # IFTTT + Rust+ integration
    ├── PLUGIN_DEVELOPMENT.md  # Plugin API and creation guide
    ├── CONFIGURATION.md       # config.json schema
    ├── TROUBLESHOOTING.md     # Common issues
    └── plugins/               # Individual plugin guides
        ├── LED_CONTROLLER.md
        ├── RUST_CONNECT.md
        ├── TWILIO_CALLER.md
        ├── AUDIO_ALERT.md
        └── DISCORD_WEBHOOK.md

🤝 Contributing

Contributions are welcome! Here's how you can help

🔌 Adding Plugins

  1. Create your plugin in plugins/your_plugin/ or plugins/your_plugin.py
  2. Inherit from PluginBase and implement required methods
  3. Test using the app's plugin auto-reload (no restart needed)
  4. See Plugin Development Guide for API details

📝 Code Guidelines

  • ✅ Keep plugin code within plugin widgets—avoid modifying core files
  • 🎨 Follow the existing dark theme styling patterns (see main.py CSS)
  • 💾 Use config dict for persistence (auto-saved/merged)
  • 📦 Add dependencies to requirements.txt if needed

🚀 Submitting Changes

  • ✔️ Test your changes thoroughly (LED devices, Telegram, plugin loading)
  • 📖 Include documentation updates if adding features
  • 💬 Create descriptive commit messages
  • 🔀 Open a pull request with a clear description
  • 🐛 Use the GitHub issue templates for bugs/feature requests

🐛 Bug Reports & Support

Need help? Here's how to get support

Before Reporting

  1. ✅ Check the Troubleshooting Guide first
  2. ✅ Search existing GitHub issues

Bug Report Checklist

  • 🖥️ OS and Python version
  • ❌ Error messages (full traceback)
  • 🔄 Steps to reproduce
  • ⚙️ Relevant config.json snippets (redact tokens/IDs!)

Feature Requests

Use the GitHub issue templates to ensure all required details are included!

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with ❤️ using:

⭐ If this project helped you defend your base, give it a star!

Report Bug • Request Feature • Documentation

Bug Reports

  • Check Troubleshooting Guide first
  • Include: OS, Python version, error messages, steps to reproduce
  • Share relevant config.json snippets (redact tokens/IDs)
  • File issues via the GitHub bug/feature templates to ensure required details are included

About

eman225511.github.io/RustPlusRaidAlarms/

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 2

Beta 1.1 Latest
Jan 17, 2026
+ 1 release

Packages

 
 
 

Contributors

Languages