Skip to content

About

A Discord Bot that uses the rustplus.js library to utilize the power of the Rust+ Companion App with additional Quality-of-Life features.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

RustPlusPlus Discord Bot Add-on

Rust++ + Home Assistant image

A Home Assistant add-on for running the RustPlusPlus Discord bot, which connects to Rust game servers via the Rust+ Companion App.


⚠️ Facepunch removed event & vending machine data from Rust+ (6 August 2026)

In the Power Trip update, Facepunch stopped sending vending machine and event map markers (cargo, helis, travelling vendor) to Rust+. This is a change on Facepunch's side that affects every Rust+ app and bot — it is not a bug in this add-on, and there is no version you can downgrade to that brings it back.

No longer working: Cargo Ship / Patrol Helicopter / Chinook (CH47) / Oil Rig crate / Traveling Vendor / Deep Sea vendor notifications, the matching in-game and Discord commands, all vending machine features (/market, market subscriptions, the WebUI Shops Browser, Insta-Profit trades, shop pins on the live map) and event history/predictions in statistics.

Still working: teammate tracking and the live map, team chat bridge, Smart Switches and groups, Smart Alarms, Storage Monitors and TC upkeep, cameras and drones, server info and time, BattleMetrics player tracking, and Discord presence.

Details, what is being done about it, and the possible workarounds: Announcement #48


About

RustPlusPlus is a powerful Discord bot that provides Quality-of-Life features for Rust players by integrating with the Rust+ Companion App.

Features

  • 🚁 Event Notifications: Get notified about Patrol Helicopter, Cargo Ship, Chinook 47, and Oil Rig events
  • 🔌 Smart Device Control: Control Smart Switches and Smart Switch Groups via Discord, and in-game chat
  • 🚨 Smart Alarms: Set up alarms that notify you when triggered
  • 📦 Storage Monitoring: Monitor Tool Cupboard upkeep and container contents
  • 💬 Team Communication: Bridge Discord and in-game team chat
  • 👥 Player Tracking: Track other teams using BattleMetrics integration (requires a BattleMetrics API key)
  • 🎮 Discord Bot Presence: Bot status shows the connected server name and online teammate count
  • 🛠️ QoL Commands: Extensive list of helpful commands for Discord and in-game use
  • 🗺️ WebUI: Live map (teammate pins, events, shops with hover cards), Shops Browser and Insta-Profit trade finder with item icons, team statistics with an activity heatmap and player forecast, map replay
  • 🔐 Secured WebUI: Password/token login on direct access

Installation

Step 1: Add the Repository

  1. Navigate to Settings → Add-ons → Add-on Store in your Home Assistant
  2. Click the ⋮ menu in the top right corner
  3. Select Repositories
  4. Add this repository URL: https://github.com/KarlisKocins/homeassistant-addon-rustplusplus
  5. Click Add

Step 2: Install the Add-on

  1. Find "RustPlusPlus Discord Bot" in the add-on store
  2. Click on it and press Install
  3. Wait for the installation to complete

Step 3: Configure the Add-on

  1. Go to the Configuration tab
  2. Fill in the required fields:
    • Discord Client ID: Your Discord application's client ID
    • Discord Token: Your Discord bot token
    • Log Level: Choose your preferred logging level (info recommended)

Step 4: Start the Add-on

  1. Go to the Info tab
  2. Click Start
  3. Check the Log tab to ensure everything is running correctly

Configuration

Discord Bot Setup

Before using this add-on, you need to create a Discord bot:

  1. Go to the Discord Developer Portal
  2. Click New Application and give it a name
  3. Go to the Bot section and click Add Bot
  4. Copy the Token (this is your Discord Token)
  5. Enable Message Content Intent under Privileged Gateway Intents
  6. Go to OAuth2 → General and copy the Client ID
  7. In OAuth2 → URL Generator:
    • Select bot scope
    • Select required permissions (Administrator recommended for full functionality)
    • Use the generated URL to invite the bot to your Discord server

Rust+ Credentials

You'll need to get your Rust+ credentials using the official credential application:

  1. Download the RustPlusPlus Credential Application
  2. Run the application and follow the instructions

Configuration Options

Option Type Default Description
discord_client_id string Required Your Discord application's client ID
discord_token password Required Your Discord bot token
log_level list info Logging level (debug, info, warning, error)
battlemetrics_api_key password (empty) BattleMetrics API token, required for player tracking. See Player Tracking
webui_enabled boolean false Enable/disable the built-in RustPlusPlus WebUI
webui_port integer 3001 Port used by the WebUI when enabled
webui_password password (empty) Password for the WebUI login on direct access. If left empty, a random access token is generated and printed in the add-on log on every start
database_path string /data/statistics.db Path for the statistics database used by WebUI/statistics features
positions_retention_days integer 14 How many days of player position history to keep for map replay; older rows are deleted during hourly maintenance

Player Tracking

Player trackers, the /players command and the information-channel player list all read the server's player list from the BattleMetrics API.

BattleMetrics used to serve this for free. It no longer does — every endpoint now answers 403 Access denied. A subscription is required to use the API. A subscription and an API key are therefore required for these features.

Setting the API key

  1. Subscribe to a plan at battlemetrics.com
  2. Generate a token at battlemetrics.com/developers/token
  3. Paste it into the battlemetrics_api_key option in the add-on Configuration tab
  4. Restart the add-on

The key is stored as a Home Assistant secret and sent as a Bearer token. Requests are pinned to api.battlemetrics.com and redirects are refused, so the token is never forwarded to another host.

Without an API key

The rest of the add-on is unaffected — smart devices, alarms, storage monitors, events, team chat, the map and the WebUI all work normally. Only the player-tracking features are unavailable:

  • Player trackers report no players
  • /players returns nothing
  • The information-channel player list is removed rather than shown empty

The add-on log prints a warning at startup when no key is set.

WebUI / Statistics

The add-on can run an optional RustPlusPlus WebUI. When enabled, it listens on the configured webui_port. Statistics and related feature data are stored in the SQLite database at database_path (default: /data/statistics.db).

There are two ways to open the WebUI:

  • Through Home Assistant (recommended): use the add-on's Open Web UI button or the sidebar panel (ingress). No extra login is needed — Home Assistant's own authentication protects it.
  • Directly at http://HOME_ASSISTANT_IP:<webui_port>: a login is required. Set webui_password in the configuration, or use the random access token printed prominently in the add-on log at startup (a new token is generated on every restart until a password is set).

WebUI highlights:

  • Live map with teammate pins, event markers, vending machine icons and shop hover cards
  • Shops Browser and Insta-Profit trade route finder, both with item icons
  • Team statistics: sessions, deaths, chat history, a 7×24 activity heatmap and a player-count forecast
  • Map replay of recorded team positions (retention controlled by positions_retention_days)

Example optional settings:

webui_enabled: true
webui_port: 3001
webui_password: "choose-a-strong-password"
database_path: /data/statistics.db
positions_retention_days: 14

Usage

First Time Setup

  1. After starting the add-on, join your Discord server where the bot was invited
  2. Use the /credentials command to set up your Rust+ credentials
  3. Use the /pair command to connect to your Rust server
  4. Configure your desired features using the bot's commands

Common Commands

  • /help - Show all available commands
  • /credentials - Set up Rust+ credentials
  • /pair - Connect to a Rust server
  • /map - View the server map
  • /players - See online players
  • /upkeep - Check tool cupboard upkeep

Smart Switch Auto Modes

Smart Switch automation includes AUTO-NIGHT-ANY-ONLINE. This mode turns switches on only at night when at least one teammate is online, and turns them off during daytime or when all teammates are offline.

Discord Bot Presence

When connected to a Rust server, the bot's Discord status automatically displays:

  • The server name
  • The number of online teammates (e.g., My Rust Server | 3/5 Online)

Data Persistence

The add-on stores data in the following locations:

  • Credentials: /data/credentials/
  • Server Instances: /data/instances/
  • Logs: /data/logs/
  • Maps: /data/maps/
  • Statistics Database: /data/statistics.db (default, configurable via database_path)

All data persists between add-on restarts and updates.

Troubleshooting

First Installation Issues

If you encounter issues during the first installation, try restarting the add-on:

  1. Go to the Info tab
  2. Click Stop to stop the add-on
  3. Wait a few seconds, then click Start
  4. Check the Log tab to verify the add-on is running correctly

Sometimes a restart can resolve initialization problems or temporary configuration issues that may occur during the initial setup.

Bot Not Responding

  1. Check the add-on logs for errors
  2. Verify your Discord token and client ID are correct
  3. Ensure the bot has proper permissions in your Discord server
  4. Check if the bot is online in your Discord server

Connection Issues

  1. Verify your Rust+ credentials are valid
  2. Check if the Rust server supports Rust+ (most official servers do)
  3. Ensure you're paired with the correct server
  4. Try restarting the add-on

Player Tracking Issues

  1. Access denied. A subscription is required to use the API in the log means BattleMetrics rejected the request. Either no battlemetrics_api_key is set, the token is wrong, or the subscription lapsed. Verify the token at battlemetrics.com/developers/token
  2. After adding or changing the key, restart the add-on — it is read from the environment at startup
  3. Empty player lists with no error in the log usually mean the server has no BattleMetrics ID stored. Check the server's settings in the Discord settings channel
  4. Player tracking is the only feature that needs the key. If devices, events or the map are also broken, the cause is elsewhere — see the sections above

WebUI Login Issues

  1. When opening the WebUI on its direct URL, a login is required — this is expected since v2.0.0
  2. If you haven't set webui_password, find the auto-generated access token in the add-on Log tab (printed in a highlighted block at startup)
  3. Opening the WebUI through the Home Assistant sidebar or the Open Web UI button never asks for this login
  4. After changing webui_password, restart the add-on and hard-refresh the browser (Ctrl+F5)

Log Analysis

Check the add-on logs in the Log tab for detailed error messages. Common issues include:

  • Invalid Discord credentials
  • Missing Rust+ credentials
  • Network connectivity problems
  • Server pairing issues

Development Smoke Test

For local development/release checks, run the startup smoke test:

chmod +x scripts/ha_addon_smoke_test.sh
./scripts/ha_addon_smoke_test.sh

This emulates add-on startup with a generated /data/options.json plus a mock Supervisor API endpoint, and fails if bootstrap does not reach run.sh -> node index.js.

Support

For support and documentation:

License

This add-on is based on RustPlusPlus by alexemanuelol, licensed under GPL-3.0.

About

A Discord Bot that uses the rustplus.js library to utilize the power of the Rust+ Companion App with additional Quality-of-Life features.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages