Fix: #50 Updated Documentation #194
Conversation
|
Sorry for not posting a draft PR first, I missed that while going through the instructions but I have implemented all the required tasks. |
|
There will be more ongoing PRs so I will merge whichever reaches my expectations the most. |
There was a problem hiding this comment.
Overall looks like an improvement. However, I was expecting a bit more of a "glow up" to the overarching look & feel of the documentation page. Perhaps a different style.
And it would be good if you link a rendered view of these docs so we can review it aesthetically
| local Position = world:component() :: jecs.Entity<Vector3> | ||
| local Velocity = world:component() :: jecs.Entity<Vector3> |
There was a problem hiding this comment.
I would use jecs.Id to represent component types. They are more terse and actually a bit more correct.
| local Position = world:component() :: jecs.Entity<Vector3> | ||
| local Velocity = world:component() :: jecs.Entity<Vector3> | ||
| ``` | ||
|
|
||
| ### Entity Creation | ||
| ```lua | ||
| -- Matter | ||
| local entity = world:spawn() | ||
|
|
||
| -- Jecs | ||
| local entity = world:entity() | ||
| ``` | ||
|
|
||
| ### Adding Components | ||
| ```lua | ||
| -- Matter | ||
| world:insert(entity, Position, { x = 0, y = 0, z = 0 }) | ||
|
|
||
| -- Jecs | ||
| world:set(entity, Position, Vector3.new(0, 0, 0)) | ||
| ``` | ||
|
|
||
| ### Querying | ||
| ```lua | ||
| -- Matter | ||
| for id, pos, vel in world:query(Position, Velocity) do | ||
| -- Process entities | ||
| end | ||
|
|
||
| -- Jecs | ||
| for id, pos, vel in world:query(Position, Velocity) do | ||
| -- Process entities | ||
| end | ||
| ``` | ||
|
|
||
| ## Major Feature Differences | ||
|
|
||
| ### Relationships | ||
| Jecs provides built-in support for entity relationships: | ||
| ```lua | ||
| -- Jecs only | ||
| world:add(child, pair(ChildOf, parent)) | ||
| ``` | ||
|
|
||
| ### Component Traits | ||
| Jecs allows adding traits to components: | ||
| ```lua | ||
| -- Jecs only | ||
| world:add(Position, Networked) | ||
| ``` | ||
|
|
||
| ### Query Caching | ||
| Jecs provides explicit query caching: | ||
| ```lua | ||
| -- Jecs only | ||
| local cachedQuery = world:query(Position, Velocity):cached() | ||
| ``` | ||
|
|
||
| ## Migration Steps | ||
|
|
||
| 1. **Update Component Definitions** | ||
| - Replace Matter component tables with Jecs components | ||
| - Add type annotations for better type safety | ||
|
|
||
| 2. **Update Entity Management** | ||
| - Replace `spawn()` with `entity()` | ||
| - Update component insertion syntax | ||
|
|
||
| 3. **Update Queries** | ||
| - Review and update query usage | ||
| - Consider using query caching for performance | ||
|
|
||
| 4. **Add Relationships** | ||
| - Replace custom parent-child implementations with Jecs relationships | ||
| - Use built-in relationship features | ||
|
|
||
| 5. **Update Systems** | ||
| - Review system implementation patterns | ||
| - Consider using component traits for better organization | ||
|
|
||
| ## Performance Considerations | ||
|
|
||
| 1. **Query Performance** | ||
| - Cache frequently used queries | ||
| - Use appropriate filters | ||
|
|
||
| 2. **Component Storage** | ||
| - Use tags for boolean states | ||
| - Consider component data structure size | ||
|
|
||
| 3. **Relationship Usage** | ||
| - Be mindful of relationship complexity | ||
| - Use built-in relationships when possible | ||
|
|
||
| ## Getting Help | ||
|
|
||
| Need help migrating? | ||
| - Join our [Discord server](https://discord.gg/h2NV8PqhAD) | ||
| - Check the [API documentation](../../api/jecs.md) | ||
| - Open an issue on [GitHub](https://github.com/ukendio/jecs/issues) |
There was a problem hiding this comment.
I am very much against the idea of having pages that suggests that you should migrate away from existing libraries like Matter. Those are still well maintained and supported.
|
beep boop im a robot 🤖🤖🤖🤖 |
|
HI, I have created a new PR #195 for the requested changes, please review those. |
This pull request fulfills the task of adding comprehensive documentation to the Jecs ECS repository. The following changes have been implemented:
Overview Section: A dedicated overview section has been created, providing a concise project description and outlining key features and functionalities.
Installation Instructions: Detailed installation instructions have been added, covering prerequisites, step-by-step guides for Wally, npm, and standalone installation methods, including configuration instructions where applicable.
Usage Examples: Comprehensive usage examples have been provided, demonstrating core functionalities with explanations of main components (entities, components, queries, and relationships). Examples are included for both Luau and TypeScript.
Contributing Guidelines: A comprehensive section on contributing has been added, including guidelines for code style, commit messages, development setup, issue reporting, pull request submission, and a code of conduct.
FAQs Section: A FAQs section has been compiled, addressing common issues and frequently asked questions.
License Information: The MIT license information has been added to the repository.
README Update: The
README.mdfile has been updated to reflect all the changes, providing a clear and concise overview of the project and its documentation.All documentation is written in Markdown and includes images where appropriate to enhance clarity and understanding. The documentation is structured for ease of navigation and is designed to be easily maintainable.