Ashley and Box2D Tutorial – ECS, Physics and Collisions

Sharing is caring!

Ashley and Box2D Tutorial

In this tutorial, we will create a simple game base using Ashley and Box2D. Ashley is an Entity System that allows us to create entities from a set of components such as an image, a position etc. More information on Ashley can be found on the Ashley wiki and information on Entity Systems can be found on  www.gamedev.net.  Box2D is a physics engine allowing us to create realistic physics in our game such as falling objects, explosions and collisions.

Ashley and Box2D – Project setup

The first step is to create a project using the gdxsetup.jar which can be downloaded from github.com/libgdx/libgdx/wiki/Project-Setup-Gradle. Run the jar file and set the project details making sure to include the Box2D and Ashley extensions. The settings I used are shown below:

Note: I have only created a desktop application as this is a tutorial and won’t ever be run on android, ios or gwt. If you add the android platform you will have to place your images in the android assets folder instead of the desktop assets folder.

Now we need to import the project into Eclipse. Go to File > Import then select Gradle > Gradle Project. Find the project root (In my case it was C:/Users/darkd/tutorial/ashbox) and select Build model. Select all the projects and click import.

Ashley and Box2D – Set up base structure

Now that we have our project setup ready we can start on the code. The first thing we want to do is change the ashbox class to remove the example code and replace it with our own.

Right we now have our game setup to change to the GameScreen as soon as it loads. Now we need to add the GameScreen.

For now, that’s all we need in our GameScreen. We will come back to this once we have all our Components, Systems, Logic and Listeners in place.

Ashley and Box2D – Creating Components

Components in the Ashley ECS are like containers for a single set of specific data. In this example, we will be using a component called TransformComponent. This component will be solely used to store data relating to the position, rotation and scale of an entity. This component can be added to any Entity that has a position, rotation and scale such as our player or an enemy.

Here are all of our components:

That’s all the components needed for this part of the tutorial. Later we will extend this to render with textures instead of the default debug renderer for box2d.

Ashley and Box2D – Creating Systems

Ashley systems are the logic of our game and each system will focus on a specific area of logic such as rendering images, moving bodies, changing states etc. In this tutorial we will be using 4 systems; Collision, Physics, PhysicsDebug and PlayerControl.

Let’s start with the PlayerControlSystem:

The PlayerControlSystem uses the Body and State components to determine if the player is able to move and then uses inputs to control the character movement by applying forces to the body. At the moment the Player Component is solely used to identify the player entity however it can be updated later to include player exclusive data.

Now let’s move on to the PhysicsSystem that updates our Box2d world then updates our local components.

Next, we have the PhysicsDebugSystem which takes the Box2D world and renders it:

Finally, we Have our CollisionSystem

We now have all the systems in place. Next, we will create the Input Controller.

Ashley and Box2D – Creating the Controller

The Input controller is a standard implementation of an input processor with some flags for our PlayerControlSystem to access.

Ashley and Box2D – Contact Listener

The Contact Listener is an implementation of the Box2D Contact Listener with methods to allow us to update the CollisionComponent of the entities that collide.

Ashley and Box2D – Implementing the Engine

Now we can finally implement the engine supplied by Ashley in our GameScreen.

Now, everything is in place and can be tested by running the game. You should be able to use the left and right keys to move left and right and the up key to jump. The console should output a string saying what type of entity it has collided with. For now there is only the Scenery however we can add an enemy to the game later and it will display enemy when hit as long as the enemy entity contains the TypeComponent as is set to ENEMY.

Ashley and Box2D – Adding a Rendering System

In order to start Rendering with real textures instead of the Box2D debug renderer we’re going to have to add a component to store our textures. So lets start by making a TextureComponent.

Usually, when creating games with lots of images you will pack the images into an atlas which is loaded by an asset manager and its simpler to get a TextureRegion then it is to get a Texture and a SpriteBatch will accept both a Texture and TextureRegion for most of it’s draw methods.

Now we have our component for the texture let’s make the system for rendering the textures.

This System loops through all Entities with a TextureComponent and a TransformComponent but it additionally has a Comparator use to sort the images. This Comparator sorts the Images out by the Z index of the Vector3 in the TransformComponent. This allows us to set what order entities will be drawn in. So our player can be drawn on top of scenery and our foreground can be drawn on top of that. The ZComparator code is:

We have the system in place, it’s now time to update our GameScreen to implement our render system. Update the show method to match this code:

Now the Engine knows about the RenderSystem but our created Entities don’t so let’s update those now. In the createPlatform method add this code:

In the createPlayer method add:

In the createFloor method add:

And finally, the code to create the TextureRegion:

 

Ashley and Box2D – Benefits

Using Ashley and Box2D together can help organise your code by keeping all the entities, components and logic systems separate. This can be achieved in normal OOP coding but becomes more difficult as you get more and more systems and entities.

With Ashley and Box2D you don’t use inheritance so entities that would like to inherit from multiple superclasses can’t be done in normal OOP programming but with Ashley and Box2D being component based you can just add the components from multiple systems.

Allowing modding becomes easier as you can create entities with groups of components which can easily be stored as a JSON string

Ashley is simple to learn compared to other ECS systems.

Ashley and Box2D – Drawbacks

Ashley isn’t the fastest ECS system available and can slow down your game especially on smaller devices when using lots of entities even with pooling.

Adding Ashley and Box2D to your game increases it’s size and isn’t needed for small or simple games.

 

A zipped version of the project can be found on stormyvids

Sharing is caring!