Warning: If you are new to Entity Component Systems, I would highly recommend Adam Martin’s blog series on them, he goes into great detail about what problem they solve, and what is required to implement them. I’m not going to discuss what Entity Component Systems are in this blog post, so you may want to read his series first.
Doing some more fun time with game development, I wanted to use a Entity Component System Library for my my next project. Since I’m quite enamoured with Clojure at the moment, I went looking to see what libraries currently existed to facilitate this.
I found simplecs, which is quite nice, but I wanted something that was far more lightweight, and used simple Clojure building blocks, such as defrecord and functions to build your Entities, Components and Systems. To that end, I wrote a library called brute, which (I think) does exactly that.
I wrote a Pong Clone example application to test out Brute, and I feel that it worked out quite well for my objectives. Below are a few highlights from developing my example application with Brute that should hopefully give you a decent overview of the library.
As we said before, we can use defrecords to specify the Components of the system. For example, the components for the Ball:
(defrecord Rectangle [^com.badlogic.gdx.math.Rectangle rect ^Color colour]) (defrecord Ball []) (defrecord Velocity [^Vector2 vec])
We have a:
- Rectangle, which defines the position of the Ball, the dimensions of the rectangle to be rendered on screen, and its colour.
- A Ball component as a marker to delineate an Entity is a Ball.
- Velocity to determine what direction and speed the Ball is currently travelling.
As you can see, there is nothing special, we have just used regular old defrecord. Brute, by default will use the the Component instance’s class as the Component type, but this can be extended and/or modified (although we don’t do that here).
Therefore, to create the ball in the game, we have the following code:
(defn create-ball
"Creates a ball entity"
[]
(let [ball (e/create-entity!)
center-x (-> (graphics! :get-width) (/ 2) (m/round))
center-y (-> (graphics! :get-width) (/ 2) (m/round))
ball-size 20
ball-center-x (- center-x (/ ball-size 2))
ball-center-y (- center-y (/ ball-size 2))
angle (create-random-angle)]
(e/add-component! ball (c/->Ball))
(e/add-component! ball (c/->Rectangle (rectangle ball-center-x ball-center-y ball-size ball-size) (color :white)))
(e/add-component! ball (c/->Velocity (vector-2 0 300 :set-angle angle)))))This creates a Ball in the centre of the playing field, with a white rectangle ready for rendering, and a Velocity of 300 pointing in a random direction.
As you can see here, creating the entity (which is just a UUID), is a simple call to create-entity!. From there we can add components to the Entity, such as an instance of the Ball defrecord, by calling add-component! passing in the entity and the relevant instance. Since we are using the defrecord classes as our Component types, we can use those classes to retrieve Entities from Brute.
For example, to retrieve all Entities that have Rectangle Components attached to them, it is simply a matter of using get-all-entities-with-component
(doseq [entity (e/get-all-entities-with-component Rectangle)]
(let [rect (e/get-component entity Rectangle)
; do things with the rectangle, such as render it.
))From there, we can use get-component to return the actual Component instance, and any data it may hold, and can perform actions accordingly.
Systems become far more simple in Brute than they would when building an Entity System architecture on top of an Object Oriented language.
Systems in Brute are simply a function, that takes a delta argument, for the number of milliseconds that have occurred since the last processing of a game tick. This leaves the onus up to the game author to structure Systems how they like around this core concept, while still giving a simple and clean entry point into getting this done.
Brute maintains a sequence of System functions in a registry, which is very simple to add to through the appropriately named add-system-fn! function.
Here is my System function for keeping score:
(ns brute-play-pong.scoring)
(defn process-one-game-tick
"Scoring, process one game tick"
[delta]
; ... do things related to keeping score
)Here we add it to the registry:
(s/add-system-fn! sc/process-one-game-tick)
Finally, to call all registered system functions are fired, by using the function process-one-game-tick, which calls all registered System functions in the order they were registered – and in theory, your game should run!
(s/process-one-game-tick (graphics! :get-delta-time))
For more details on Brute, check out the full API documentation, as well as the Pong clone sample game that I wrote with the great play-clj framework (that sits on top if libGDX).
As always, feedback is appreciated.