Click here for ECS Swarms on the Unity Asset Store

Description

ECS Swarms is a framework for creating high performance swarm/flocking behaviours built on ECS. Capable of creating fantastic simulations of birds, fish, and so much more!

The ECS Swarm Toolkit is the asset for you if you are looking to simply add efficient, swarming/flocking behaviours to your scene. This can be used to create many great effects such as birds, fish, and more! ECS Swarm Toolkit is designed to be as simple as possible as to abstract away any complicated ECS code, it also comes with extensive web-based documentation for you to easily add your own behaviours. It also comes with many built-in behaviours so that you can create your own simulations just by adding a few components, no coding required!

It uses ECS and the Physics package, so in order to use you must install the Hybrid Renderer and the Physics packages from the package manager (requires Unity 2022 for Entities 1.0, or Unity 2020 for Entities 0.50). It also supports using the Burst compiler for incredible performance!

Features:

Uses Unity ECS and the Burst compiler to achieve top-tier performance.

Uses sparse spatial partitioning for increased optimization.

Capable of simulating tens of thousands of agents at 60+ fps easily on most modern processors.

Capable of creating highly complex simulations, includes a Predator vs. Prey example scene.

Includes physics-based obstacle avoidance. So your swarms won't end up flying through walls!

Comes with classic boid behaviours such as seperation, alignment, cohesion; but also comes with more such as target, obstacle, avoidance, hover, gravity, and more! You can mix and match to easily create your own swarms, no coding required!

Built to be as simple to extend as possible so you can easily create your own behaviours!

Tons of customizable features to finely tune your swarms to exactly your needs.

Includes extensive web-based documentation and video tutorial.

Full source code included.

Includes 3 examples scenes: Birds, Fish, PredatorPrey

Includes third-party model and texture assets. More information can be found in the Third-Party Notices.txt file in the package.

Links

Guides

Trailers

Benchmarks

Getting Started

Requirements

ECS Swarms makes use of ECS and DOTS, what this means is that in order to make use of ECS Swarms you must install some packages nessesary for ECS and DOTS. The two packages that are required are Hybrid Renderer and Havok Physics for Unity (the Unity Physics package also works, but Havok Physics for Unity is a bit faster, while also having some additional licensing requirements). This means that you must also be using Unity version 2020.1.9f1 or later, as that is the last version that both of those packages are available for.

However, both of these packages are currently in the preview stages and have not had their full release yet. This means that you need to turn on Enable Preview Packages in the package manager. To do this, open your Unity project and navigate to Window > Package Manager > Settings (gear icon) > Advanced Project Settings. Then you can enable the Enable Preview Packages settings.

To install the Hybrid Renderer package, open your Unity project and navigate to Window > Package Manager > + > Add Package From git URL. Then enter com.unity.rendering.hybrid@0.50.0-preview.44 (the version may change, however after installing this version there will be an option to update to the latest version. If you would like the documentation for the Hybrid Renderer, you can find it here.

However for installing the Physics package, you have two options. You can install the Havok Physics for Unity which includes the DOTS Physics package and a performance boost compared to only DOTS Physics, however it is not free for Pro users. If that is a problem for you, you can instead install only DOTS Physics, which is free but slightly less performant than Havok Physics. The performance difference should be relatively negligable, unless you are have very Physics intensive scene.

1. To install Havok Physics for Unity, open your Unity project and navigate to Window > Package Manager, then set Packages to Unity Registry. Then search for "Physics" and install the Havok Physics for Unity package (note that you must have enabled the Enable Pre-release Packages setting in order to have this appear in the search). If you would like the documentation for this Physics package, you can find it here.
2. To instead install only DOTS Physics, open your Unity project and navigate to Window > Package Manager > + > Add Package From git URL. Then enter com.unity.physics@0.51.0-preview.32, these version numbers are subject to change but they can be found here.

You will also want to sure your project is made to render with either URP (Universal Render Pipeline) or HDRP (High Definition Render Pipeline), this is because Hybrid Renderer only supports those options, meaning that assets made for the Built-in render pipeline may not be compatible.

Using ECS Swarms

Using ECS Swarms once you have DOTS set-up is quite simple. All you need to do is place a Swarm Settings component on the GameObject you wish to use as a prefab for your swarms. After adding the swarms settings component, you can tweak the values and settings to whatever you would like. You must also click the ConvertToEntity toggle button, in order to mark this GameObject to be converted to an ECS entity (note that in ECS v1.0 there is no longer a ConvertToEntity button, GameObjects will only be converted to entities if they are part of a subscene). Then save that GameObject as a prefab.

After creating your swarm prefab, you must now create a swarm spawner. To do this add a Swarm Spawner component to any GameObject in your scene. You will want to fill in the data for the prefab to spawn, the area to spawn in, and the count to spawn. If you are using ECS v0.5X, make sure to also toggle ConvertToEntity on this GameObject. If you are using ECS v1.0, you must then put that swarm spawner in a subscene, in v1.0 GameObjects will only be converted to entities if they are part of a subscene.

That's really all you need to get started, it's that simple! In addition, you can also add the Swarm Node components to GameObjects, this will cause various effects on nearby swarms based on the node's tag attribute. However, those GameObjects must also have ConvertToEntity enabled.

Built in Behaviours

Overview

ECS Swarms comes with many swarm/flocking behaviours. Some of these are classic boid behaviours such as seperation, alignment, and cohesion; however, ECS Swarms also comes with others such as avoidance, hover, target, obstacle, gravity, and more! This section will provide a brief description of how each behaviour works, and how to use all the various settings so you can customize your swarms to exactly your purpose.

Vision

Many of the swarms behaviours are affected by it's vision settings. A swarms vision is it's ability to sense other swarms in it's nearby area. The built-in behaviours that are affected by vision are seperation, alignment, and cohesion. A swarm's vision has two propeties: distance (defines how far away this swarm can see other swarms from), and angle (defines the maximum angle at which this swarm can see other swarms, a value of 180 indicates full 360° vision).

The cell size of the sparse spatial partitioning is governed by the highest vision distance in the scene. For example if you have 10000 swarms with a vision distance of 10, but 1 swarm with a distance of 100. Then the cell size of the spatial partitioning will be 100, thus causing the simulation to run far slower. For maximum performance you want to keep the vision distances lower.

Boid Behaviours

Seperation

Seperation is a behaviour that causes swarms to be repelled by nearby swarms if they get too close together. This helps stop swarms from stacking on top of each other. The settings for seperation are also used to calculate predator/prey forces.

Alignment

Alignment is a behaviour that causes swarms to steer to face in the same directions as other nearby swarms. This helps swarms move together in flocks better.

Cohesion

Cohesion is a behaviour that causes swarms to move towards the center of nearby swarms. This behaviour also helps swarms move together in flocks better.

New Behaviours

Avoidance

Avoidance is a physics-based behaviour that performs obstacle avoidance for that swarm. It is calculated by doing many physics sphere casts until one is found that has a clear path. This behaviour allows swarms to avoid other colliders in your scene, you will also need to make sure those colliders are on GameObjects with ConvertToEntity enabled.

Hover

Hover is a physics-based behaviour that allows swarms to hover above some surface. It is calculated by doing a physics sphere cast in the downward direction, then applying a force upward depending on how close the swarm is to the surface. As with avoidance, you will also need to make sure the colliders that should be interacted with are on GameObjects with ConvertToEntity enabled.

Target

Target is a node-based behaviour that makes swarms attracted to nearby SwarmNode's with the Target tag.

Obstacle

Obstacle is a node-based behaviour that makes swarms repelled by nearby SwarmNode's with the Obstacle tag.

Gravity

Gravity is a behaviour that applies a constant force to the swarm.

Drag

Drag is a behaviour that applies drag or friction to the swarms movement. This can be used to dampen their movements or slow them down.

How to Create Custom Behaviours

What is ECS?

ECS stands for Entity Component System. It is a way of writing high performance code for DOTS (Unity's data-oriented technology stack). ECS code can be quite confusing at first, that is what ECS Swarms tries to abstract away as much ECS Code as possible. So that you can add your own swarm behaviours without having to be an expert in ECS. However, it is useful to at least have a basic understanding of ECS so that you can better understand ECS Swarms.

ECS works in terms of 3 main parts: Entities, Components, and Systems. Entities are essentially super light GameObjects, they are merely containers for Components. Components hold all the data for each individual, however they don't execute any behaviours, they only hold the data. Systems are what actually executes the behaviours, they collect entities with similar components, then calculate their behaviours in parallel using multi-threading. This multi-threading is what makes ECS incredibly performant.

Regular Behaviours

If you want to create your own behaviour that doesn't utilize any physics-based features (no raycasts or anything similar), then you would likely want to implement it inside of the SwarmBehaviour struct, the SwarmBehaviour struct is what is responsible for calculating a swarms velocity.

Physics Based Behaviours

If you want to create your own behaviour that does use some physics-based features (no raycasts or anything similar), then you would likely want to implement it inside of the SwarmPhysicsSystem class, the SwarmPhysicsSystem is an ECS system that is responsible for calculating all the physics behaviours and adding them all to the swarms PhysicsResult. So if you want to add your own physics based behaviour, it should modify PhysicsResult and possibly ForcePhysics (a flag that causes regular behaviours to be ignored and to only use the physics-based ones, this can be used for emergency obstacle avoidance scenarios).

Custom Settings

Due to how ECS splits up data and behaviours, adding your own custom settings to a swarm is going to be slightly more complicated. You will need to do three things in order to add your own custom settings.

1. Add the properties you want into the SwarmSettings struct, this is component that is shared across all swarms with the same settings.
2. Add those same properties to the SwarmSettingsAuthoring class, this is the component that is shown in the inspector.
3. Edit the Convert function in the SwarmSettingsAuthoring class so that it will set the value in SwarmSettings to the corresponding value in SwarmSettingsAuthoring.

After you've done all those steps, you can then access your custom settings in code by accessing a SwarmSettings variable

Script Reference

The Script Reference is organized based on classes, structs, and enums. Everything in ECS Swarms is under the ECSSwarms namespace. It also includes many references to the Mathematics and Physics namespaces.

Classes

SwarmAvoidance

SwarmHover

SwarmNodeAuthoring

SwarmPhysicsSystem

SwarmSettingsAuthoring

SwarmSpawnerAuthoring

SwarmSpawnerSystem

SwarmSystem

SwarmVisionHelper

Structs

SwarmBehaviour

SwarmData

SwarmNode

SwarmSettings

SwarmSpawner

Enums

MovementType

SwarmNodeTag

SwarmSpawnerDirection

SwarmSpawnerShape

SwarmTag

Contact Information

If you have any questions or inquires please email ecsswarmtoolkit@gmail.com.