Move2win/SquadJS

SquadJS

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

Git
Node.js (Current) - Download
Yarn (Version 1.22.0+) - Download
Some plugins may have additional requirements.

Installation

Clone the repository: git clone https://github.com/Thomas-Smyth/SquadJS
Install the dependencies: yarn install
Configure the config.json file. See below for more details.
Start SquadJS: node index.js.

Note - We use Yarn Workspaces so npm install will not work and will break stuff!

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.

Squad Layer Filter

Connects to a filtered list of Squad layers and filters them either by an "initial filter" or an "active filter" that depends on current server information, e.g. player count.

"layerFilter": {
  "type": "buildPoolFromFilter",
  "filter": {
    "whitelistedLayers": null,
    "blacklistedLayers": null,
    "whitelistedMaps": null,
    "blacklistedMaps": null,
    "whitelistedGamemodes": null,
    "blacklistedGamemodes": [
      "Training"
    ],
    "flagCountMin": null,
    "flagCountMax": null,
    "hasCommander": null,
    "hasTanks": null,
    "hasHelicopters": null
  },
  "activeLayerFilter": {
    "historyResetTime": 18000000,
    "layerHistoryTolerance": 8,
    "mapHistoryTolerance": 4,
    "gamemodeHistoryTolerance": {
      "Invasion": 4
    },
    "gamemodeRepetitiveTolerance": {
      "Invasion": 4
    },
    "playerCountComplianceEnabled": true,
    "factionComplianceEnabled": true,
    "factionHistoryTolerance": {
      "RUS": 4
    },
    "factionRepetitiveTolerance": {
      "RUS": 4
    }
  }
},

type - The type of filter builder to use. filter will depend on this type.
- buildPoolFromFilter - Builds the Squad layers list from a list of filters. An example filter with default values for this type is show above.
  - whitelistedLayers - List of layers to consider.
  - blacklistLayers - List of layers to not consider.
  - whitelistedMaps - List of maps to consider.
  - blacklistedMaps - List of maps to not consider.
  - whitelistedGamemodes - List of gamemodes to consider.
  - blacklistedGamemodes - List of gamemodes to not consider.
  - flagCountMin - Minimum number of flags the layer may have.
  - flagCountMax - Maximum number of flags the layer may have.
  - hasCommander - Layer must/most not have a commander. null for either.
  - hasTanks - Layer must/most not have a tanks. null for either.
  - hasHelicopters - Layer must/most not have a helicopters. null for either.
- buildPoolFromFile - Builds the Squad layers list from a Squad layer config file. filter should be the filename of the config file.
- buildPoolFromLayerNames - Builds the Squad layers list from a list of layers. filter should be a list of layers, e.g. "filter": ["Sumari AAS v1", "Fool's Road AAS v1"].
filter - Described above.
activeLayerFilter - Filters layers live as server information updates, e.g. if the player count exceeds a certain amount a layer may no longer be in the filter.
- historyResetTime - After this number of milliseconds the layer history is no longer considered.
- layerHistoryTolerance - A layer can only be played again after this number of layers.
- mapHistoryTolerance - A map can only be played again after this number of layers.
- gamemodeHistoryTolerance - A gamemode can only be played again after this number of layers. Gamemodes can be specified individually inside the object. If they are not listed then the filter is not applied.
- gamemodeRepetitiveTolerance - A gamemode can only be played this number of times in a row. Gamemodes can be specified individually inside the object. If they are not listed then the filter is not applied.
- playerCountComplianceEnabled - Filter layers by player count.
- factionComplianceEnabled - Filter layers so that a team cannot play the same faction twice in a row.
- factionHistoryTolerance - A faction can only be played again after this number of layers. Factions can be specified individually inside the object. If they are not listed then the filter is not applied.
- factionRepetitiveTolerance - A faction can only be played this number of times in a row. Factions can be specified individually inside the object. If they are not listed then the filter is not applied.

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

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
```

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

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"
]
```

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
```

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"
]

pingDelay

Description

Cooldown for pings in milliseconds.

Default
```
60000
```
color

Description

The color of the embed.

Default
```
16761867
```

DiscordServerStatus

The DiscordServerStatus plugin updates a message in Discord with current server information, e.g. player count.

Options

discordClient (Required)

Description

Discord connector name.

Default
```
discord
```
messageIDs (Required)

Description

ID of messages to update.

Default
```
[]
```

Example

[
  {
    "channelID": "667741905228136459",
    "messageID": "766688383043895387"
  }
]

updateInterval

Description

How frequently to update the status in Discord.

Default
```
60000
```
disableStatus

Description

Disable the bot status.

Default
```
false
```

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 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
```

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"
]

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
```

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
```
disableSCBL

Description

Disable Squad Community Ban List information.

Default
```
false
```

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

Description

"Live" message to display.

Default
```
Live!
```

AutoTKWarn

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

Options

message

Description

The message to warn players with.

Default
```
Please apologise for ALL TKs in ALL chat!
```

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 (NOT YET WORKING WITH V2):

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
```

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
```

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": []
  }
]
```

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
```

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
```

TeamRandomizer

The TeamRandomizer can be used to randomize teams. It's great for destroying clan stacks or for social events. It can be run by typing, by default, !randomize into in-game admin chat

Options

command

Description

The command used to randomize the teams.

Default
```
randomize
```

SCBLInfo

The SCBLInfo plugin alerts admins when a harmful player is detected joining their server based on data from the Squad 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 Squad Community Ban List's FAQ

Default
```
6
```

Statement on Accuracy

Some of the information SquadJS collects from Squad servers was never intended or designed to be collected. As a result, it is impossible for any framework to collect the same information with 100% accuracy. SquadJS aims to get as close as possible to that figure, however, it acknowledges that this is not possible in some specific scenarios.

Below is a list of scenarios we know may cause some information to be inaccurate:

Use of Realtime Server and Player Information - We update server and player information periodically every 30 seconds (by default) or when we know that it requires an update. As a result, some information about the server or players may be up to 30 seconds out of date.
SquadJS Restarts - If SquadJS is started during an active Squad game some information will be lost or not collected correctly:
- The current state of players will be lost. For example, if a player was wounded prior to the bot starting and then is revived/gives up after the bot is started information regarding who originally wounded them will not be known.
- The accurate collection of some server log events will not occur. SquadJS collects players' "suffix" name, i.e. their Steam name without the clan tag added via the game settings, when they join the server and uses this to identify them in certain logs that do not include their full name. As a result, for players connecting prior to SquadJS starting some log events associated with their actions will show the player as null. We aim to implement a solution to attempt to recover players' suffix names when this occurs, but the accuracy of correctly identifying players will be decreased.
Duplicated Player Names - If two or more players have the same name or suffix name (see above) then SquadJS will be unable to identify them in the logs. When this occurs event logs will show the player as null. Be on the watch for groups of players who try to abuse this in order to TK or complete other malicious actions without being detected by SquadJS plugins.

Credits

SquadJS would not be possible without the support of so many individuals and organisations. Our thanks goes out to:

SquadJS's contributors
Thomas Smyth's GitHub sponsors
subtlerod for proposing the initial log parsing idea, helping to design the log parsing process and for providing multiple servers to test with.
Fourleaf, Mex, various members of ToG / ToG-L and others that helped to stage logs and participate in small scale tests.
Various Squad servers/communities for participating in larger scale tests and for providing feedback on plugins.
Everyone in the Squad RCON Discord and others who have submitted bug reports, suggestions, feedback and provided logs.

License

Boost Software License - Version 1.0 - August 17th, 2003

Copyright (c) 2020 Thomas Smyth

Permission is hereby granted, free of charge, to any person or organization
obtaining a copy of the software and accompanying documentation covered by
this license (the "Software") to use, reproduce, display, distribute,
execute, and transmit the Software, and to prepare derivative works of the
Software, and to permit third-parties to whom the Software is furnished to
do so, all subject to the following:

The copyright notices in the Software and this entire statement, including
the above license grant, this restriction and the following disclaimer,
must be included in all copies of the Software, in whole or in part, and
all derivative works of the Software, unless such copies or derivative
works are solely in the form of machine-executable object code generated by
a source language processor.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

SquadJS

About

Using SquadJS

Prerequisites

Installation

Configuring SquadJS

Server Configuration

Connector Configuration

Squad Layer Filter

Discord

Databases

Plugin Configuration

Console Output Configuration

Plugins

DiscordPlaceholder

Options

discordClient (Required)

Description

Default

command

Description

Default

DiscordSubsystemRestarter

Options

discordClient (Required)

Description

Default

role (Required)

Description

Default

Example

DiscordChat

Options

discordClient (Required)

Description

Default

channelID (Required)

Description

Default

Example

chatColors

Description

Default

Example

color

Description

Default

ignoreChats

Description

Default

DiscordAdminBroadcast

Options

discordClient (Required)

Description

Default

channelID (Required)

Description

Default

Example

color

Description

Default

DiscordAdminRequest

Options

discordClient (Required)

Description

Default

channelID (Required)

Description

Default

Example

ignoreChats

Description

Default

Example

ignorePhrases

Description

Default

Example

command