@four-leaf-studios/rl-overlay-tool v1.0.1

WebSocket Module Documentation

This module provides functionality to connect to a WebSocket server, handle incoming data, and automatically manage reconnections. It includes methods to convert data from Rocket League's SOS plugin into a custom format and to listen to WebSocket events.

Functions

convertData(data, mapping)

Converts data based on a given mapping object.

• Parameters:
  • data (Object): The data to be converted.
  • mapping (Object): The mapping object defining the conversion.
• Returns:
  • Object: Converted data.

convertSosData(sosData, mapping)

Converts Rocket League SOS plugin data to a custom format.

• Parameters:
  • sosData (Object): Data from Rocket League's SOS plugin.
  • mapping (Object): Custom data mapping.
• Returns:
  • Object: Custom formatted data.

connectToWebSocket(wsUrl, onData, config)

Attempts to connect to the WebSocket server, handling automatic reconnection.

• Parameters:
  • wsUrl (string): The WebSocket server URL.
  • onData (function): Callback function to handle incoming data.
  • config (Object): Configuration object.
    • mapping (Object): Mapping object for data conversion.
    • eventFilters (Array): List of events to filter.
    • errorHandling (Object): Error handling configuration.
      • retryInterval (number): Interval between reconnection attempts.
      • maxRetries (number): Maximum number of reconnection attempts.
    • logging (boolean): Enable or disable logging.
    • dataTransformation (function): Function to transform data before passing to the callback.
    • callbacks (Object): Callback functions for connection events.
      • onConnect (function): Function to call on connection.
      • onDisconnect (function): Function to call on disconnection.
    • reconnect (function): Function returning a boolean indicating whether to attempt reconnection.
    • enable (function): Function returning a boolean indicating whether to enable the connection.

listenToWebSocket(wsUrl, onData, config)

Listens to the WebSocket server and streams data to the client.

• Parameters:
  • wsUrl (string): The WebSocket server URL.
  • onData (function): Callback function to handle incoming data.
  • config (Object): Configuration object (same as connectToWebSocket).
• Returns:
  • function: Function to stop the WebSocket connection.

listenToWebSocketOnPort(onData, config)

Listens to the WebSocket server on a specific port and streams data to the client.

• Parameters:
  • onData (function): Callback function to handle incoming data.
  • config (Object): Configuration object (same as connectToWebSocket).
• Returns:
  • function: Function to stop the WebSocket connection.

Configuration Fields

• mapping (Object): Defines how to convert the incoming SOS plugin data into a custom format.

  • event (string or function): Maps the event type.
  • game (Object): Maps the game data fields.
    • arena (string or function): Maps the arena field.
    • ball (string or function): Maps the ball field.
    • teams (string or function): Maps the teams field.
    • time (string or function): Maps the time field.
    • winner (string or function): Maps the winner field.
  • players (function): Maps the players' data.

• eventFilters (Array): Specifies which events to listen for. Only these events will trigger the onData callback.

• errorHandling (Object): Configuration for handling connection errors.

  • retryInterval (number): Time in milliseconds between reconnection attempts.
  • maxRetries (number): Maximum number of reconnection attempts before giving up.

• logging (boolean): Enables or disables logging of connection events and errors.

• dataTransformation (function): A function to transform the data before passing it to the onData callback.

• callbacks (Object): Defines callback functions for connection events.

  • onConnect (function): Called when a connection is established.
  • onDisconnect (function): Called when a connection is closed.

• reconnect (function): A function that returns a boolean indicating whether to attempt reconnection. This can be used to control reconnection logic dynamically.

• enable (function): A function that returns a boolean indicating whether the connection should be enabled. This can be used to enable or disable the connection dynamically.

Example Usage

const { listenToWebSocketOnPort } = require("rl-overlay-tool");
const config = {
  mapping: {
    event: "event",
    game: {
      arena: (data) => data?.arena,
      ball: (data) => data?.ball,
      teams: (data) => data?.teams,
      time: (data) => data?.time_seconds,
      winner: (data) => data?.winner,
    },
    players: (data) =>
      data.players
        ? Object.keys(data.players).map((playerId) => {
            const player = data.players[playerId];
            return {
              id: player.id,
              name: player.name,
              team: player.team,
              score: player.score,
              goals: player.goals,
              assists: player.assists,
              saves: player.saves,
              shots: player.shots,
            };
          })
        : [],
  },
  eventFilters: [
    "sos:version",
    "game:match_created",
    "game:initialized",
    "game:pre_countdown_begin",
    "game:post_countdown_begin",
    "game:update_state",
    "game:ball_hit",
    "game:statfeed_event",
    "game:goal_scored",
    "game:replay_start",
    "game:replay_will_end",
    "game:replay_end",
    "game:match_ended",
    "game:podium_start",
    "game:match_destroyed",
  ],
  errorHandling: {
    retryInterval: 1000,
    maxRetries: 5,
  },
  logging: true,
  connectionSettings: {
    url: "ws://localhost",
    port: 49122,
  },
  dataTransformation: (data) => {
    if (data.players) {
      data.players.forEach((player) => {
        player.displayName = `${player.name} (${player.team})`;
      });
    }
    return data;
  },
  callbacks: {
    onConnect: () => console.log("Connected to WebSocket server"),
    onDisconnect: () => console.log("Disconnected from WebSocket server"),
  },
  reconnect: () => true,
  enable: () => true,
};

let stopWebSocket;

// Function to start listening to the WebSocket server
function startListening() {
  stopWebSocket = listenToWebSocketOnPort((data) => {
    console.log("Received data:", data);
  }, config);
  console.log("Started listening to the WebSocket server on port 49122");
}

// Function to stop listening to the WebSocket server
function stopListening() {
  if (stopWebSocket) {
    stopWebSocket();
    console.log("Stopped listening to the WebSocket server");
  }
}

// Start listening
startListening();

// Stop listening after some time (e.g., 10 seconds)
setTimeout(() => {
  stopListening();
}, 10000);