[A while back](https://www.mikecann.blog/portfolio/projects/unity-ashteroids-ash-framework-in-unity/) I decided to scratch an itch and see if [Richard Lord's Ash Entity Framework](https://www.ashframework.org/) could be ported to Unity. Well I was pleasantly surprised that it did port quite easily (with some help from David Arno's .NET port) and worked well enough that I could also port [Richard's Asteroids game over to Unity](https://github.com/mikecann/UnityAshteroids) too.



Since then I have had a few people contact me interested in using the port for their own projects so I decided to give it a little more love and polish.

## Part 1 - Separation

First things first was to split the Ash library from the Asteroids example project so you dont have to include the entire Asteroids port in every single one of your games (madness). So now the Unity Ash project can be found here:

[https://github.com/mikecann/Unity-Ash](https://github.com/mikecann/Unity-Ash)

..and the Asteroids project (which uses the Untity-Ash project) lives here:

[https://github.com/mikecann/UnityAshteroids](https://github.com/mikecann/UnityAshteroids)

Now all that you need to do to is to clone (or include as submodule) Unity-Ash into your game's Assets folder and you should be good to go, simples!

## Part 2 - GetComponents

Next up was performance. I knew that the performance of Unity-Ash was the biggest stumbling block and unfortunately it seemed like a fairly fundamental one thanks to some holes in the Unity API (more on that later). However, I knew there were a few low-hanging-performance-fruits I could pick that should speed up things a bit.

To experiment with things I setup a separate Unity project for the performance tests and included [Unity-Ash from GitHub](https://github.com/mikecann/Unity-Ash).

[![2014-12-10_09-30-51](https://www.mikecann.blog/wp-content/uploads/2014/12/2014-12-10_09-30-51-1024x618.png)](https://www.mikecann.blog/wp-content/uploads/2014/12/2014-12-10_09-30-51.png)

The key performance bottleneck in Unity-Ash is the way the code checks for component additions and removals. Dynamic component addition and removal is key to how Ash functions and in AS3 because it was all custom code we could just fire an event when a component is added or removed from an Entity. Because Unity-Ash tries to piggyback on top of Unity's existing Entity (GameObject) / Component architecture we dont actually have access to the GameObject source and thus cant trigger events when a component is added or removed.

The solution I came up with is to add a component to each GameObject which acts like the Entity. It is responsible for checking to see if components have been added or removed, to do this it gets a list of all the components in the GameObject each frame and compares against its internal cache to see if any have been added or removed. This solution works well, however you can probably see the performance hit involved with getting a list of components from Unity for each GameObject, each frame will likely be quite high.

Because this listing of components was so crucial to performance I decided to write some tests to see what is the fastest way of doing that:

```
public class GetComponentTests : MonoBehaviour
{
	public int iterations = 10000000;
	public int repeats = 3;

	public GameObject noComponents;
	public GameObject manyComponents;
	public List<Component> components;

	public void TestAll()
	{
		components = new List<Component>();
		TestHelpers.Execute(iterations, repeats, "Empty Function", TestEmpty);
		TestHelpers.Execute(iterations, repeats, "Get Components With No Components", NoComponentsGetComponents);
		TestHelpers.Execute(iterations, repeats, "Get Components With Many Components", ManyComponentsGetComponents);
		TestHelpers.Execute(iterations, repeats, "Get Components With No Components List", NoComponentsGetComponentsList);
		TestHelpers.Execute(iterations, repeats, "Get Components With Many Components List", ManyComponentsGetComponentsList);

		Debug.Log("components " + components.Count);
	}

	public void TestEmpty()
	{
	}

	public void NoComponentsGetComponents()
	{
		noComponents.GetComponents<Component>();
	}

	public void ManyComponentsGetComponents()
	{
		manyComponents.GetComponents<Component>();
	}

	public void NoComponentsGetComponentsList()
	{
		noComponents.GetComponents<Component>(components);
	}

	public void ManyComponentsGetComponentsList()
	{
		manyComponents.GetComponents<Component>(components);
	}
}
```

I run each of these 10 million times then repeat 3 times and average:

1. "TestEmpty" is my control test test to get a sense of the cost of simply calling an empty function. That averaged to 0ms elapsed
2. "NoComponentsGetComponents" I test getting a list of components when the GameObject is empty (other than Transform), that averaged to 22ms.
3. "ManyComponentsGetComponents" I test getting a list of components when there are 20 components (plus Transform) to see what the cost of getting additional components would be, that averaged to 35ms.
4. "NoComponentsGetComponentsList" is the same as 2) except I avoid an internal memory allocation my passing in a List to populate the return with, that averaged to 5ms.
5. "ManyComponentsGetComponentsList" is the same as 3) except I pass in the List again, that averaged to 15ms.

So in summary, I learned its much faster if I pass in a list to GetComponents, which makes sense as I avoid the memory allocation associated with returning a new array each time. As a result I folded this performance improvement into Unity-Ash.

## Part 3 - Unity vs Ash

These tests are all well and good but 10 million iterations of GetComponents in standalone is probably an unlikely use case in the standard game so in addition I wanted to test what the actual performance hit you would get if you used Unity-Ash in a game instead of the standard Unity way.

To test this I set up another scene that creates and updates 5,000 asteroids on the screen.

![upout](https://www.mikecann.blog/wp-content/uploads/2014/12/upout.jpg)

I time how long they create then I count how many frames I get in 10 seconds of updating them. Each asteroid has a 2D rigid body and a very simple controller script that wraps the Asteroids position on the screen:

![2014-12-10_10-15-54](https://www.mikecann.blog/wp-content/uploads/2014/12/2014-12-10_10-15-54.png)

```
public class AsteroidController : MonoBehaviour
{
	private Bounds bounds;

	void Awake()
	{
		var size = Camera.main.ScreenToWorldPoint(new Vector2(Screen.width, Screen.height));
		bounds = new Bounds(Vector3.zero, new Vector3(size.x * 2, size.y * 2));
	}

	void Update()
	{
		if (transform.position.x < bounds.min.x)
		{
			transform.position = new Vector3(transform.position.x + bounds.size.x, transform.position.y, transform.position.z);
		}
		if (transform.position.x > bounds.max.x)
		{
			transform.position = new Vector3(transform.position.x - bounds.size.x, transform.position.y, transform.position.z);
		}
		if (transform.position.y < bounds.min.y)
		{
			transform.position = new Vector3(transform.position.x, transform.position.y + bounds.size.y, transform.position.z);
		}
		if (transform.position.y > bounds.max.y)
		{
			transform.position = new Vector3(transform.position.x, transform.position.y - bounds.size.y, transform.position.z);
		}
	}
}
```

This was the base test and it took about 440ms to create 5000 asteroids and processed 83 frames over 10 seconds (8.3FPS).

Now I had my base I decided to setup the same scenario but using Unity-Ash to drive the updates. So now the Asteroid looks like this:

![2014-12-10_10-19-42](https://www.mikecann.blog/wp-content/uploads/2014/12/2014-12-10_10-19-42.png)

Notice that there is no controller for the Asteroid, now all the update logic happens in a system:

```
public class MovementSystem : SystemBase
{
	private Bounds bounds;
	private NodeList nodes;

	public MovementSystem()
	{
		var size = Camera.main.ScreenToWorldPoint(new Vector2(Screen.width, Screen.height));
		bounds = new Bounds(Vector3.zero, new Vector3(size.x * 2, size.y * 2));
	}

	override public void AddToGame(IGame game)
	{
		nodes = game.GetNodeList<MovementNode>();
	}

	override public void Update(float time)
	{
		var cam = Camera.main;
		for (var node = (MovementNode)nodes.Head; node != null; node = (MovementNode)node.Next)
		{
			var transform = node.Transform;
			var rigidbody = node.Rigidbody;

			if (transform.position.x < bounds.min.x)
			{
				transform.position = new Vector3(transform.position.x + bounds.size.x, transform.position.y, transform.position.z);
			}
			if (transform.position.x > bounds.max.x)
			{
				transform.position = new Vector3(transform.position.x - bounds.size.x, transform.position.y, transform.position.z);
			}
			if (transform.position.y < bounds.min.y)
			{
				transform.position = new Vector3(transform.position.x, transform.position.y + bounds.size.y, transform.position.z);
			}
			if (transform.position.y > bounds.max.y)
			{
				transform.position = new Vector3(transform.position.x, transform.position.y - bounds.size.y, transform.position.z);
			}
		}
	}

	override public void RemoveFromGame(IGame game)
	{
		nodes = null;
	}
}
```

The update logic is functionally exactly the same as the AsteroidController except its now contained within a system.

This time it took 595ms to create the Asteroids and we processed 33 frames over 10 seconds (3.3FPS).

So immediately you can see there is a large performance hit in using Ash-Unity over regular Unity (8.3FPS compared to 3.3FPS). To confirm that it was the extra overhead of checking for new components on each asteroid rather than the internal updating mechanism of the Systems in Ash I decided to turn off checking for component updates..

![2014-12-10_10-40-02](https://www.mikecann.blog/wp-content/uploads/2014/12/2014-12-10_10-40-02.png)

Sure enough the frame rate went back up (in fact higher!) than the Unity update rate of 8.3FPS to 8.6FPS.

So with this in mind I decided to add an option to the Entity component that lets you choose how often it checks for new components:

![2014-12-10_10-42-02](https://www.mikecann.blog/wp-content/uploads/2014/12/2014-12-10_10-42-02.png)

The reasoning is that its actually quite rare that you change the components after the initial creation of the object (at least that's what I found) and thus by reducing the number of times the Entity component checks for updates we should be able to increase the performance.

Sure enough, when set to "Every Other Frame" the framerate goes up to 4.5FPS then set to "Every 10 Frames" it goes up to 7.4 FPS. The final setting "If Component Count Changes" attempts to skip the iteration of the components by comparing the number of components against the previous frame, this results in 7.5 FPS.

So the short of the long is that you can get the same as or higher FPS using Unity-Ash so long as you know beforehand how often you are going to be added or removing components. If you have entities that is likely never to have components added or removed then set it to update "Never" and enjoy great FPS with the power of using Ash.

Just as an addendum to this, I have submitted a feature request to Unity to add in events to GameObject that we can listen to that are fired when components are added or removed, this would obviously remove 99.9% of these performance issues from Unity Ash so I would love your votes:

[https://feedback.unity3d.com/suggestions/componentadded-slash-removed-events-on-gameobject](https://feedback.unity3d.com/suggestions/componentadded-slash-removed-events-on-gameobject)

As a final step in the upgrade process I looked at what more radical changes we could make to the framework by taking advantage of Generics and some other features that C# gives us that were lacking in AS3, you can check those out towards the bottom of the readme: [https://github.com/mikecann/Unity-Ash](https://github.com/mikecann/Unity-Ash)

Well that's it for now, I hope you enjoy the improvements, please to let me know if you think its worth carrying on development, I would love to work on it some more but I have games to write!

I decided to take a break from the [game development](https://www.mikecann.blog/myprojects/mr-nibbles-3d/mr-nibbles-3d-menus-obscuring/) today to scratch an itch I had had for a while.



Its no secret that im a fan of Entity-Component systems having used various flavours of them for years. My particular favourite however is found in [Richard Lord's Ash Framework](https://www.ashframework.org/). I have used it on numerous projects including my [3-game prototype challenge](/posts/the-three-game-challenge/).



Ash Framework however is written for the Flash platform. Though there are ports for other platforms, no one has yet done one for Unity. It gets talked about on the [Ash mailing list](https://groups.google.com/group/ash-framework?hl=en) every now and then but often dismissed as either impossible or pointless as Unity already has an Entity framework built into it.

Well after a [recent discussion](https://groups.google.com/forum/?hl=en#!topic/ash-framework/NrC5dQyBRkY) I decided I wanted to have a go at it anyway. It turns out its actually not that hard to implement.

Starting off with [David Arno's .Net port of Ash](https://github.com/DavidArno/Ash.NET) I wrote two small classes that wrap the [Ash Engine](https://github.com/mikecann/UnityAshteroids/blob/master/Assets/Ash/Unity/AshGame.cs) and [Ash Entity](https://github.com/mikecann/UnityAshteroids/blob/master/Assets/Ash/Unity/AshEntity.cs).

Ash Entity is the key piece to the puzzle. You add it as a component to your game object:

![screenshot_003](https://www.mikecann.blog/wp-content/uploads/2014/07/screenshot_003.png)

It then checks to see which Unity components have been added or removed each frame and updates the Ash Entity reference. Its simple but it works! It even includes the default Unity Components so that means you don't need a base "AshComponent".

The AshEngine serves as the root of the hierarchy. So long as you place entities below it they will be able to find the engine. This makes it really easy and convenient to create scenes at design time and have them work when you hit play:

![screenshot_005](https://www.mikecann.blog/wp-content/uploads/2014/07/screenshot_005.png)

From that simple foundation I decided to have a go at porting the entire of Richard's Asteroids example over to Unity. I was surprised at how little issues I ran into. You can give it a play here:

[/projects/UnityAshteroids/UnityAshteroids.html](/projects/UnityAshteroids/UnityAshteroids.html)
**Use arrow keys to move and space to shoot.**

It all works surprisingly well. [The code](https://github.com/mikecann/UnityAshteroids) is really clean and very simmilar to the original.

The only changes I needed to make from the .Net port was to change some "internals" to "public" and changed the type of the update variable from double to float as Unity uses floats for everything not doubles.

Instead of manually defining the components in "EntityCreator" I use Unity's prefab system which makes it really nice and easy to edit properties in the inspector in the editor:

[![screenshot_004](https://www.mikecann.blog/wp-content/uploads/2014/07/screenshot_004-1024x685.png)](https://www.mikecann.blog/wp-content/uploads/2014/07/screenshot_004.png)

Then load them the usual Unity way using Resources.Load().

Systems are just pure code and added to the Engine as usual:

[code lang="csharp"]
public class Asteroids : AshGame
{
private EntityCreator creator;
private GameConfig config;

    void Awake()
    {
    	creator = new EntityCreator(this);
    	config = new GameConfig();

    	var size = Camera.main.ScreenToWorldPoint(new Vector2(Screen.width, Screen.height));
    	config.Bounds = new Bounds(Vector3.zero, new Vector3(size.x*2, size.y*2));

    	Engine.AddSystem(new WaitForStartSystem(creator), SystemPriorities.PreUpdate);
    	Engine.AddSystem(new GameManagerSystem(creator, config), SystemPriorities.PreUpdate);
    	Engine.AddSystem(new MotionControlSystem(), SystemPriorities.Update);
    	Engine.AddSystem(new GunControlSystem(creator), SystemPriorities.Update);
    	Engine.AddSystem(new BulletAgeSystem(creator), SystemPriorities.Update);
    	Engine.AddSystem(new DeathThroesSystem(creator), SystemPriorities.Update);
    	Engine.AddSystem(new MovementSystem(config), SystemPriorities.Move);
    	Engine.AddSystem(new CollisionSystem(creator), SystemPriorities.ResolveCollisions);
    	Engine.AddSystem(new HudSystem(), SystemPriorities.Animate);
    	Engine.AddSystem(new AudioSystem(), SystemPriorities.Render);

    	creator.CreateWaitForClick();
    	creator.CreateGame();
    }

}  
[/code]

The changes to the Asteroids code in general are minimal. I use Unity's components wherever possible, so things like Position and Movement become Transform and Rigidbody2D. Rendering is taken care of by Unity so I didn't need any RenderingSystem or Display component.

The code is available on GitHub for your perusal: [https://github.com/mikecann/UnityAshteroids](https://github.com/mikecann/UnityAshteroids)

I was actually surprised I was able to get this all working without any problems. There are improvements that could be made:

## Performance of AshEntity

AshEntity is the core to the whole thing and unfortunately it probably isn't the most performant. For each entity in the game it checks every frame to see if any components were added or removed. It doesn't do this in the best possible way so there is definitely room to improve this.

## Sugar

There is plenty of room for syntax sugar thanks to the superior C# language over Actionscript 3\. NodeList could be made generic and a generic ListIteratingSystem could be developed and perhaps even a way of eliminating nodes altogether. Also retrieving components from Ash Entity could be made simpler by removing the need to pass in the type param when calling Entity.Get<>().

## Finite State Machines

As the .Net port does not include Richard's FSM code I worked around the problem by destroying and creating new prefabs. This works quite well as it allows you to use the inspector to visually design the prefabs however a nice addition would be some editor tools and code for FSMs in Unity.

## Unit Tests

I copied over the .Net tests from David's port and got them running in unity using Unity Test tools without any problems however my Ash Unity code isn't tested. There isn't much of it but it probably should be covered.