Merge 96bed9bd7e into 6a5832db20

Add Guides

docs/.vitepress/config.mts

@@ -15,6 +15,13 @@ export default defineConfig({
 
 		sidebar: {
 			"/api/": [
+				{
+					text: "Introduction",
+					items: [
+						{ text: "Getting Started", link: "/learn/overview/get-started" },
+						{ text: "First Jecs Project", link: "/learn/overview/first-jecs-project" },
+					]
+				},
 				{
 					text: "API reference",
 					items: [
@@ -22,7 +29,7 @@ export default defineConfig({
 						{ text: "World", link: "/api/world" },
 						{ text: "Query", link: "/api/query" },
 					],
-				},
+				}
 			],
 			"/learn/": [
 				{
@@ -43,17 +50,41 @@ export default defineConfig({
 					],
 				},
 				{
-					text: "FAQ",
-					items: [{ text: "How can I contribute?", link: "/learn/faq/contributing" }],
+					text: "API Reference",
+					items: [
+						{ text: "jecs", link: "/api/jecs"},
+						{ text: "World", link: "/api/world"},
+						{ text: "Query", link: "/api/query"}
+					]
 				},
+				{
+					text: "Resources",
+					items: [
+						{ text: "Guides", link: "/learn/resources/guides" }
+					]
+				},
+				{
+					text: "Contribute",
+					items: [
+						{ text: "How Can I Contribute?", link: "/contributing/guidelines" }
+					]
+				}
 			],
 			"/contributing/": [
+				{
+					text: "Introduction",
+					items: [
+						{ text: "Getting Started", link: "/learn/overview/get-started" },
+						{ text: "First Jecs Project", link: "/learn/overview/first-jecs-project" },
+					],
+				},
 				{
 					text: "Contributing",
 					items: [
-						{ text: "Contribution Guidelines", link: "/learn/contributing/guidelines" },
-						{ text: "Submitting Issues", link: "/learn/contributing/issues" },
-						{ text: "Submitting Pull Requests", link: "/learn/contributing/pull-requests" },
+						{ text: "Contribution Guidelines", link: "/contributing/guidelines" },
+						{ text: "Submitting Issues", link: "/contributing/issues" },
+						{ text: "Submitting Pull Requests", link: "/contributing/pull-requests" },
+						{ text: "Code Coverage", link: "/contributing/coverage" },
 					],
 				},
 			],

docs/contributing/coverage.md

@@ -0,0 +1,17 @@
+# Code Coverage Reports
+
+All of the code coverage reports can be found here:
+
+[Overview](/jecs/coverage/index.html){target="_self"}
+
+[jecs.luau](/jecs/coverage/jecs.luau.html){target="_self"}
+
+[ANSI](/jecs/coverage/ansi.luau.html){target="_self"}
+
+[Entity Visualiser](/jecs/coverage/entity_visualiser.luau.html){target="_self"}
+
+[Lifetime Tracker](/jecs/coverage/lifetime_tracker.luau.html){target="_self"}
+
+[Testkit](/jecs/coverage/testkit.luau.html){target="_self"}
+
+[Tests](/jecs/coverage/tests.luau.html){target="_self"}

docs/contributing/guidelines.md

@@ -1,3 +1,21 @@
-## TODO
+# Contribution Guidelines
 
-This is a TODO stub.
+Whether you found an issue, or want to make a change to jecs, we'd love to hear back from the community on what features you want or bugs you've run into.
+
+There's a few different ways you can go about this.
+
+## Creating an Issue
+
+This is what you should be filing if you have a bug you want to report.
+
+[Click here](https://github.com/Ukendio/jecs/issues/new/choose) to file a bug report. We have a few templates ready for the most common issue types.
+
+Additionally, see the [Submitting Issues](/contributing/issues) page for more information.
+
+## Creating a Pull Request
+
+This is what you should be filing if you have a change you want to merge into the main project.
+
+[Click here](https://github.com/Ukendio/jecs/compare) to select the branch you want to merge from. 
+
+Additionally, see the [Submitting Pull Requests](/contributing/pull-requests) page for more information.

docs/contributing/issues.md

@@ -1,3 +1,25 @@
-## TODO
+# Submitting Issues
+
+When you're submitting an issue, generally they fall into a few categories:
+
+## Bug
+
+We need some information to figure out what's going wrong. At a minimum, you need to tell us:
+
+        (1) What's supposed to happen
+
+        (2) What actually happened
+
+        (3) Steps to reproduce
+
+
+Stack traces and other useful information that you find make a bug report more likely to be fixed.
+
+Consult the template for a bug report if you don't know or have questions about how to format this.
+
+## Documentation
+
+Depending on how you go about it, this can be done as a [Pull Request](/contributing/pull-requests) instead of an issue. Generally, we need to know what was wrong, what you changed, and how it improved the documentation if it isn't obvious.
+
+We just need to know what's wrong. You should fill out a [PR](/contributing/pull-requests) if you know what should be there instead.
 
-This is a TODO stub.

docs/contributing/pull-requests.md

@@ -1,3 +1,77 @@
-## TODO
+# Submitting Pull Requests
 
-This is a TODO stub.
+When submitting a Pull Request, there's a few reasons to do so:
+
+
+## Documentation
+
+If there's something to change with the documentation, you should follow a similar format to this example:
+
+An example of an appropriate typo-fixing PR would be:
+
+>**Brief Description of your Changes**
+>
+>I fixed a couple of typos found in the /contributing/issues.md file.
+>
+>**Impact of your Changes**
+>
+>- Documentation is more clear and readable for the users.
+>
+>**Tests Performed**
+>
+>Ran `vitepress dev docs` and verified it was built successfully.
+>
+>**Additional Comments**
+>
+>[At Discretion]
+
+## Change in Behavior
+
+An example of an appropriate PR that adds a new feature would be:
+
+>
+>**Brief Description of your Changes**
+>
+>I added `jecs.best_function`, which gives everyone who uses the module an immediate boost in concurrent player counts. (this is a joke)
+>
+>**Impact of your Changes**
+>
+>- jecs functionality is extended to better fit the needs of the community [explain why].
+>
+>**Tests Performed**
+>
+>Added a few test cases to ensure the function runs as expected [link to changes].
+>
+>**Additional Comments**
+>
+>[At Discretion]
+
+## Addons
+
+If you made something you think should be included into the [addons page](/learn/concepts/addons), let us know!
+
+We have tons of examples of libraries and other tools which can be used in conjunction with jecs on this page.
+
+One example of a PR that would be accepted is:
+
+>**Brief Description of your Changes**
+>
+>I added [jecs observers](/learn/concepts/addons#jecs_observers) to the addons page.
+>
+>**Impact of your Changes**
+>
+>- jecs observers are a different and important way of handling queries which benefit the users of jecs by [explain why your tool benefits users here]
+>
+>- [talk about why you went with this design instead of maybe an alternative]
+>
+>**Tests Performed**
+>
+> I used this tool in conjunction with jecs and ensured it works as expected.
+>
+> [If you wrote unit tests for your tool, mention it here.]
+>
+>**Additional Comments**
+>
+>[At Discretion]
+
+Keep in mind the list on the addons page is *not* exhaustive. If you came up with a tool that doesn't fit into any of the categories listed, we still want to hear from you!

docs/learn/concepts/addons.md

@@ -1,6 +1,6 @@
 # Addons
 
-A collection of third-party jecs addons made by the community. If you would like to share what you're working on, [submit a pull request](https://github.com/Ukendio/jecs)!
+A collection of third-party jecs addons made by the community. If you would like to share what you're working on, [submit a pull request](/contributing/pull-requests#addons)!
 
 # Development tools
 

docs/learn/resources/guides.md

@@ -0,0 +1,49 @@
+# Guides
+
+ECS is a very foreign concept. Here's a few resources that the community has compiled about how to use ECS and some of its design choices.
+
+See something missing? [Let us know.](/contributing/pull-requests)
+
+## Blogs
+
+- [An Introduction to ECS for Robloxians - @Ukendio](https://devforum.roblox.com/t/all-about-entity-component-system/1664447)
+- [Entities, Components and Systems - Mark Jordan](https://medium.com/ingeniouslysimple/entities-components-and-systems-89c31464240d)
+- [Why Vanilla ECS is not enough - Sander Mertens](https://ajmmertens.medium.com/why-vanilla-ecs-is-not-enough-d7ed4e3bebe5)
+- [Formalisation of Concepts behind ECS and Entitas - Maxim Zaks](https://medium.com/@icex33/formalisation-of-concepts-behind-ecs-and-entitas-8efe535d9516)
+- [Entity Component System and Rendering - Our Machinery](https://ourmachinery.com/post/ecs-and-rendering/)
+- [Specs and Legion, two very different approaches to ECS - Cora Sherrat](https://csherratt.github.io/blog/posts/specs-and-legion/)
+- [Where are my Entities and Components - Sander Mertens](https://ajmmertens.medium.com/building-an-ecs-1-where-are-my-entities-and-components-63d07c7da742)
+- [Archetypes and Vectorization - Sander Mertens](https://medium.com/@ajmmertens/building-an-ecs-2-archetypes-and-vectorization-fe21690805f9)
+- [Building Games with Entity Relationships - Sander Mertens](https://ajmmertens.medium.com/building-games-in-ecs-with-entity-relationships-657275ba2c6c)
+- [Why it is time to start thinking of games as databases - Sander Mertens](https://ajmmertens.medium.com/why-it-is-time-to-start-thinking-of-games-as-databases-e7971da33ac3)
+- [A Roadmap to Entity Relationships - Sander Mertens](https://ajmmertens.medium.com/a-roadmap-to-entity-relationships-5b1d11ebb4eb)
+- [Making the most of Entity Identifiers - Sander Mertens](https://ajmmertens.medium.com/doing-a-lot-with-a-little-ecs-identifiers-25a72bd2647)
+- [Why Storing State Machines in ECS is a Bad Idea - Sander Mertens](https://ajmmertens.medium.com/why-storing-state-machines-in-ecs-is-a-bad-idea-742de7a18e59)
+- [ECS back & forth - Michele Caini](https://skypjack.github.io/2019-02-14-ecs-baf-part-1/)
+- [Sparse Set - Geeks for Geeks](https://www.geeksforgeeks.org/sparse-set/)
+
+## Videos
+
+- [Taking the Entity-Component-System Architecture Seriously - @alice-i-cecile](https://www.youtube.com/watch?v=VpiprNBEZsk)
+- [Overwatch Gameplay Architecture and Netcode - Blizzard, GDC](https://www.youtube.com/watch?v=W3aieHjyNvw)
+- [Data-Oriented Design and C++ - Mike Acton, CppCon](https://www.youtube.com/watch?v=rX0ItVEVjHc)
+- [Using Rust for Game Development - Catherine West, RustConf](https://www.youtube.com/watch?v=aKLntZcp27M)
+- [CPU caches and why you should care - Scott Meyers, NDC](https://vimeo.com/97337258)
+- [Building a fast ECS on top of a slow ECS - @UnitOfTime](https://youtu.be/71RSWVyOMEY)
+- [Culling the Battlefield: Data Oriented Design in Practice - DICE, GDC](https://www.gdcvault.com/play/1014491/Culling-the-Battlefield-Data-Oriented)
+- [Game Engine Entity/Object Systems - Bobby Anguelov](https://www.youtube.com/watch?v=jjEsB611kxs)
+- [Understanding Data Oriented Design for Entity Component Systems - Unity GDC](https://www.youtube.com/watch?v=0_Byw9UMn9g)
+
+## Tutorials
+
+- [Understanding Data Oriented Design - Unity](https://learn.unity.com/tutorial/part-1-understand-data-oriented-design?courseId=60132919edbc2a56f9d439c3&signup=true&uv=2020.1)
+
+## Books
+
+- [Data Oriented Design - Richard Fabian](https://www.dataorienteddesign.com/dodbook/dodmain.html)
+
+## Other
+
+- [Interactive app for browsing systems of City Skylines 2 - @Captain-Of-Coit](https://captain-of-coit.github.io/cs2-ecs-explorer/)
+- [Awesome Entity Component System (link collection related to ECS) - Jeongseok Lee](https://github.com/jslee02/awesome-entity-component-system)
+- [Hibitset - DOCS.RS](https://docs.rs/hibitset/0.6.3/hibitset/)

jecs.d.ts

@@ -120,6 +120,7 @@ export class World {
 	 * @returns An entity (Tag) with no data.
 	 */
 	entity(): Tag;
+	entity<T extends Entity>(id: T): InferComponent<T> extends undefined ? Tag : T;
 
 	/**
 	 * Creates a new entity in the first 256 IDs, typically used for static
@@ -148,7 +149,7 @@ export class World {
 	 * @param entity The target entity.
 	 * @param component The component (or tag) to add.
 	 */
-	add(entity: Entity, component: Id<undefined>): void;
+	add<C>(entity: Entity, component: undefined extends InferComponent<C> ? C : Id<undefined>): void;
 
 	/**
 	 * Assigns a value to a component on the given entity.

package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "@rbxts/jecs",
-	"version": "0.6.0-rc.1",
+	"version": "0.6.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@rbxts/jecs",
-			"version": "0.6.0-rc.1",
+			"version": "0.6.0",
 			"license": "MIT",
 			"devDependencies": {
 				"@rbxts/compiler-types": "^2.3.0-types.1",