Skip to content

Team-Silver-Sphere/SquadJS

Repository files navigation

Logo Logo

SquadJS

GitHub release GitHub contributors GitHub release


GitHub issues GitHub pull requests GitHub issues Discord



About

SquadJS is a scripting framework, designed for Squad servers, that aims to handle all communication and data collection to and from the servers. Using SquadJS as the base to any of your scripting projects allows you to easily write complex plugins without having to worry about the hassle of RCON or log parsing. However, for your convenience SquadJS comes shipped with multiple plugins already built for you allowing you to experience the power of SquadJS right away.


Using SquadJS

SquadJS relies on being able to access the Squad server log directory in order to parse logs live to collect information. Thus, SquadJS must be hosted on the same server box as your Squad server or be connected to your Squad server via FTP.

Prerequisites

Installation

  1. Download SquadJS and unzip the download.
  2. Open the unzipped folder in your terminal.
  3. Install the dependencies by running yarn install in your terminal. Due to the use of Yarn Workspaces it is important to use yarn install and not npm install as this will not work and will break stuff.
  4. Configure the config.json file. See below for more details.
  5. Start SquadJS by running node index.js in your terminal.

Note - If you are interested in testing versions of SquadJS not yet released please download/clone the master branch. Please also see here for more information on our versions and release procedures.


Configuring SquadJS

SquadJS can be configured via a JSON configuration file which, by default, is located in the SquadJS and is named config.json.

The config file needs to be valid JSON syntax. If an error is thrown saying the config cannot be parsed then try putting the config into a JSON syntax checker (there's plenty to choose from that can be found via Google).

Server

Server Configuration

The following section of the configuration contains information about your Squad server.

"server": {
  "id": 1,
  "host": "xxx.xxx.xxx.xxx",
  "queryPort": 27165,
  "rconPort": 21114,
  "rconPassword": "password",
  "logReaderMode": "tail",
  "logDir": "C:/path/to/squad/log/folder",
  "ftp":{
    "port": 21,
    "user": "FTP Username",
    "password": "FTP Password",
    "useListForSize": false
  },
  "adminLists": [
    {
      "type": "local",
      "source": "C:/Users/Administrator/Desktop/Servers/sq_arty_party/SquadGame/ServerConfig/Admins.cfg",
    },
    {
      "type": "remote",
      "source": "http://yourWebsite.com/Server1/Admins.cfg",
    }
  ]
},
  • id - An integer ID to uniquely identify the server.

  • host - The IP of the server.

  • queryPort - The query port of the server.

  • rconPort - The RCON port of the server.

  • rconPassword - The RCON password of the server.

  • logReaderMode - tail will read from a local log file. ftp will read from a remote log file using the FTP protocol.

  • logDir - The folder where your Squad logs are saved. Most likely will be C:/servers/squad_server/SquadGame/Saved/Logs.

  • ftp:port - The FTP port of the server. Only required for ftp logReaderMode.

  • ftp:user - The FTP user of the server. Only required for ftp logReaderMode.

  • ftp:password - The FTP password of the server. Only required for ftp logReaderMode.

  • adminLists - Sources for identifying an admins on the server, either remote or local.


Connectors

Connector Configuration

Connectors allow SquadJS to communicate with external resources.

"connectors": {
  "discord": "Discord Login Token",
},

Connectors should be named, for example the above is named discord, and should have the associated config against it. Configs can be specified by name in plugin options. Should a connector not be needed by any plugin then the default values can be left or you can remove it from your config file.

See below for more details on connectors and their associated config.

Discord

Connects to Discord via discord.js.

"discord": "Discord Login Token",

Requires a Discord bot login token.

Databases

SquadJS uses Sequelize to connect and use a wide range of SQL databases.

The connector should be configured using any of Sequelize's single argument configuration options.

For example:

"mysql": "mysql://user:pass@example.com:5432/dbname"

or:

"sqlite": {
    "dialect": "sqlite",
    "storage": "path/to/database.sqlite"
}

See Sequelize's documentation for more details.


Plugins

Plugin Configuration

The plugins section in your config file lists all plugins built into SquadJS

  "plugins": [
    {
      "plugin": "auto-tk-warn",
      "disabled": false,
      "message": "Please apologise for ALL TKs in ALL chat!"
    }
  ]

The disabled field can be toggled between true/ false to enabled/disable the plugin.

Plugin options are also specified. A full list of plugin options can be seen below.


Verboseness

Console Output Configuration

The logger section configures how verbose a module of SquadJS will be as well as the displayed color.

  "logger": {
    "verboseness": {
      "SquadServer": 1,
      "LogParser": 1,
      "RCON": 1
    },
    "colors": {
      "SquadServer": "yellowBright",
      "SquadServerFactory": "yellowBright",
      "LogParser": "blueBright",
      "RCON": "redBright"
    }
  }

The larger the number set in the verboseness section for a specified module the more it will print to the console.



Plugins

The following is a list of plugins built into SquadJS, you can click their title for more information:

Interested in creating your own plugin? See more here

AutoKickUnassigned

AutoKickUnassigned

The AutoKickUnassigned plugin will automatically kick players that are not in a squad after a specified ammount of time.

Options

  • warningMessage

    Description

    Message SquadJS will send to players warning them they will be kicked

    Default
    Join a squad, you are unassigned and will be kicked
  • kickMessage

    Description

    Message to send to players when they are kicked

    Default
    Unassigned - automatically removed
  • frequencyOfWarnings

    Description

    How often in Seconds should we warn the player about being unassigned?

    Default
    30
  • unassignedTimer

    Description

    How long in Seconds to wait before a unassigned player is kicked

    Default
    360
  • playerThreshold

    Description

    Player count required for AutoKick to start kicking players, set to -1 to disable

    Default
    93
  • roundStartDelay

    Description

    Time delay in Seconds from start of the round before AutoKick starts kicking again

    Default
    900
  • ignoreAdmins

    Description

    • true: Admins will NOT be kicked
    • false: Admins WILL be kicked

    Default
    false
  • ignoreWhitelist

    Description

    • true: Reserve slot players will NOT be kicked
    • false: Reserve slot players WILL be kicked

    Default
    false
AutoTKWarn

AutoTKWarn

The AutoTkWarn plugin will automatically warn players with a message when they teamkill.

Options

  • attackerMessage

    Description

    The message to warn attacking players with.

    Default
    Please apologise for ALL TKs in ALL chat!
  • victimMessage

    Description

    The message that will be sent to the victim.

    Default
    null
CBLInfo

CBLInfo

The CBLInfo plugin alerts admins when a harmful player is detected joining their server based on data from the Community Ban List.

Options

  • discordClient (Required)

    Description

    Discord connector name.

    Default
    discord
  • channelID (Required)

    Description

    The ID of the channel to alert admins through.

    Default
  • Example
    667741905228136459
  • threshold

    Description

    Admins will be alerted when a player has this or more reputation points. For more information on reputation points, see the Community Ban List's FAQ

    Default
    6
ChatCommands

ChatCommands

The ChatCommands plugin can be configured to make chat commands that broadcast or warn the caller with present messages.

Options

  • commands

    Description

    An array of objects containing the following properties:

    • command - The command that initiates the message.
    • type - Either warn or broadcast.
    • response - The message to respond with.
    • ignoreChats - A list of chats to ignore the commands in. Use this to limit it to admins.

    Default
    [
      {
        "command": "squadjs",
        "type": "warn",
        "response": "This server is powered by SquadJS.",
        "ignoreChats": []
      }
    ]
DBLog

DBLog

The mysql-log plugin will log various server statistics and events to a database. This is great for server performance monitoring and/or player stat tracking.

Grafana:

  • Grafana is a cool way of viewing server statistics stored in the database.
  • Install Grafana.
  • Add your database as a datasource named SquadJS.
  • Import the SquadJS Dashboard to get a preconfigured MySQL only Grafana dashboard.
  • Install any missing Grafana plugins.

Options

  • database (Required)

    Description

    The Sequelize connector to log server information to.

    Default
    mysql
  • overrideServerID

    Description

    A overridden server ID.

    Default
    null
DiscordAdminBroadcast

DiscordAdminBroadcast

The DiscordAdminBroadcast plugin will send a copy of admin broadcasts made in game to a Discord channel.

Options

  • discordClient (Required)

    Description

    Discord connector name.

    Default
    discord
  • channelID (Required)

    Description

    The ID of the channel to log admin broadcasts to.

    Default
  • Example
    667741905228136459
  • color

    Description

    The color of the embed.

    Default
    16761867
DiscordAdminCamLogs

DiscordAdminCamLogs

The DiscordAdminCamLogs plugin will log in game admin camera usage to a Discord channel.

Options

  • discordClient (Required)

    Description

    Discord connector name.

    Default
    discord
  • channelID (Required)

    Description

    The ID of the channel to log admin camera usage to.

    Default
  • Example
    667741905228136459
  • color

    Description

    The color of the embed.

    Default
    16761867
DiscordAdminRequest

DiscordAdminRequest

The DiscordAdminRequest plugin will ping admins in a Discord channel when a player requests an admin via the !admin command in in-game chat.

Options

  • discordClient (Required)

    Description

    Discord connector name.

    Default
    discord
  • channelID (Required)

    Description

    The ID of the channel to log admin broadcasts to.

    Default
  • Example
    667741905228136459
  • ignoreChats

    Description

    A list of chat names to ignore.

    Default
    []
  • Example
    [
      "ChatSquad"
    ]
  • ignorePhrases

    Description

    A list of phrases to ignore.

    Default
    []
  • Example
    [
      "switch"
    ]
  • command

    Description

    The command that calls an admin.

    Default
    admin
  • pingGroups

    Description

    A list of Discord role IDs to ping.

    Default
    []
  • Example
    [
      "500455137626554379"
    ]
  • pingHere

    Description

    Ping @here. Great if Admin Requests are posted to a Squad Admin ONLY channel, allows pinging only Online Admins.

    Default
    false
  • pingDelay

    Description

    Cooldown for pings in milliseconds.

    Default
    60000
  • color

    Description

    The color of the embed.

    Default
    16761867
  • warnInGameAdmins

    Description

    Should in-game admins be warned after a players uses the command and should we tell how much admins are active in-game right now.

    Default
    false
  • showInGameAdmins

    Description

    Should players know how much in-game admins there are active/online?

    Default
    true
DiscordChat

DiscordChat

The DiscordChat plugin will log in-game chat to a Discord channel.

Options

  • discordClient (Required)

    Description

    Discord connector name.

    Default
    discord
  • channelID (Required)

    Description

    The ID of the channel to log admin broadcasts to.

    Default
  • Example
    667741905228136459
  • chatColors

    Description

    The color of the embed for each chat.

    Default
    {}
  • Example
    {
      "ChatAll": 16761867
    }
  • color

    Description

    The color of the embed.

    Default
    16761867
  • ignoreChats

    Description

    A list of chat names to ignore.

    Default
    [
      "ChatSquad"
    ]
DiscordDebug

DiscordDebug

The DiscordDebug plugin can be used to help debug SquadJS by dumping SquadJS events to a Discord channel.

Options

  • discordClient (Required)

    Description

    Discord connector name.

    Default
    discord
  • channelID (Required)

    Description

    The ID of the channel to log events to.

    Default
  • Example
    667741905228136459
  • events (Required)

    Description

    A list of events to dump.

    Default
    []
  • Example
    [
      "PLAYER_DIED"
    ]
DiscordFOBHABExplosionDamage

DiscordFOBHABExplosionDamage

The DiscordFOBHABExplosionDamage plugin logs damage done to FOBs and HABs by explosions to help identify engineers blowing up friendly FOBs and HABs.

Options

  • discordClient (Required)

    Description

    Discord connector name.

    Default
    discord
  • channelID (Required)

    Description

    The ID of the channel to log FOB/HAB explosion damage to.

    Default
  • Example
    667741905228136459
  • color

    Description

    The color of the embeds.

    Default
    16761867
DiscordKillFeed

DiscordKillFeed

The DiscordKillFeed plugin logs all wounds and related information to a Discord channel for admins to review.

Options

  • discordClient (Required)

    Description

    Discord connector name.

    Default
    discord
  • channelID (Required)

    Description

    The ID of the channel to log teamkills to.

    Default
  • Example
    667741905228136459
  • color

    Description

    The color of the embeds.

    Default
    16761867
  • disableCBL

    Description

    Disable Community Ban List information.

    Default
    false
DiscordPlaceholder

DiscordPlaceholder

The DiscordPlaceholder plugin allows you to make your bot create placeholder messages that can be used when configuring other plugins.

Options

  • discordClient (Required)

    Description

    Discord connector name.

    Default
    discord
  • command

    Description

    Command to create Discord placeholder.

    Default
    !placeholder
  • channelID (Required)

    Description

    The bot will only answer with a placeholder on this channel

    Default
DiscordRcon

DiscordRcon

The DiscordRcon plugin allows a specified Discord channel to be used as a RCON console to run RCON commands.

Options

  • discordClient (Required)

    Description

    Discord connector name.

    Default
    discord
  • channelID (Required)

    Description

    ID of channel to turn into RCON console.

    Default
  • Example
    667741905228136459
  • permissions

    Description

    • Dictionary of roles and a list of the permissions they are allowed to use.
    • If dictionary is empty ({}) permissions will be disabled
    • A list of available RCON commands can be found here https://squad.gamepedia.com/Server_Administration#Admin_Console_Commands.

    Default
    {}
  • Example
    {
      "123456789123456789": [
        "AdminBroadcast",
        "AdminForceTeamChange",
        "AdminDemoteCommander"
      ]
    }
  • prependAdminNameInBroadcast

    Description

    Prepend admin names when making announcements.

    Default
    false
DiscordRoundWinner

DiscordRoundWinner

The DiscordRoundWinner plugin will send the round winner to a Discord channel.

Options

  • discordClient (Required)

    Description

    Discord connector name.

    Default
    discord
  • channelID (Required)

    Description

    The ID of the channel to log admin broadcasts to.

    Default
  • Example
    667741905228136459
  • color

    Description

    The color of the embed.

    Default
    16761867
DiscordRoundEnded

DiscordRoundEnded

The DiscordRoundEnded plugin will send the round winner to a Discord channel.

Options

  • discordClient (Required)

    Description

    Discord connector name.

    Default
    discord
  • channelID (Required)

    Description

    The ID of the channel to log round end events to.

    Default
  • Example
    667741905228136459
  • color

    Description

    The color of the embed.

    Default
    16761867
DiscordServerStatus

DiscordServerStatus

The DiscordServerStatus plugin can be used to get the server status in Discord.

Options

  • discordClient (Required)

    Description

    Discord connector name.

    Default
    discord
  • messageStore (Required)

    Description

    Sequelize connector name.

    Default
    sqlite
  • command

    Description

    Command name to get message.

    Default
    !status
  • disableSubscriptions

    Description

    Whether to allow messages to be subscribed to automatic updates.

    Default
    false
  • updateInterval

    Description

    How frequently to update the time in Discord.

    Default
    60000
  • setBotStatus

    Description

    Whether to update the bot's status with server information.

    Default
    true
DiscordSquadCreated

DiscordSquadCreated

The SquadCreated plugin will log Squad Creation events to a Discord channel.

Options

  • discordClient (Required)

    Description

    Discord connector name.

    Default
    discord
  • channelID (Required)

    Description

    The ID of the channel to log Squad Creation events to.

    Default
  • Example
    667741905228136459
  • color

    Description

    The color of the embed.

    Default
    16761867
  • useEmbed

    Description

    Send message as Embed

    Default
    true
DiscordSubsystemRestarter

DiscordSubsystemRestarter

The DiscordSubSystemRestarter plugin allows you to manually restart SquadJS subsystems in case an issues arises with them.

  • !squadjs restartsubsystem rcon
  • !squadjs restartsubsystem logparser

Options

  • discordClient (Required)

    Description

    Discord connector name.

    Default
    discord
  • role (Required)

    Description

    ID of role required to run the sub system restart commands.

    Default
  • Example
    667741905228136459
DiscordTeamkill

DiscordTeamkill

The DiscordTeamkill plugin logs teamkills and related information to a Discord channel for admins to review.

Options

  • discordClient (Required)

    Description

    Discord connector name.

    Default
    discord
  • channelID (Required)

    Description

    The ID of the channel to log teamkills to.

    Default
  • Example
    667741905228136459
  • color

    Description

    The color of the embeds.

    Default
    16761867
  • disableCBL

    Description

    Disable Community Ban List information.

    Default
    false
FogOfWar

FogOfWar

The FogOfWar plugin can be used to automate setting fog of war mode.

Options

  • mode

    Description

    Fog of war mode to set.

    Default
    1
  • delay

    Description

    Delay before setting fog of war mode.

    Default
    10000
IntervalledBroadcasts

IntervalledBroadcasts

The IntervalledBroadcasts plugin allows you to set broadcasts, which will be broadcasted at preset intervals

Options

  • broadcasts

    Description

    Messages to broadcast.

    Default
    []
  • Example
    [
      "This server is powered by SquadJS."
    ]
  • interval

    Description

    Frequency of the broadcasts in milliseconds.

    Default
    300000
SeedingMode

SeedingMode

The SeedingMode plugin broadcasts seeding rule messages to players at regular intervals when the server is below a specified player count. It can also be configured to display "Live" messages when the server goes live.

Options

  • interval

    Description

    Frequency of seeding messages in milliseconds.

    Default
    150000
  • seedingThreshold

    Description

    Player count required for server not to be in seeding mode.

    Default
    50
  • seedingMessage

    Description

    Seeding message to display.

    Default
    Seeding Rules Active! Fight only over the middle flags! No FOB Hunting!
  • liveEnabled

    Description

    Enable "Live" messages for when the server goes live.

    Default
    true
  • liveThreshold

    Description

    Player count required for "Live" messages to not bee displayed.

    Default
    52
  • liveMessage