Clearer Documentation and Working Example

[MorganeLeCaignec]

Hello! This is great, but I wanted to give some feedback on my initial impressions of this repo's documentation and how I think it could be improved.

The existing documentation is good, but could be a bit more consistent. Currently, the documentation shows snippets of code for specific elements but omits others, and the examples used in the documentation don't really connect.

For example, when I first downloaded this to try it, I started copying/modifying things from the docs as I read them, but things feel out of order. The first snippet shows a new Hero() and new health(10) which are not explained and never declared elsewhere in the docs.

Maybe the entities and components need to be explained first?

In each section where we declare components, entities and systems, it would be useful to show how they are added/removed from the engine (even if that has already been declared elsewhere), to avoid scrolling back to the engine section multiple times.

I think this also needs a full working example that showcases all (or most) of the library and that can quickly be copied and played with for a new user. As a new user, I wasn't sure at first how to setup everything together and how to make the game loop.

A working example would also provide a nice reference for the docs, a user would be able to follow the docs alongside the working example and be able to play with it directly.

[mayakwd]

Thank for such great feedback, I'm working on some samples and how-to/tutorial-like documentation.

[MorganeLeCaignec]

Thank you for your response!

Another zone of uncertainty in the docs :
The systems are not very clear, and some of example code might not be correct.

the code
protected prepare(): void { for (const entity of this.entities) { this.entityAdded(entity); } }
for example shows an error in my IDE, TS2345: Argument of type 'Entity' is not assignable to parameter of type 'EntitySnapshot'.   Type 'Entity' is missing the following properties from type 'EntitySnapshot': _previous, current, previous, and if I throw a console.log in entityAdded showing the current object, it returns undefined which means entity isn't passed properly to entityAdded somehow.

I'm also confused by ReactionSystem and IterativeSystem, a full example might help for this. I'm not certain what they do exactly differently and how i'm supposed to implement them.
For example, it wasn't clear that I needed the prepare() function for entityAdded to run, and as far as I know entityRemoved is never called in the example (I tried removing an entity that my Query would return and the system never calls entityRemoved). A sort of lifecycle of the system would be useful, ie. what functions are called when, in what order.