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.
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.
- Git
- Node.js (18.x) - Download
- Yarn (Version 1.22.0+) - Download
- Some plugins may have additional requirements.
- Download SquadJS and unzip the download.
- Open the unzipped folder in your terminal.
- Install the dependencies by running
yarn installin your terminal. Due to the use of Yarn Workspaces it is important to useyarn installand notnpm installas this will not work and will break stuff. - Configure the
config.jsonfile. See below for more details. - Start SquadJS by running
node index.jsin 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.
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
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"
},
"sftp": {
"host": "xxx.xxx.xxx.xxx",
"port": 21,
"username": "SFTP Username",
"password": "SFTP Password"
},
"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",
},
{
"type": "ftp",
"source": "ftp://<user>:<password>@<host>:<port>/<url-path>",
}
]
},-
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-tailwill read from a local log file.ftpwill read from a remote log file using the FTP protocol. -
logDir- The folder where your Squad logs are saved. Most likely will beC:/servers/squad_server/SquadGame/Saved/Logs. -
ftp:port- The FTP port of the server. Only required forftplogReaderMode. -
ftp:user- The FTP user of the server. Only required forftplogReaderMode. -
ftp:password- The FTP password of the server. Only required forftplogReaderMode. -
adminLists- Sources for identifying an admins on the server, either remote or local.
Connectors
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.
Connects to Discord via discord.js.
"discord": "Discord Login Token",Requires a Discord bot login token.
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
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
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.
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
The AutoKickUnassigned plugin will automatically kick players that are not in a squad after a specified ammount of time.
-
Message SquadJS will send to players warning them they will be kicked
Join a squad, you are unassigned and will be kicked -
Message to send to players when they are kicked
Unassigned - automatically removed -
How often in Seconds should we warn the player about being unassigned?
30 -
How long in Seconds to wait before a unassigned player is kicked
360 -
Player count required for AutoKick to start kicking players, set to -1 to disable
93 -
Time delay in Seconds from start of the round before AutoKick starts kicking again
900 -
true: Admins will NOT be kickedfalse: Admins WILL be kicked
false -
true: Reserve slot players will NOT be kickedfalse: Reserve slot players WILL be kicked
false
AutoTKWarn
The AutoTkWarn plugin will automatically warn players with a message when they teamkill.
-
The message to warn attacking players with.
Please apologise for ALL TKs in ALL chat! -
The message that will be sent to the victim.
null
CBLInfo
The CBLInfo plugin alerts admins when a harmful player is detected joining their server based on data from the Community Ban List.
-
Discord connector name.
discord -
The ID of the channel to alert admins through.
-
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
6
667741905228136459ChatCommands
The ChatCommands plugin can be configured to make chat commands that broadcast or warn the caller with present messages.
-
An array of objects containing the following properties:
command- The command that initiates the message.type- Eitherwarnorbroadcast.response- The message to respond with.ignoreChats- A list of chats to ignore the commands in. Use this to limit it to admins.
[ { "command": "squadjs", "type": "warn", "response": "This server is powered by SquadJS.", "ignoreChats": [] } ]
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.
-
The Sequelize connector to log server information to.
mysql -
A overridden server ID.
null
DiscordAdminBroadcast
The DiscordAdminBroadcast plugin will send a copy of admin broadcasts made in game to a Discord channel.
-
Discord connector name.
discord -
The ID of the channel to log admin broadcasts to.
-
The color of the embed.
16761867
667741905228136459DiscordAdminCamLogs
The DiscordAdminCamLogs plugin will log in game admin camera usage to a Discord channel.
-
Discord connector name.
discord -
The ID of the channel to log admin camera usage to.
-
The color of the embed.
16761867
667741905228136459DiscordAdminRequest
The DiscordAdminRequest plugin will ping admins in a Discord channel when a player requests an admin via the !admin command in in-game chat.
-
Discord connector name.
discord -
The ID of the channel to log admin broadcasts to.
-
A list of chat names to ignore.
[] -
A list of phrases to ignore.
[] -
The command that calls an admin.
admin -
A list of Discord role IDs to ping.
[] -
Ping @here. Great if Admin Requests are posted to a Squad Admin ONLY channel, allows pinging only Online Admins.
false -
Cooldown for pings in milliseconds.
60000 -
The color of the embed.
16761867 -
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.
false -
Should players know how much in-game admins there are active/online?
true
667741905228136459[
"ChatSquad"
][
"switch"
][
"500455137626554379"
]DiscordChat
The DiscordChat plugin will log in-game chat to a Discord channel.
-
Discord connector name.
discord -
The ID of the channel to log admin broadcasts to.
-
The color of the embed for each chat.
{} -
The color of the embed.
16761867 -
A list of chat names to ignore.
[ "ChatSquad" ]
667741905228136459{
"ChatAll": 16761867
}DiscordDebug
The DiscordDebug plugin can be used to help debug SquadJS by dumping SquadJS events to a Discord channel.
-
Discord connector name.
discord -
The ID of the channel to log events to.
-
A list of events to dump.
[]
667741905228136459[
"PLAYER_DIED"
]DiscordFOBHABExplosionDamage
The DiscordFOBHABExplosionDamage plugin logs damage done to FOBs and HABs by explosions to help identify engineers blowing up friendly FOBs and HABs.
-
Discord connector name.
discord -
The ID of the channel to log FOB/HAB explosion damage to.
-
The color of the embeds.
16761867
667741905228136459DiscordKillFeed
The DiscordKillFeed plugin logs all wounds and related information to a Discord channel for admins to review.
-
Discord connector name.
discord -
The ID of the channel to log teamkills to.
-
The color of the embeds.
16761867 -
Disable Community Ban List information.
false
667741905228136459DiscordPlaceholder
The DiscordPlaceholder plugin allows you to make your bot create placeholder messages that can be used when configuring other plugins.
-
Discord connector name.
discord -
Command to create Discord placeholder.
!placeholder -
The bot will only answer with a placeholder on this channel
DiscordRcon
The DiscordRcon plugin allows a specified Discord channel to be used as a RCON console to run RCON commands.
-
Discord connector name.
discord -
ID of channel to turn into RCON console.
-
- 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.
{} -
Prepend admin names when making announcements.
false
667741905228136459{
"123456789123456789": [
"AdminBroadcast",
"AdminForceTeamChange",
"AdminDemoteCommander"
]
}DiscordRoundWinner
The DiscordRoundWinner plugin will send the round winner to a Discord channel.
-
Discord connector name.
discord -
The ID of the channel to log admin broadcasts to.
-
The color of the embed.
16761867
667741905228136459DiscordRoundEnded
The DiscordRoundEnded plugin will send the round winner to a Discord channel.
-
Discord connector name.
discord -
The ID of the channel to log round end events to.
-
The color of the embed.
16761867
667741905228136459