Dark Theme

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 2020.1.9f1 or later). It also supports using the Burst compiler for incredible performance!

Features:

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. 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. 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. Make sure to also toggle ConvertToEntity on this GameObject.

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

A static class used to calculate the physics-based avoidance behaviour for swarms.

public static class SwarmAvoidance

SwarmHover

A static class used to calculate the physics-based hover behaviour for swarms.

public static class SwarmHover

SwarmNodeAuthoring

The authoring component for SwarmNode. A SwarmNode is a 'node' with a tag and position that can influence the behaviour of swarms.

public class SwarmNodeAuthoring : MonoBehaviour, IConvertGameObjectToEntity

SwarmPhysicsSystem

The system for calculating all the physics based behaviours of the swarms. The reason these must be split from the regular behaviours is because the physics system can only be queried in certain update groups.

You may want to edit this if you choose to implement your own custom physics based behaviours.

public class SwarmPhysicsSystem : SystemBase

SwarmSettingsAuthoring

The authoring component for SwarmSettings. SwarmSettings is a shared component for the settings for a particular kind of swarm. It contains attributes related to movement, vision, and behaviours.

You may want to edit this if you want to add customizable settings for custom behaviours.

public class SwarmSettingsAuthoring : MonoBehaviour, IConvertGameObjectToEntity

SwarmSpawnerAuthoring

An authoring component for SwarmSpawner. A SpawnSpawner is a component used to spawn various quantites of swarms. It contains attributes for changing the shape and direction that the swarms are spawned in.

public class SwarmSpawnerAuthoring : MonoBehaviour, IConvertGameObjectToEntity, IDeclareReferencedPrefabs

SwarmSpawnerSystem

The system for spawning all the swarms for their corresponding SwarmSpawner components. Once a SwarmSpawner is used to spawn swarms, it is destroyed.

public class SwarmSpawnerSystem : SystemBase

SwarmSystem

The main system for calculating all the behaviours of the swarms, doing the spatial partitioning, and for updating their data (position, velocity, etc.).

public class SwarmSystem : SystemBase

SwarmVisionHelper

A static class used to assist in vision/avoidance based calculations for swarm behaviours.

public static class SwarmVisionHelper

Structs

SwarmBehaviour

A struct that is created once per update cycle for each swarm, and is used to calculate and set all the behaviours for the swarms.

This is likely the struct you would want to edit if you wanted to add new behaviours.

The lifecycle of a SwarmBehaviour struct is as follows: for each swarm, a SwarmBehaviour is created via the constructor, then ForEachSwarmInAdjacentPartitions is called for every other swarm in the adjacent sparse spatial partitions, after all other swarms have been iterated through Finish is then called. After Finish is called, the position, velocity, and tag properties of the SwarmBehaviour are read and used to set the relevant data for the swarm.

public struct SwarmBehaviour

SwarmData

All the data for a single swarm to hold. Contains the swarms velocity and tag; also contains data for the result of physics based behaviours.

public struct SwarmData : IComponentData

SwarmNode

A 'node' with a tag and position that can influence the behaviour of swarms.

public struct SwarmNode : IComponentData

SwarmSettings

A shared component for the settings for a particular kind of swarm. Contains attributes related to movement, vision, and behaviours.

You may want to edit this if you want to add customizable settings for custom behaviours.

public struct SwarmSettings : ISharedComponentData

SwarmSpawner

A component used to spawn various quantites of swarms. Contains attributes for changing the shape and direction that the swarms are spawned in.

public struct SwarmData : IComponentData

Enums

MovementType

The mode in which to apply a movement vector.

public enum MovementType

SwarmNodeTag

Tags that a SwarmNode can have. Ex. Target which causes swarms to be attracted to the node's position, Obstacle which causes swarms to be repeled by the node's position.

public enum SwarmNodeTag

SwarmSpawnerDirection

The different ways that a swarms direction can be set by a SwarmSpawner.

public enum SwarmSpawnerDirection

SwarmSpawnerShape

The different shapes that a SwarmSpawner can use to spawn.

public enum SwarmSpawnerShape

SwarmTag

A tag that a swarm can have. Can be used to make different swarms to interact differently with each other (ex. Predator/Prey).

public enum SwarmTag

Contact Information

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