@rustwirebot/rustplus.js 2.5.0

package/examples/4_entity_changed_broadcasts.js

@@ -0,0 +1,58 @@
+const RustPlus = require('@rustwirebot/rustplus.js');
+var rustplus = new RustPlus('ip', 'port', 'playerId', 'playerToken');
+
+// wait until connected before sending commands
+rustplus.on('connected', () => {
+
+    /**
+     * getting an entities info will cause the rust server
+     * to send an entity changed broadcast each time the
+     * entities state changes.
+     */
+    rustplus.getEntityInfo(1234567, (message) => {
+
+        /**
+         * you can of course see the current entity state in this callback
+         * as a 'one off' check. But broadcasts will still be sent.
+         */
+        console.log("getEntityInfo result: " + JSON.stringify(message));
+
+        /**
+         * we won't disconnect from the rust server in this example
+         * as we want to receive broadcasts in the message handler below.
+         */
+        // rustplus.disconnect();
+
+    });
+    
+});
+
+// listen for messages from rust server
+rustplus.on('message', (message) => {
+
+    // check if message is an entity changed broadcast
+    if(message.broadcast && message.broadcast.entityChanged){
+
+        /**
+         * since we called getEntityInfo, this message handler will be triggered
+         * when the entity state has changed. for example, when a smart alarm is triggered,
+         * a smart switch is toggled or a storage monitor has updated.
+         */
+
+        var entityChanged = message.broadcast.entityChanged;
+
+        // log the broadcast
+        console.log(message.broadcast);
+
+        var entityId = entityChanged.entityId;
+        var value = entityChanged.payload.value;
+
+        // log the entity status
+        console.log("entity " + entityId + " is now " + (value ? "active" : "inactive"));
+
+    }
+
+});
+
+// connect to rust server
+rustplus.connect();

package/examples/5_download_map_jpeg.js

@@ -0,0 +1,22 @@
+const fs = require('fs');
+const RustPlus = require('@rustwirebot/rustplus.js');
+var rustplus = new RustPlus('ip', 'port', 'playerId', 'playerToken');
+
+// wait until connected before sending commands
+rustplus.on('connected', () => {
+
+    // get the map
+    rustplus.getMap((message) => {
+
+        // save jpg image of map to file
+        fs.writeFileSync('map.jpg', message.response.map.jpgImage);
+
+        // disconnect from rust server
+        rustplus.disconnect();
+
+    });
+    
+});
+
+// connect to rust server
+rustplus.connect();

package/examples/6_async_requests.js

@@ -0,0 +1,35 @@
+const RustPlus = require('@rustwirebot/rustplus.js');
+var rustplus = new RustPlus('ip', 'port', 'playerId', 'playerToken');
+
+// wait until connected before sending commands
+rustplus.on('connected', () => {
+
+    /**
+     * sendRequestAsync will return a promise for your request.
+     * you can optionally pass in a second parameter for the timeout in milliseconds
+     * - AppResponse packets will be sent to `then` on success.
+     * - AppError packets and Timeout Errors will be sent to `catch`.
+     */
+    rustplus.sendRequestAsync({
+        getInfo: {}, // get server info with a timeout of 2 seconds
+    }, 2000).then((response) => {
+
+        // AppResponse
+        console.log(response);
+
+    }).catch((error) => {
+
+        // AppError or Error('Timeout');
+        console.log(error);
+
+    }).finally(() => {
+
+        // disconnect so our script is finished
+        rustplus.disconnect();
+
+    });
+    
+});
+
+// connect to rust server
+rustplus.connect();

package/examples/7_render_camera.js

@@ -0,0 +1,34 @@
+const RustPlus = require('@rustwirebot/rustplus.js');
+const fs = require("fs");
+var rustplus = new RustPlus('ip', 'port', 'playerId', 'playerToken');
+
+rustplus.on('connected', async () => {
+
+    console.log("connected");
+
+    // get a camera
+    const camera = rustplus.getCamera("DOME1");
+
+    // listen for events when a camera frame has been rendered, you will get a png image buffer
+    camera.on('render', async (frame) => {
+
+        console.log("on render");
+
+        // save camera frame to disk
+        fs.writeFileSync(`camera.png`, frame);
+
+        // unsubscribe from camera to allow others to control it
+        await camera.unsubscribe();
+
+        // disconnect from server after a single render
+        rustplus.disconnect();
+
+    });
+
+    // subscribe to camera
+    await camera.subscribe();
+
+});
+
+// connect to rust server
+rustplus.connect();

package/examples/8_move_ptz_camera.js

@@ -0,0 +1,56 @@
+const RustPlus = require('../rustplus');
+const Camera = require('../camera');
+var rustplus = new RustPlus('ip', 'port', 'playerId', 'playerToken');
+
+function delay(time) {
+    return new Promise(resolve => setTimeout(resolve, time));
+}
+
+rustplus.on('connected', async () => {
+
+    console.log("connected");
+
+    // get a camera (must support PTZ)
+    const camera = rustplus.getCamera("PTZ1");
+
+    // wait until subscribed to camera
+    camera.on('subscribed', async () => {
+
+        console.log("subscribed to camera");
+
+        // move camera up 10 times
+        for(let i = 0; i < 10; i++){
+            await camera.move(Camera.Buttons.NONE, 0, 1);
+            await delay(100);
+        }
+
+        // move camera down 10 times
+        for(let i = 0; i < 10; i++){
+            await camera.move(Camera.Buttons.NONE, 0, -1);
+            await delay(100);
+        }
+
+        // move camera left 10 times
+        for(let i = 0; i < 10; i++){
+            await camera.move(Camera.Buttons.NONE, -1, 0);
+            await delay(100);
+        }
+
+        // move camera right 10 times
+        for(let i = 0; i < 10; i++){
+            await camera.move(Camera.Buttons.NONE, 1, 0);
+            await delay(100);
+        }
+
+        console.log("disconnecting");
+        await rustplus.disconnect();
+
+    });
+
+    // subscribe to camera
+    await camera.subscribe();
+
+});
+
+// connect to rust server
+rustplus.connect();

package/examples/9_zoom_ptz_camera.js

@@ -0,0 +1,37 @@
+const RustPlus = require('../rustplus');
+var rustplus = new RustPlus('ip', 'port', 'playerId', 'playerToken');
+
+function delay(time) {
+    return new Promise(resolve => setTimeout(resolve, time));
+}
+
+rustplus.on('connected', async () => {
+
+    console.log("connected");
+
+    // get a camera (must support PTZ)
+    const camera = rustplus.getCamera("PTZ1");
+
+    // wait until subscribed to camera
+    camera.on('subscribed', async () => {
+
+        console.log("subscribed to camera");
+
+        // zoom camera every 1 second, 8 times
+        for(let i = 0; i < 8; i++){
+            await camera.zoom();
+            await delay(1000);
+        }
+
+        console.log("disconnecting");
+        await rustplus.disconnect();
+
+    });
+
+    // subscribe to camera
+    await camera.subscribe();
+
+});
+
+// connect to rust server
+rustplus.connect();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@rustwirebot/rustplus.js",
+  "version": "2.5.0",
+  "description": "NodeJS library for controlling Smart Switches and interacting with the Rust+ Companion API. Maintained fork of @liamcottle/rustplus.js, republished by BotForge Studios / RustWire.",
+  "main": "rustplus.js",
+  "bin": {
+    "rustplus": "./cli/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YOUR_GITHUB_USERNAME/rustwire-rustplus.js.git"
+  },
+  "keywords": [
+    "rust",
+    "rust+",
+    "rustplus",
+    "rustplus-api",
+    "companion",
+    "api",
+    "websocket",
+    "smart switch",
+    "smart alarm",
+    "team chat",
+    "rustwire"
+  ],
+  "author": "Liam Cottle",
+  "contributors": [
+    "BotForge Studios (fork maintainer)"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/YOUR_GITHUB_USERNAME/rustwire-rustplus.js/issues"
+  },
+  "homepage": "https://github.com/YOUR_GITHUB_USERNAME/rustwire-rustplus.js#readme",
+  "dependencies": {
+    "axios": "^1.2.2",
+    "chrome-launcher": "^0.15.0",
+    "command-line-args": "^5.2.0",
+    "command-line-usage": "^6.1.1",
+    "express": "^4.17.1",
+    "http_ece": "^1.0.5",
+    "jimp": "^0.22.7",
+    "long": "^3.2.0",
+    "protobufjs": "^7.1.2",
+    "uuid": "^11.1.1",
+    "ws": "^8.3.0"
+  }
+}

package/rustplus.js

@@ -0,0 +1,380 @@
+"use strict";
+
+const path = require('path');
+const WebSocket = require('ws');
+const protobuf = require("protobufjs");
+const { EventEmitter } = require('events');
+const Camera = require('./camera');
+
+class RustPlus extends EventEmitter {
+
+    /**
+     * @param server The ip address or hostname of the Rust Server
+     * @param port The port of the Rust Server (app.port in server.cfg)
+     * @param playerId SteamId of the Player
+     * @param playerToken Player Token from Server Pairing
+     * @param useFacepunchProxy True to use secure websocket via Facepunch's proxy, or false to directly connect to Rust Server
+     *
+     * Events emitted by the RustPlus class instance
+     * - connecting: When we are connecting to the Rust Server.
+     * - connected: When we are connected to the Rust Server.
+     * - message: When an AppMessage has been received from the Rust Server.
+     * - request: When an AppRequest has been sent to the Rust Server.
+     * - disconnected: When we are disconnected from the Rust Server.
+     * - error: When something goes wrong.
+     */
+    constructor(server, port, playerId, playerToken, useFacepunchProxy = false) {
+
+        super();
+
+        this.server = server;
+        this.port = port;
+        this.playerId = playerId;
+        this.playerToken = playerToken;
+        this.useFacepunchProxy = useFacepunchProxy;
+
+        this.seq = 0;
+        this.seqCallbacks = [];
+
+    }
+
+    /**
+     * This sets everything up and then connects to the Rust Server via WebSocket.
+     */
+    connect() {
+
+        // load protobuf then connect
+        protobuf.load(path.resolve(__dirname, "rustplus.proto")).then((root) => {
+
+            // make sure existing connection is disconnected before connecting again.
+            if(this.websocket){
+                this.disconnect();
+            }
+
+            // load proto types
+            this.AppRequest = root.lookupType("rustplus.AppRequest");
+            this.AppMessage = root.lookupType("rustplus.AppMessage");
+
+            // fire event as we are connecting
+            this.emit('connecting');
+
+            // connect to websocket
+            var address = this.useFacepunchProxy ? `wss://companion-rust.facepunch.com/game/${this.server}/${this.port}` : `ws://${this.server}:${this.port}`;
+            this.websocket = new WebSocket(address);
+
+            // fire event when connected
+            this.websocket.on('open', () => {
+                this.emit('connected');
+            });
+
+            // fire event for websocket errors
+            this.websocket.on('error', (e) => {
+                this.emit('error', e);
+            });
+
+            this.websocket.on('message', (data) => {
+
+                // decode received message
+                var message = this.AppMessage.decode(data);
+
+                // check if received message is a response and if we have a callback registered for it
+                if(message.response && message.response.seq && this.seqCallbacks[message.response.seq]){
+
+                    // get the callback for the response sequence
+                    var callback = this.seqCallbacks[message.response.seq];
+
+                    // call the callback with the response message
+                    var result = callback(message);
+
+                    // remove the callback
+                    delete this.seqCallbacks[message.response.seq];
+
+                    // if callback returns true, don't fire message event
+                    if(result){
+                        return;
+                    }
+
+                }
+
+                // fire message event for received messages that aren't handled by callback
+                this.emit('message', this.AppMessage.decode(data));
+
+            });
+
+            // fire event when disconnected
+            this.websocket.on('close', () => {
+                this.emit('disconnected');
+            });
+
+        });
+
+    }
+
+    /**
+     * Disconnect from the Rust Server.
+     */
+    disconnect() {
+        if(this.websocket){
+            this.websocket.terminate();
+            this.websocket = null;
+        }
+    }
+
+    /**
+     * Check if RustPlus is connected to the server.
+     * @returns {boolean}
+     */
+    isConnected() {
+        return (this.websocket.readyState === WebSocket.OPEN);
+    }
+
+    /**
+     * Send a Request to the Rust Server with an optional callback when a Response is received.
+     * @param data this should contain valid data for the AppRequest packet in the rustplus.proto schema file
+     * @param callback
+     */
+    sendRequest(data, callback) {
+
+        // increment sequence number
+        let currentSeq = ++this.seq;
+
+        // save callback if provided
+        if(callback){
+            this.seqCallbacks[currentSeq] = callback;
+        }
+
+        // create protobuf from AppRequest packet
+        let request = this.AppRequest.fromObject({
+            seq: currentSeq,
+            playerId: this.playerId,
+            playerToken: this.playerToken,
+            ...data, // merge in provided data for AppRequest
+        });
+
+        // send AppRequest packet to rust server
+        this.websocket.send(this.AppRequest.encode(request).finish());
+
+        // fire event when request has been sent, this is useful for logging
+        this.emit('request', request);
+
+    }
+
+    /**
+     * Send a Request to the Rust Server and return a Promise
+     * @param data this should contain valid data for the AppRequest packet defined in the rustplus.proto schema file
+     * @param timeoutMilliseconds milliseconds before the promise will be rejected. Defaults to 10 seconds.
+     */
+    sendRequestAsync(data, timeoutMilliseconds = 10000) {
+        return new Promise((resolve, reject) => {
+
+            // reject promise after timeout
+            var timeout = setTimeout(() => {
+                reject(new Error('Timeout reached while waiting for response'));
+            }, timeoutMilliseconds);
+
+            // send request
+            this.sendRequest(data, (message) => {
+
+                // cancel timeout
+                clearTimeout(timeout);
+
+                if(message.response.error){
+
+                    // reject promise if server returns an AppError for this request
+                    reject(message.response.error);
+
+                } else {
+
+                    // request was successful, resolve with message.response
+                    resolve(message.response);
+
+                }
+
+            });
+
+        });
+    }
+
+    /**
+     * Send a Request to the Rust Server to set the Entity Value.
+     * @param entityId the entity id to set the value for
+     * @param value the value to set on the entity
+     * @param callback
+     */
+    setEntityValue(entityId, value, callback) {
+        this.sendRequest({
+            entityId: entityId,
+            setEntityValue: {
+                value: value,
+            },
+        }, callback);
+    }
+
+    /**
+     * Turn a Smart Switch On
+     * @param entityId the entity id of the smart switch to turn on
+     * @param callback
+     */
+    turnSmartSwitchOn(entityId, callback) {
+        this.setEntityValue(entityId, true, callback);
+    }
+
+    /**
+     * Turn a Smart Switch Off
+     * @param entityId the entity id of the smart switch to turn off
+     * @param callback
+     */
+    turnSmartSwitchOff(entityId, callback) {
+        this.setEntityValue(entityId, false, callback);
+    }
+
+    /**
+     * Quickly turn on and off a Smart Switch as if it were a Strobe Light.
+     * You will get rate limited by the Rust Server after a short period.
+     * It was interesting to watch in game though 😝
+     */
+    strobe(entityId, timeoutMilliseconds = 100, value = true) {
+        this.setEntityValue(entityId, value);
+        setTimeout(() => {
+            this.strobe(entityId, timeoutMilliseconds, !value);
+        }, timeoutMilliseconds);
+    }
+
+    /**
+     * Send a message to Team Chat
+     * @param message the message to send to team chat
+     * @param callback
+     */
+    sendTeamMessage(message, callback) {
+        this.sendRequest({
+            sendTeamMessage: {
+                message: message,
+            },
+        }, callback);
+    }
+
+    /**
+     * Get info for an Entity
+     * @param entityId the id of the entity to get info of
+     * @param callback
+     */
+    getEntityInfo(entityId, callback) {
+        this.sendRequest({
+            entityId: entityId,
+            getEntityInfo: {
+
+            },
+        }, callback);
+    }
+
+    /**
+     * Get the Map
+     */
+    getMap(callback) {
+        this.sendRequest({
+            getMap: {
+
+            },
+        }, callback);
+    }
+    
+    /**
+     * Get the ingame time
+    */
+    getTime(callback) {
+        this.sendRequest({
+            getTime: {
+
+            },
+        }, callback);
+    }
+
+    /**
+     * Get all map markers
+     */
+    getMapMarkers(callback) {
+        this.sendRequest({
+            getMapMarkers: {
+
+            },
+        }, callback);
+    }
+
+    /**
+     * Get the server info
+     */
+    getInfo(callback) {
+        this.sendRequest({
+            getInfo: {
+
+            },
+        }, callback);
+    }
+
+    /**
+     * Get team info
+     */
+    getTeamInfo(callback) {
+        this.sendRequest({
+            getTeamInfo: {
+
+            },
+        }, callback);
+    }
+
+    /**
+     * Subscribes to a Camera
+     * @param identifier Camera Identifier, such as OILRIG1 (or custom name)
+     * @param callback
+     */
+    subscribeToCamera(identifier, callback) {
+        this.sendRequest({
+            cameraSubscribe: {
+                cameraId: identifier,
+            },
+        }, callback);
+    }
+
+    /**
+     * Unsubscribes from a Camera
+     * @param callback
+     */
+    unsubscribeFromCamera(callback) {
+        this.sendRequest({
+            cameraUnsubscribe: {
+
+            }
+        }, callback)
+    }
+
+    /**
+     * Sends camera input to the server (mouse movement)
+     * @param buttons The buttons that are currently pressed
+     * @param x The x delta of the mouse movement
+     * @param y The y delta of the mouse movement
+     * @param callback
+     */
+    sendCameraInput(buttons, x, y, callback) {
+        this.sendRequest({
+            cameraInput: {
+                buttons: buttons,
+                mouseDelta: {
+                    x: x,
+                    y: y,
+                }
+            },
+        }, callback);
+    }
+
+    /**
+     * Get a camera instance for controlling CCTV Cameras, PTZ Cameras and  Auto Turrets
+     * @param identifier Camera Identifier, such as DOME1, OILRIG1L1, (or a custom camera id)
+     * @returns {Camera}
+     */
+    getCamera(identifier) {
+        return new Camera(this, identifier);
+    }
+
+}
+
+module.exports = RustPlus;