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.
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).
Connectors allow SquadJS to communicate with external resources.
```json
"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.
*`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.
-`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`.
```json
"discord": "Discord Login Token",
```
Requires a Discord bot login token.
##### Databases
SquadJS uses [Sequelize](https://sequelize.org/) to connect and use a wide range of SQL databases.
The connector should be configured using any of Sequelize's single argument configuration options.
<p>How often in <b>Seconds</b> should we warn the player about being unassigned?</p>
<h6>Default</h6>
<pre><code>30</code></pre></li>
<li><h4>unassignedTimer</h4>
<h6>Description</h6>
<p>How long in <b>Seconds</b> to wait before a unassigned player is kicked</p>
<h6>Default</h6>
<pre><code>360</code></pre></li>
<li><h4>playerThreshold</h4>
<h6>Description</h6>
<p>Player count required for AutoKick to start kicking players, set to -1 to disable</p>
<h6>Default</h6>
<pre><code>93</code></pre></li>
<li><h4>roundStartDelay</h4>
<h6>Description</h6>
<p>Time delay in <b>Seconds</b> from start of the round before AutoKick starts kicking again</p>
<h6>Default</h6>
<pre><code>900</code></pre></li>
<li><h4>ignoreAdmins</h4>
<h6>Description</h6>
<p><ul><li><code>true</code>: Admins will <b>NOT</b> be kicked</li><li><code>false</code>: Admins <b>WILL</b> be kicked</li></ul></p>
<h6>Default</h6>
<pre><code>false</code></pre></li>
<li><h4>ignoreWhitelist</h4>
<h6>Description</h6>
<p><ul><li><code>true</code>: Reserve slot players will <b>NOT</b> be kicked</li><li><code>false</code>: Reserve slot players <b>WILL</b> be kicked</li></ul></p>
<p>The <code>AutoTkWarn</code> plugin will automatically warn players with a message when they teamkill.</p>
<h3>Options</h3>
<ul><li><h4>message</h4>
<h6>Description</h6>
<p>The message to warn players with.</p>
<h6>Default</h6>
<pre><code>Please apologise for ALL TKs in ALL chat!</code></pre></li></ul>
</details>
<details>
<summary>ChatCommands</summary>
<h2>ChatCommands</h2>
<p>The <code>ChatCommands</code> plugin can be configured to make chat commands that broadcast or warn the caller with present messages.</p>
<h3>Options</h3>
<ul><li><h4>commands</h4>
<h6>Description</h6>
<p>An array of objects containing the following properties: <ul><li><code>command</code> - The command that initiates the message.</li><li><code>type</code> - Either <code>warn</code> or <code>broadcast</code>.</li><li><code>response</code> - The message to respond with.</li><li><code>ignoreChats</code> - A list of chats to ignore the commands in. Use this to limit it to admins.</li></ul></p>
<h6>Default</h6>
<pre><code>[
{
"command": "squadjs",
"type": "warn",
"response": "This server is powered by SquadJS.",
"ignoreChats": []
}
]</code></pre></li></ul>
</details>
<details>
<summary>DBLog</summary>
<h2>DBLog</h2>
<p>The <code>mysql-log</code> 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):
<ul><li><ahref="https://grafana.com/">Grafana</a> is a cool way of viewing server statistics stored in the database.</li>
<li>Install Grafana.</li>
<li>Add your database as a datasource named <code>SquadJS</code>.</li>
<li>Import the <ahref="https://github.com/Thomas-Smyth/SquadJS/blob/master/squad-server/templates/SquadJS-Dashboard-v2.json">SquadJS Dashboard</a> to get a preconfigured MySQL only Grafana dashboard.</li>
<li>Install any missing Grafana plugins.</li></ul></p>
<h3>Options</h3>
<ul><li><h4>database (Required)</h4>
<h6>Description</h6>
<p>The Sequelize connector to log server information to.</p>
<h6>Default</h6>
<pre><code>mysql</code></pre></li>
<li><h4>overrideServerID</h4>
<h6>Description</h6>
<p>A overridden server ID.</p>
<h6>Default</h6>
<pre><code>null</code></pre></li></ul>
</details>
<details>
<summary>DiscordAdminBroadcast</summary>
<h2>DiscordAdminBroadcast</h2>
<p>The <code>DiscordAdminBroadcast</code> plugin will send a copy of admin broadcasts made in game to a Discord channel.</p>
<p>The <code>DiscordAdminRequest</code> plugin will ping admins in a Discord channel when a player requests an admin via the <code>!admin</code> command in in-game chat.</p>
<p>The <code>DiscordPlaceholder</code> plugin allows you to make your bot create placeholder messages that can be used when configuring other plugins.</p>
<p><ul><li>Dictionary of roles and a list of the permissions they are allowed to use.<li>If dictionary is empty (<code>{}</code>) permissions will be disabled</li><li>A list of available RCON commands can be found here <a>https://squad.gamepedia.com/Server_Administration#Admin_Console_Commands</a>.</ul></p>
<p>The <code>DiscordSubSystemRestarter</code> plugin allows you to manually restart SquadJS subsystems in case an issues arises with them.<ul><li><code>!squadjs restartsubsystem rcon</code></li><li><code>!squadjs restartsubsystem logparser</code></li></ul></p>
<p>The <code>SCBLInfo</code> plugin alerts admins when a harmful player is detected joining their server based on data from the <ahref="https://squad-community-ban-list.com/">Squad Community Ban List</a>.</p>
<p>Admins will be alerted when a player has this or more reputation points. For more information on reputation points, see the <ahref="https://squad-community-ban-list.com/faq">Squad Community Ban List's FAQ</a></p>
<p>The <code>SeedingMode</code> 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.</p>
<h3>Options</h3>
<ul><li><h4>interval</h4>
<h6>Description</h6>
<p>Frequency of seeding messages in milliseconds.</p>
<h6>Default</h6>
<pre><code>150000</code></pre></li>
<li><h4>seedingThreshold</h4>
<h6>Description</h6>
<p>Player count required for server not to be in seeding mode.</p>
<h6>Default</h6>
<pre><code>50</code></pre></li>
<li><h4>seedingMessage</h4>
<h6>Description</h6>
<p>Seeding message to display.</p>
<h6>Default</h6>
<pre><code>Seeding Rules Active! Fight only over the middle flags! No FOB Hunting!</code></pre></li>
<li><h4>liveEnabled</h4>
<h6>Description</h6>
<p>Enable "Live" messages for when the server goes live.</p>
<h6>Default</h6>
<pre><code>true</code></pre></li>
<li><h4>liveThreshold</h4>
<h6>Description</h6>
<p>Player count required for "Live" messages to not bee displayed.</p>
<h6>Default</h6>
<pre><code>52</code></pre></li>
<li><h4>liveMessage</h4>
<h6>Description</h6>
<p>"Live" message to display.</p>
<h6>Default</h6>
<pre><code>Live!</code></pre></li></ul>
</details>
<details>
<summary>TeamRandomizer</summary>
<h2>TeamRandomizer</h2>
<p>The <code>TeamRandomizer</code> 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, <code>!randomize</code> into in-game admin chat</p>
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.
- 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.