<p align="center"> <a href="https://bot.rustplus.io/"><img src="./rustplusbot.png" width="400"></a> </p>

RustPlusBot plugins reference and examples

RustPlusBot plugins allow you to develop your own commands to add functionality to the bot. The plugin itself exposes many events for a programmer to attach to and execute code.

The plugins are written in JavaScript and run in a NodeJS environment after they are published. During development, you host the plugin on your client machine and in your web-browser. Your plugin interfaces with the bot via a WebSocket connection and communicates using the RustPlusBot api.

[!NOTE] Plugins are loaded when the bot is starting and lasts for its entire life-cycle. Restarting the bot also restarts all plugins.

You can load any of the official plugins and use them as a template for getting started in the Plugin Studio. The Plugin Studio can be accessed via a link in the Plugin settings tab on the RustPlusBot settings page for your Discord server.

You can find the list of plugin examples in the <a href="#plugin-examples">plugin examples</a> section.

Plugin Reference

<ul> <li><a href="#plugin-storage">Plugin Storage</a></li> <li><a href="#plugin-events">Plugin Events</a></li> <li><a href="#plugin-interface">Plugin Interface</a><ul><li><a href="#properties">Properties</a></li><li><a href="#methods">Methods</a></li><li><a href="#other-methods">Other Methods</a></li><li><a href="#data-types">Data Types</a></li></ul></li> <li><a href="#plugin-globals">Plugin Globals</a></li> <li><a href="#plugin-publishing">Plugin Publishing</a></li> <li><a href="#plugin-examples">Plugin Examples</a></li> </ul>

Plugin Storage

For data that persists beyond the bot's instance, use this.storage. This object loads with the bot and saves when it stops or restarts.

// store the myData variable
if (!this.storage.myData) this.storage.myData = 'Hello World!';
console.log(this.storage.myData);

Plugin Events

<ul> <li><code>onConnected()</code> Fires when the bot connects to a server or when the plugin loads</li> <li><code>onDisconnected()</code> Fires when the bot disconnects from a server</li> <li><code>onEntityChanged(obj)</code> Fires when a paired Smart Device is changed<ul><li><b>obj.entityId</b>: ^{<code>int</code>} The entity ID of the Smart device</li><li><b>obj.payload</b>: ^{<code>object</code>} The payload data of the event (see <code><a href="#Payload">Payload</a></code> below)</li></ul></li> <li><code>onMessageReceive(obj)</code> Fires when a team chat message is received<ul><li><b>obj.message</b>: ^{<code>string</code>} The incoming team chat message</li><li><b>obj.name</b>: ^{<code>string</code>} The steam name of the sender</li><li><b>obj.steamId</b>: ^{<code>string</code>} The steam ID of the sender</li></ul></li> <li><code>onMessageSend(obj)</code> Fires when a team chat message is sent<ul><li><b>obj.message</b>: ^{<code>string</code>} The outgoing team chat message</li></ul></li> <li><code>onNotification(obj)</code> Fires when there is a bot notification (including server events)<ul><li><b>obj.notification</b>: ^{<code>object</code>} The notification data of the event (see all <code><a href="#NotificationAlarm">Notification</a></code> below)</li></ul></li> <li><code>onTeamChanged(obj)</code> Fires when the team leader changes, or a team member is added or removed from the team<ul><li><b>obj.leaderSteamId</b>: ^{<code>object</code>} The steam ID of the team leader</li><li><b>obj.leaderMapNotes</b>: ^{<code>object</code>} The leader map notes data of the event (see <code><a href="#MapNotes">MapNotes</a></code> below)</li><li><b>obj.members</b>: ^{<code>object</code>} The members list data of the event (see <code><a href="#Members">Members</a></code> below)</li></ul></li> </ul>

[!NOTE] To handle bot configuration changes or other update events, take a look at <a href="#other-methods">registeredHandlers</a>.

Plugin Interface

The app object exists in the plugin's scope this, and exposes the following properties and methods:

Properties

<ul> <li><code>bmData</code> ^{<code>object</code>} An object containing the BattleMetrics data of the server (see <code><a href="#BattleMetricsData">BattleMetrics Data</a></code> below)</li> <li><code>cameras</code> ^{<code>array</code>} An array containing all camera indentifiers saved from the Camera Station</li> <li><code>cfg</code> ^{<code>object</code>} An object containing the configuration settings for the bot (see <code><a href="#Config">Config</a></code> below)</li> <li><code>devices</code> ^{<code>Map</code>} A <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map">Map</a> object containing the bot's paired devices (<b>key</b>: device name (lowercase only), <b>value</b>: Array of devices, see <code><a href="#Device">Device</a></code> below)</li> <li><code>devices_auto</code> ^{<code>Map</code>} A <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map">Map</a> object containing the bot's automatic paired devices function (<b>key</b>: device name, <b>value</b>: An object containing the automatic function config (see <code><a href="#DeviceAuto">DeviceAuto</a></code> below))</li> <li><code>devices_icons</code> ^{<code>Map</code>} A <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map">Map</a> object containing the bot's paired device icons (<b>key</b>: device name, <b>value</b>: The icon name of the device)</li> <li><code>devices_map</code> ^{<code>Map</code>} A <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map">Map</a> object containing the bot's paired device names (<b>key</b>: device ID, <b>value</b>: Array of lowercased device names)</li> <li><code>event_types</code> ^{<code>Map</code>} A <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map">Map</a> object containing server event names (<b>key</b>: event ID, <b>value</b>: event name)</li> <li><code>eventTimers</code> ^{<code>object</code>} An object containing the respawn timers for server events in seconds (see <code><a href="#EventTimers">Event Timers</a></code> below)</li> <li><code>guild_token</code> ^{<code>string</code>} The unique token representing the Discord server</li> <li><code>guild_name</code> ^{<code>string</code>} The name of the Discord server</li> <li><code>itemIds</code> ^{<code>Map</code>} A <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map">Map</a> object containing the item names for all item IDs (<b>key</b>: item ID, <b>value</b>: item name)</li> <li><code>itemShortnames</code> ^{<code>Map</code>} A <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map">Map</a> object containing the item shortnames for all item IDs (<b>key</b>: item ID, <b>value</b>: item shortname)</li> <li><code>itemMatchIgnore</code> ^{<code>array</code>} An array containing all the item names that should be ignored when suggesting item names</li> <li><code>monuments</code> ^{<code>Map</code>} A <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map">Map</a> object containing all monument tokens and locations (<b>key</b>: monument token, <b>value</b>: Array of monument locations, see <code><a href="#Point">Point</a></code> below)</li> <li><code>tokenMap</code> ^{<code>Map</code>} A <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map">Map</a> object containing the monument names for all monument tokens (<b>key</b>: monument token, <b>value</b>: monument name)</li> <li><code>player_id</code> ^{<code>string</code>} The steam ID of the bot's connected player</li> <li><code>player_name</code> ^{<code>string</code>} The steam name of the bot's connected player</li> <li><code>server_ip</code> ^{<code>string</code>} The IP address of the bot's connected server</li> <li><code>server_name</code> ^{<code>string</code>} The name of the bot's connected server</li> <li><code>server_port</code> ^{<code>string</code>} The port of the bot's connected server (Rust+ app port)</li> <li><code>server_tags</code> ^{<code>string</code>} Internal tags used to describe this server</li> </ul>

// get the bot's language setting
console.log(this.app.cfg.lang);

Methods

<ul> <li><code>getBattleMetrics(playerName, success, error)</code> Retrieve the BattleMetrics info for a server player using their player name<ul><li><b>playerName</b>: ^{<code>string</code>} The name of the player</li><li><b>success(data)</b>: ^{<code>function</code>} The function to execute after receiving the BattleMetrics data (optional)</li><li><b>error(err)</b>: ^{<code>function</code>} The function to execute when an error occurs (optional)</li><li><b>returns</b>: ^{<code>bool</code>} <code>true</code></li></ul><p><pre><code>// getBattleMetrics example var app = this.app; app.getBattleMetrics('Rust Player 2099', (data) => { if (data && data.name) { if (data.online) app.sendTeamMessage('Player ' + cmdFormat(data.id) + ' \'' + cmdFormat(data.name) + '\' is ONLINE and has been connected for ' + getTimeDisplay(getTimeDifference(new Date(data.lastseen)), true)); else app.sendTeamMessage('Player ' + cmdFormat(data.id) + ' \'' + cmdFormat(data.name) + '\' is OFFLINE and was last seen ' + getFriendlyDate(data.lastseen)); app.sendTeamMessage('Player ' + cmdFormat(data.id) + ' was first seen ' + getFriendlyDate(data.firstseen) + ' and t