Welcome to SquidBots! SquidBots is a plug-in for Offworld games, distributed with Squad and the Squad Editor. Anyone can add to this documentation (just make a pull request).
SquidBots started off as a tool for making Squad videos. The existing workflow of pre-recording your Squad character in PIE and saving out the animation was too time consuming, so I set out to automate some of the processes. The systems created let you entirely keyframe a soldier:
These allowed for the creation of videos like:
The systems became extensive enough that I started messing around with having systems to automaticallly keyframe soldiers: The first test of which was the Squad Tower Defence mod. Next, I experimented with using behaviour trees and pathfinding to make complex solider AI. The final hurdle was redesigning the system to be replicated (supporting multiplayer), and with those hurdles completed came the first release of the SquidBots mod. SquidBots is designed to be somewhat game-agnostic, and had been ported with ease to Post Scriptum (now Squad44).
SquidBots was acquired by Offworld, and has now been integrated into Squad's base game.
SquidBots is designed to work in networked games (client), and offline (standalone). When testing in editor, it is recommended to play in standalone.
There is currently a bug in the SquadEditor that fully automatic sounds can lock up your editor forever without crashing. If you have no need for authentic full auto sounds, it is recommended you disable Can Use Full Auto Sounds in Editor in the Editor Preferences. This will replace full auto sounds with semi auto sounds.
SquidBots has not yet been optimised for performance. It’s almost all written in Blueprint, and the origins of the mod comes from wanting a high fidelity animation system for cinematics - the bots are doing lots of potentially unnecessary stuff for general gameplay. The current limitation to bot counts is client performance, and I’d recommend avoiding more than 70 bots existing on a client for now. On a server, the limits are a bit higher, somewhere between 100-200.
When playing in a real game, with a client connected to a server, SquidBots benefits from the AI logic being processed by the server, and the animation logic being handled by the clients. But when playing offline, or testing in editor, it’s all having to be processed by one machine, worsening performance.
When playing offline, ~50 bots would give you acceptable performance (50 bots concentrated around the player can feel more full than 100 players scattered around a 8x8km map).
And when testing in editor, there’s lots of engine debug systems running in the background, again slowing down performance. I’d recommend lowering your bot counts in editor to whatever your pc can handle (for one of my PCs, that’s around 20, for another it’s around 40). (If testing seed layers, use AdminSetSeedTargetPlayerCount 10)
For bots to move around, SquidBots requires the gameplay layer to have a navmesh. Due to an engine bug, the navmesh must be generated in the gameplay layer, not in the Geo Level (which annoyingly means duplicate navmeshes across layers). Hopefully this will be fixed in Squad in the future, were we to add navmeshes to all the vanilla geo levels.
To build a navmesh, drag-and-drop a NavMeshBoundsVolume into your world.
I believe the NavMeshBoundsVolume can be placed in the Geo Level, but then you must manually generate the NavMesh in the gameplay layer.
You can then scale your NavMeshBoundsVolume to the size of your playspace.
Bots are currently unaffected by Squad Map boundaries, so make sure to only have this cover the area you want bots to run around in.
With editor default settings, the navmesh should then be automatically generated. For more manual control of this, you can disable Update Navigation Automatically in the editor preferences. To then manually generate the navmesh, type RebuildNavigation in the editor console (~ key).
Note that the automated navmesh generation is asynchronous, so doesn’t lock up the editor and can be cancelled, but RebuildNavigation is synchronous, locking up the editor and non cancellable.
Once the navmesh has been generated, you can hit P in the editor viewport and the navmesh will be displayed.
If this isn’t being generated, I’d recommend looking into the Unreal Engine documentation as Squad is using the Engine’s navigation system out of the box.
When generating automatically, it’s advised that you disable the Navmesh Visualizer (hit P again), as generating with the visualizer enabled drastically worsens performance and slows down generation.
Squad has project defaults defined for its navmeshes, tuned for the best results on the existing ~25 squad maps. If you want to manually tune these (which I wouldn’t recommend as it’s a rabbit hole), modify the navmesh settings in the generated RecastNavMesh_Default.
You can also modify these in the Project Settings, but note that these apply globally, and for modders will be wiped whenever the SDK updates.
There are WorldSettings related to AI (Enable AISystem, NavigationSystemConfig), however they are overridden to use Squad’s defaults, unless Enable Custom Navigation System Config is enabled. So I would recommend not touching this.
Oftentimes you might need to reload your world, or potentially restart your editor. Sometimes your navmesh can be entirely corrupted, so you may need to delete your existing RecastNavMesh_Default, then force RebuildNavigation again. Sometimes that doesn't even work, so you may need to move your NavMeshBoundsVolume, or delete and replace your NavMeshBoundsVolume.
Ensure that Used for Navigation is enabled on the landscape.
Areas of the navmesh can be marked as restricted to a team. Placing a NavModifierVolume in the world, or adding a NavModifier component to an existing actor, you can use the Team1RestrictedZone or Team2RestrictedZone. The restriction zones work that only Bots with Team X can use that section of the navmesh for pathing. (Red = Team 1, Blue = Team 2). In vanilla Squad, the Gameplay_RestrictedTeamZone used for seeding already has this navmodifier, so seeding layers restrict bots from entering the enemy team’s restricted zone.
Once the navmesh is sorted out, getting bots in seeding is very simple. Assuming you have a functional seed layer already, place an SQSeedingBotSpawner in the world.
You’ll want to place one for each team, near their team’s player spawn point. Ensure that they are within the navmesh, otherwise the bots will be immediately killed on spawn due to stuck detection. For seeding, you’ll only need to modify the TeamNum setting. Seeding bot spawners rely on the gamemode being set up correctly. If set up incorrectly, there’ll be logs explaining how to amend the layer.
Seed bot counts are determined by the SeedTargetPlayerCount (in the BP_GameStateSquad_Seed). This is read from the ServerConfig/CustomOptions.cfg. Here’s what is explained there:
// Target player count for seeding. Bots will be used to fill the server up to this player count.
// Teams will be balanced so that both teams have an equal number of players+bots.
// With SeedTargetPlayerCount=40, this is what you'll see:
// On an empty-ish server // On a more full server
// Team 1 3 players 17 bots // Team 1 16 players 4 bots
// Team 2 5 players 15 bots // Team 2 18 players 2 bots
// Bots will all be killed (and none will spawn) when the seed match is live.
#SeedTargetPlayerCount=40
Note that the SpawnerMaxBotCount is unused for SeedingBotSpawners, it just uses the SeedTargetPlayerCount. This can be set at runtime using AdminSetSeedTargetPlayerCount X.
Multiple seeding bot spawners can be placed per team, but the team will still be limited to the (target player count / 2) number of bots.
This is significant as Squad’s worlds are quite dynamic, with deployables, vehicles and wrecks affecting the game world and blocking once-available paths. The static navmeshes means that bots don’t know how to path around these objects, and will try to walk into them and get stuck. As a short term workaround (and legacy from the mod), bots stuck walking into deployables will automatically passively dig them down, until the deployable is destroyed or the bot is able to get unstuck. This is important to note in the seeding gamemode, as placing the seed bot spawners near fobs / habs can have gameplay consequences, due to the bots potentially getting stuck and digging these down.
SquidBots officially supports:
- Singleplayer (standalone)
- Multiplayer (replicated clients)
- Editor scripting (level sequences)
On paper, SquidBot should be game agnostic and not depend on Squad functionality. This was an advantage of SquidBots as a mod not depending on a Squad base class, and we'd like to keep it that way. In practice, lots of Squad code and systems are used by SquidBots in Blueprint. No new code is being written depending on Squad (the plugin's C++ modules don't depend on Squad for example), so slowly as systems are refactored, the system should move towards being entirely game agnostic. Squad can depend on SquidBots, but SquidBot cannot depend on Squad.
Some functionality SquidBots is looking for must be implemented for use in a project. Squad's implementation of this is USQSquidBotsProjectImplementation. Setting the SquidBotsProjectImplementationClass in the ODKSquidBotsSettings will assign the project its implementation class. SquidBots will manage the lifetime of a singleton of this class, then talk to it through the UODKSquidBotsProjectInterface.
ACharacter: UE4 Engine base class, note that SquidBots does not use any SQ parent class.UODKAvatar: C++ Parent class, very minimal implementation details. Adds key functionality like Health, Seeded Random support. Slowly, more stable functionality and features needing to be optimised will be moved into this.SkeletalMeshPawn: A redundant legacy parent class that should be removed.KillableSkeletalMeshPawn: Adds custom logic for damaging. Historically was added for non-humanoid bots (Emus lol) but should be removed and damage logic refactored away.Avatar: The base class for any animation work. This was originally where 99% of the mod was developed, and contains most logic for the solider and their weapons.SquadSoldier: Adds support for Squad Role parsing (not very project agnostic), and adds support for entering vehicles. Any cinematic work should be usingSquadSoldiers as they contain no AI logic.SquidBot: Adds all AI logic for soldier bots.SquadSoldiers can only be keyframed, but SquidBots can do complex behaviours and processing including scanning the world around them and automatically hunting down targets, following orders etc.SQSquidBot: Squad implementation ofSquidBot. Any Squad-specific details should be contained toSQSquidBot. For example,SQSquidBotadds any system interactions for the Squad map and nametag systems, and interactions with water. The optimal setup would be everything above this point would be project agnostic and squad then adds its defaults and overrides here.
When SquidBots are used for creating cinematics, it's pivotal for creators to get the exact same results whenever they play their sequence. With that in mind, a requirement of SquidBots' systems is all actions should be deterministic and repeatable. SquidBots does use randoms, but a seeded random system. The SquidBot has a Seed variable defined. Whenever a random is needed for initialisation of a bot, the seed is used for random number generation. Whenever a continuous series of random numbers is needed, UODKSequencerHelpers::GetRandomSeedAtFrame should be used. This will hook up to any existing level sequences to ensure that the seed is the same at that frame every time the sequence is played.
Tip: SquidBots have a function on them to force randomise the seed. Selecting multiple bots and running this event will give them all different random seeds.
Weapons and Items (all inheriting from GenericItem) are designed to exist both owned by a bot and by themselves. SQWeapon does not support this functionality, and this can be used to make simple weapon sentries or test weapon firing functionality without a bot
SquidBots and Items both use a function called Event Construct to do most of their initialisation logic. This gets run at either construction time or beginplay, depending on the when the bot is spawned.
SquidBots are not constrained to just Team 1 or Team 2. SquidBots have a team number that can be set to any integer. Bots will view any other entities that are not on their team as their enemy.
Bots can be preplaced in the editor. Drag-and-drop a SQSquidBot into the world.
There are a lot of settings configurable on the SquidBot details view, but all you need to search for to get a spawned bot in the scene is the SquadRole
Set the BP_SQFactionSetup and BP_SQRoleSettings to the faction and role you want the bot to use. Optionally, you can use a random role (enable Use Random Role, which will choose a random role from the faction setups you provide in the RandomRoleSettings.FactionSetups array. The random role system also lets you filter for roles with specific tags or using specific weapons. Tags work that for a role to pass the filter, all of its tags must be in the RandomRoleSettings.Tags array. You may want to also set the Seed and the TeamNum.
TODO: Improve spawner systems and documentation.
Currently the only spawner that works out of the box for SquidBots is the SQSeedingBotSpawner.
As a designer, the 2 most important API calls you have are spawning bots and giving them orders. Once you get to grips with those systems, the world is your oyster. To Spawn a bot, use the Blueprint SpawnActor node, and select a SQSquidBot class. Parameters will be explained elsewhere in this document, so I would recommend at this point usign ctrl+f.
