How to improve the ECS/specs situation


I’m writing a game in Rust for fun. It seems specs is the accepted ‘gold standard’ ECS implementation in Rust. However, I have a few concerns with it:

  • Hidden limits – for example, the limit of 220 entities on 32-bit systems. Sure, you could argue that if you have that many entities you’re doing it wrong, but it’s the principle of the thing: unstated limits are somewhat alarming. That’s why the Rust documentation explicitly lists any possible panics for a function.
  • Less-than-stellar documentation. Apart from the hidden pitfalls as mentioned above, specs is very, very opaque for people who come to ECS fairly new (I speak from experience) and it’s inner workings aren’t well explained either, which makes it hard to understand and extend.
  • Use of unsafe. A quick grep suggests that there are over 100 uses of unsafe in specs. I’m not an expert and perhaps it’s all perfectly fine in the end, but again, I’m writing an MMO and I’d prefer to avoid potential vulnerabilities. And 100 uses of unsafe is a lot of room for that.

I suspect that problem #2, in particular, is causing ecosystem fragmentation (just search ‘ecs’ on for an example of what I’m talking about). People who are unable to understand specs (like myself) go off and write their own ‘simple’ ECS (like myself) and publish it (like myself), causing confusion and drawing off programmers who would otherwise be improving specs and helping newcomers.

I wish everyone could use specs. It’s a marvel of engineering (IMHO) and I’ve referenced it many times for ideas while building my own ECS. I’d be willing to switch to specs – and to help document it – if I only understood it. But I don’t, primarily because the documentation is insufficient!! Chicken and egg.

Currently, I’m considering writing a tutorial on How to Write an ECS, to help people understand ECS implementation without rolling their own and causing further fragmentation. But Specs is right there, if only I and everyone else could use it. What to do?


As for fragmentation, I suspect that ECS are the gamedev space equivalent of a web framework: easy to think “let me just write my own, I’ll do it nicer than all the others”.

#1 and #2 can be resolved by contributing to the documentation.

As for #3, you should check if the uses of unsafe are properly explained. If not, an audit and a push to remove unneeded/unsafe unsafe could be done a la actix-web (but with less drama, preferably).


I don’t know much about specs but @torkleyy and @kvark might be interested in your feedback and/or brainstorming improvement ideas (hope they don’t mind me cc’ing them).


Thanks for the cc! @propguy The docs certainly aren’t as good as the docs of similar big crates, but they’ve already improved a lot. I’ve also put a lot of effort into writing a book, did you see that? I’m currently not working on it, but I sure can answer some questions (and there’s always somebody around on Gitter). I would appreciate more docs, but I rarely get PRs for that.


I meant to remove that hidden limit months ago, but work on it stopped IIRC (there’s a PR for generically layered bit sets for hibitset, not finished though).


Thanks @torkleyy! I have seen the book, and it was a big help when getting started with ECS. I’d love to work on the documentation, if I could ask questions occasionally to clarify my understanding of how some things work. Would you mind if I PM’d you with some questions?


Sure, please PM me for any questions you have. Note though that I’m only checking every couple of days, for a quicker response please contact me on Gitter or via