Advice on how to properly document and track System - ComponentData mappings

Hello

We've started talking within the team about practices regarding documenting and tracking the different compositions of components we use. We're still early in development and it's not an issue so far, but I can easily picture a scenario where eventually you can get swamped by having a bunch of systems that do similar things or have components that have overlapping meanings later in the project when the number of components have greatly increased.

There are a bunch of ways you could keep track of everything in documents or spreadsheets, but I'm curious how other teams go about this. How do you sync with each other in order for everyone to keep track over which systems there are, and which system care about which components. Or is this one of those "if you need to extensively document you data, you're doing it wrong" scenarios?

Side-notes: Are there any external tools suitable for visualizing system - component relationships. Has there been any mention of such a tool for ECS down the road?

 

In my experience, performance and self-documentation are on two opposite ends of a spectrum; you can't have both.

As I've worked with ECS, I've found that my ComponentData needs to be as small as possible. Any time I try to combine multiple pieces of information, I find that I always regret it later and end up splitting it out anyway. Preventing refactoring ahead of time can greatly reduce these headaches up front. We use the new conversion system to group related ComponentData together on a single Proxy on a prefab (we call them blueprints to distinguish from classic MonoBehavior stuff)

Documentation is definitely a pain point. I'd love to know if there's a good tool for this, but it would be difficult to build as it would require heavy static analysis of code to do properly. Probably won't happen anytime soon because the APIs are still in flux.

 

This is a good question as for me, the hardest part of ecs is managing/understanding the ordering of systems and jobs.

I currently manually document basic properties of my systems for the purposes of ordering them all but I think an auto generated doc solution is going to be the best way. It's going to be very difficult to manually document systems and components and keep it up to date and in sync with code changes.
My very simple game already has ~70 systems and 80 components which I started and quickly gave up manually documenting in a spreadsheet. It's way too difficult but mostly I don't think it's necessary.

Thanks to the way ecs is structured, it's going to be much easier to just auto document all your systems, components, archetypes, chunk allocations and whatever other data you could want.
You'll get much better and always accurate analysis and won't have to rely on everyone keeping docs up to date.

 

Haven't really gotten into the conversion system yet, gonna get grips on that now since we're just upgrading to 2019. But that sounds like a reasonable way to approach it, to make it easier to work with in the editor and abstract the actual components away from whoever is fiddling with the prefabs. I'll probably take inspiration from that idea, thanks for sharing!

This is my naïve assumption as well without thinking to much about it. Seeing as it is very explicit in the ComponentSystems which components they react upon (disregarding manual fetching of component data through the EntityManager). I'm not expecting anything like this soon since there are more important stuff to worry about, but I hope this is something being considered down the road.