Xile - Entity Component System Framework

Hey everyone, Its been quite a while since I last posted but after seeing your recent discussions of component based architecture I thought I’d post my attempt at one :slight_smile:

I originally started out with the aim of creating some simple tile-map games but after a few diversions later I ended up writing this framework with some tile-map experiments instead :D.

The framework aims to offer “out of the box” Entity Component System functionality with minimal setup see usage instructions.

I have also written two example projects (they’re a little rough around the edges)

  • Asteroids Game - The controls are a bit crude but its more about the code than it is gameplay. The entire game is composed (put together) in the main tab and it can be changed by simply adding or removing Entities and Systems in the setup function.
  • Tilemap Editor - This is a bit of an experiment really but I thought it might still be useful to someone. It mainly demonstrates usage of the TileMesh object which can run at about 100x100 tiles at 60fps (in my limited testing).

I’m hoping the code is relatively self documenting but I’m sure it could probably do with some more comments in places, so if your not sure about anything please ask! Also do expect bugs :wink:

You can download everything from GitHub (auto installs are under installation heading):


Looking forward to hearing what you think :smiley:

Extra Info

The architecture is inspired by these fantastic blog posts about Entity Framework architecture by Richard Lord and his framework called Ash which is written in ActionScript 3.0.



Similar to the description in the “What Is an Entity Framework” post there are four main object types and an “Engine” which tracks all added Entities and Systems (see diagram above the Conclusion). You can see an example of registration here.

  • Entity
    • Container for related components (any “thing” in your game for example Player, Enemy, Treasure Chest )
  • Component
    • Game Data Object (attributes of Entities for example Position, Health, Movement)
  • System
    • Game Logic Object (processors which do the work in the game like Rendering, Collisions, Movement)
  • Node
    • Automatically generated component containers used to access components within Systems.

Beautifully presented and documented, thank you. Even with something to work from, that must have taken a lot of time and effort! Thank you for sharing it.

I found the framework very impressive, but impossible to really assess without developing a reasonably large project in it. I would guess that familiarity with this style of software would help a lot, too (I am not professionally trained, so I find the component terminology complex).

I won’t use it myself, because the framework is very large, at about 2500 lines; the concepts and usage take some getting used to (what I like about Lua is that it keeps things really simple); and even a basic game like asteroids appears to take a further 700 lines of code, in 19 tabs. I know you deliberately chose a simple game, but I suspect most users (like me) aren’t going to write huge games, and would think “I can write a game like Asteroids in around 100 lines, why use something that makes it much more complex”.

But this is not a criticism. I am not a professional, and I don’t write really big projects, so don’t be put off by anything I said. Let’s see what the serious professionals think.

Also, if there are people on the forum who would like to learn how to use component architecture, which could be useful in a software career, this framework could be a good learning tool.

Thanks again. It is truly impressive. =D>

@XanDDemoX thanks for sharing. Can certainly help understanding components architecture requirements.
Could you post the whole auto-install into one single project file? It is then easier to get it from github.

@Jmv38 if you click the links in the front page readme (under “installation”), that takes you to a raw page of the whole project that you can “paste-into-project”.

ducky Entity Component System Framework, but i wonder if there are more code lines than the orginal game?

Thanks everyone for your comments so far! :slight_smile:

@Ignatz I can see where your comming from and agree, getting used to the concepts is a must and it is quite large in terms of total lines but most tabs are quite small. But some of the code in there is the result of some experiments and could probably be cut down. Check out the Query tab its a chainable data helper.

    local objs = {
    local tbl = Xile.from({1,2,3})
                        return objs[i]
                        return o.name ~= "bob"
    Xile.from(tbl):map(function(o) return o.name end):each(print)

I do also agree that if your writing a 100 line project this might not be for you. But if you intend the project to be longer lived then a framework like this could help with maintaining and extending the project later.

I forgot to mention the framework also uses a concept called “Depenency inversion” quite prevalently among other SOLID principals.

So that means it (attempts) to promote reusability, separation of game logic and display and encourages small single purpose objects ( and lots of them :wink: ).

In theory (with an appropriate approach) you could change how the game looks entirely without touching the logic and add new or remove existing features with a reduced risk (hopefully) of breaking others :slight_smile:

Edit: I’ve made a few edits to the first post to give some more information :slight_smile:

@XanDDemoX - can you give us an idea of how relevant this framework (or others like it) would be for professional projects? Are these frameworks commonly used now? How widely is SOLID used?

I’m thinking that some of our younger members might be interested in learning how to use it, if it provided them with valuable experience for the future. Otherwise, they are likely to decide it looks like too much hard work.

@Ignatz It certainly will be similar to tools that would be used in commercial game development in an “under the hood” sence allthough simplified and lacking fancy editors :p.

Entity component systems are used widely in commercial game development I believe. Engines such as Unity and many others use component architectures (or adaptions of) as a core philosophy.

Unity is fantastic by the way its been used to make some AAA games, and it has free edition :slight_smile:

SOLID is a set of guidelines used very widely in commercial software development, it makes up some of the core principals of Object Oriented approaches its well worth knowing for any aspiring programmer among other topics :slight_smile:

Edit: Id also love nothing more than if others can learn from it :slight_smile: I’m looking to improve both the code and documentation over time :slight_smile:

Well, I hope some people take the opportunity to learn about it, to make your effort worthwhile. :slight_smile: