[Library] tiny-ecs - Fast Simple Entity Component System

[bakpakin]

Hi, love the library, thanks for your hard work. I'm trying to filter systems in tiny.update(), I'm not sure exactly what kind of filter to pass in the third argument. I've tried things like tiny.filter("componentThatSystemIWantFiltersFor") or passing the actual system's filter but nothing seems to be working.

Edit: Never mind, I got it to work by passing the same filter as the system. Pretty sure I just confused myself.

Good that you solved the problem, but just to be explicit - from the doc:

tiny.update (world, dt, filter)
Updates the World by dt (delta time). Takes an optional parameter, filter, which is a Filter that selects Systems from the World, and updates only those Systems. If filter is not supplied, all Systems are updated. Put this function in your main loop.

To elaborate, Filters work exactly the same in tiny.update as they do in Systems. Filters are just functions of the following type:

Code: Select all

local function myFilter(system, entity)
	-- do stuff
	
	-- Return truthy to be run or included, falsy to be skipped or excluded
	return true
end

When update is called with a Filter, the world object is passed instead of a system to the first argument. If the filter returns false for a system, that system is skipped. Otherwise, the system is updated.

Hope that helps for anyone in the future.

[fedkanaut]

Cool, thanks for clarifying.

[phobos2077]

Has anyone tried using this library properly with STI? I'm still trying to wrap my head around this. Because STI holds all game objects and tiles and draws them, acting like a primary object collection. But tiny-ecs does exactly the same with it's world object. I looked at the first example project by bakpakin which does indeed use STI, but I didn't liked how it uses STI to only draw the tiles and custom code (using systems) to draw everything else.

I'm trying to make a foundation for my game engine with following:
- Use Tiled as a level editor.
- After level is loaded into the actual game, everything should remain dynamic (even tiles). I don't want to split objects into "static" (stuff drawn in the editor) and "dynamic" (custom layers, etc.). I want levels created in Tiled to act just like a starting point for the game, so I have freedom to modify anything at runtime.
- Use ECS to construct my game entities as a table of components (I have a little experience with Unity, and I liked the ECS approach there), where every component is an instance of a class.
- All update happening in update callback and all drawing in draw callback, not everything in update.
- Use bump for collision checking and response.

So If I use all 3 libraries (tiny-ecs, bump and sti) I end up with 3 "worlds" each with full sets of objects that I will need to sync. That sounds like a bad design right there


PS: A bit of a critique: I think "tiny" in the name is misleading. The scope of this library is nowhere near "tiny" IMO. I think it would be good idea to split it into actual ECS implementation (systems, components and filters) AND separate ecs-world module (container for everything, with "update" method, caches and stuff). I might still use this library as a whole because structure it provides is good, but it doesn't follow the single responsibility principle.

[shakesoda]

the scope of the library is exactly that which is most useful.

anyway, STI doesn't know squat about your game world, it just loads the map. You can load up the objects into your tiny world and update the data in STI's layers using a system, as you'd do if you weren't using STI. Same goes for bump. The "master" world should be the one the ES has, and you just update the data for rendering (STI) and physics (Bump) as needed.

[bakpakin]

PS: A bit of a critique: I think "tiny" in the name is misleading. The scope of this library is nowhere near "tiny" IMO. I think it would be good idea to split it into actual ECS implementation (systems, components and filters) AND separate ecs-world module (container for everything, with "update" method, caches and stuff). I might still use this library as a whole because structure it provides is good, but it doesn't follow the single responsibility principle.

Yes, it is not exactly tiny, especially compared to some other solutions in this forum like knife.system and Lua micro-modules in general. But it really isn't that big, and the fact that it is in one file means it easy to copy-paste around. Everything I put in the library were things that I found myself writing a lot, or features that are common to ECS. It is small enough to be added to a project with little friction, but large enough in scope to base a project around (IMHO). Compared to most solutions of the same scope, I think it is significantly smaller.

I agree that certain things (especially filters) could be broken off into their own libraries.

[airstruck]

The scope of this library is nowhere near "tiny" IMO [...] I might still use this library as a whole because structure it provides is good, but it doesn't follow the single responsibility principle.

As far as I can tell (someone please correct me if I'm wrong), this library provides two major benefits. One is a convenience: you can have your entities list automatically sorted in different ways for different systems. The other is a potential optimization: Tiny will maintain a cache of relevant entities for each system, so that systems don't need to look at and reject irrelevant entities. I say potential because of course there is some overhead associated with maintaining the cache, and you're not necessarily going to pick up more speed from caching than you'll lose from that overhead in every scenario (for example, when most of your systems affect most of your entities).

It might be a good idea to evaluate whether you need these particular benefits. For example, you might decide that you only ever need to sort your entities for drawing; in that case you can easily do it outside the ECS. Or you might determine that you can hit your baseline performance goals without the caching behavior, or that you actually get better performance from not caching. In that case you don't need a lot of the complexity associated with manually invalidating the cache and so on. You also might decide you don't really want another "world" and would prefer a more "immediate mode" style of applying your systems.

Lua's flexibility allows for pretty decent ECS-style designs without another layer of abstraction. Entities can be tables, components can be fields, and systems can be functions. Instead of filters, you can simply wrap the body of your system function with a conditional. If you don't need caching, there's no real need for separate filters. Of course you could still write them as separate functions if you want to. Instead of adding your entities and your systems to a world, you can just apply all your systems to all your entities inside a loop in your update or draw callback, immediate-mode style.

In other words, all you actually need to get the same structure this library provides is a small amount of discipline and plain old Lua language constructs. I wouldn't use it for structure alone, I'd use it based on its own particular merits, like those mentioned above or any others I missed. I'm not trying to discourage anyone from using this library, just suggesting to weigh the added complexity against the benefits, and make sure it's actually doing something for your particular use case that a no-library solution wouldn't do.

[phobos2077]

That's exactly why I think single responsibility principle is good. If you split your solution into separate modules, each designed for specific problem, there is a better flexibility in how others can use your library. Of course you can also provide single-file build as well for someone who wants it.

From my perspective as a beginner, I don't want yet to use complex stuff like world and caching (because I lack experience, I don't know yet if I will need it or not), I just need the ECS structure. Other thing that slightly put me of is filters for systems. I think it might be an excess overhead to add flags like "isDrawingSystem" and then every time query for systems with this flag. Might be easier and more transparent to just specify 2 lists for "update" and "draw" systems and iterate over them directly.

Do I understand correctly that the result of filters are cached? So for example in weregoat game, Lua don't evaluate "updateSystems" filter function for every system EVERY frame?

[bakpakin]

Results for filtering entities are cached, but results for filtering systems are not - the hope being that you have far fewer systems than you have entities.

The filtering for systems was a bit of a kludge I added so that I could I easily just add systems to the world and not to a specific list. There are other solutions that avoid this problem, such as overriding love.run and ordering your systems such that drawing happens after update. I honestly prefer this, but some people might not want to mess with love.run.

In response to airstruck, I would say this library at this point really offers more organizational benefits than performance benefits.
A simple loop-over-all-entities works very well for many applications, but for something more complex, it can be easier to just worry about the per system logic and have something else take care of the iteration.

Lastly, if you really think that caching is killing performance, you can turn it off with the nocache option per system. I honestly doubt it, though.

[airstruck]

A simple loop-over-all-entities works very well for many applications, but for something more complex, it can be easier to just worry about the per system logic and have something else take care of the iteration.

I'm not really seeing it, is there an example of that posted somewhere? It seems to me that adding all systems to a world and calling world:update is going to be just as much trouble and about the same amount of code as writing a for-loop that applies all the systems. Of course the "immediate mode" solution is also quite flexible, it alleviates the need for differentiating between "draw" and "update" systems (or any other kind of system the user wants); it makes it very easy to accept additional arguments, or you could use return values to do things like "apply this system or that system or the other system," or you could still put all your systems in a table named "world" if you want to; you can apply all systems to each entity before processing the next (so you can do draw-pipelining stuff, for example), etc. The flexibility you get from applying systems like this can easily outweigh ease-of-use of the "world" approach in a complex application (assuming world approach is actually easier to use; not really convinced without looking at an example).

Lastly, if you really think that caching is killing performance, you can turn it off with the nocache option per system. I honestly doubt it, though.

I'm not saying it kills performance, although I did get slightly better performance out of a no-cache no-library solution over Tiny on some benchmarks that were supposed to represent somewhat realistic situations. That was a while ago, though, and Tiny has been updated since. What I meant was that the caching behavior necessitates some other complexities, like the need for manual invalidation when giving or taking away components on the fly, the need for "first-class" entity filters, and so on. This was more in response to phobos' suggestions about separation of concerns. I guess my point was that allowing for the possibility of caching (even if you can turn it off) necessitates a lot of complexity, so if someone's not sure the cache is actually going to make or break their game's performance that might be something to think about.

[phobos2077]

It would be awesome to be able to easily update systems without using the "world" but with an advantage of entity filters/cache. I guess it's possible to just create world with systems and entities, but iterate via system's update method (not world:update).