.gitattributes

@@ -1,2 +0,0 @@
-*.luau                 text eol=lf
-*.html           linguist-vendored

.github/ISSUE_TEMPLATE/BUG-REPORT.md

@@ -1,25 +1,22 @@
 ---
 name: Bug report
 about: File a bug report for any behavior that you believe is unintentional or problematic
-title: ""
+title: "[BUG]"
 labels: bug
-assignees: ""
+assignees: ''
+
 ---
 
 ## Describe the bug
-
 Put a clear and concise description of what the bug is. This should be short and to the point, not to exceed more than a paragraph. Put the details inside your reproduction steps.
 
 ## Reproduction
-
 Make an easy-to-follow guide on how to reproduce it. Does it happen all the time? Will specific features affect reproduction? All these questions should be answered for a good issue.
 
 This is a good place to put rbxl files or scripts that help explain your reproduction steps.
 
 ## Expected Behavior
-
 What you expect to happen
 
 ## Actual Behavior
-
 What actually happens

.github/ISSUE_TEMPLATE/DOCUMENTATION.md

@@ -1,15 +1,14 @@
 ---
 name: Documentation
 about: Open an issue to add, change, or otherwise modify any part of the documentation.
-title: ""
+title: "[DOCS]"
 labels: documentation
-assignees: ""
+assignees: ''
+
 ---
 
 ## Which Sections Does This Issue Cover?
-
 [Put sections (e.g. Query Concepts), page links, etc as necessary]
 
 ## What Needs To Change?
-
 What specifically needs to change and what suggestions do you have to change it?

.github/ISSUE_TEMPLATE/FEATURE-REQUEST.md

@@ -1,9 +1,10 @@
 ---
 name: Feature Request
 about: File a feature request for something you believe should be added to Jecs
-title: ""
+title: "[FEATURE]"
 labels: enhancement
-assignees: ""
+assignees: ''
+
 ---
 
 ## Describe your Feature
@@ -21,7 +22,6 @@ What other alternative implementations or otherwise relevant information is impo
 ## Considerations
 
 Some questions that need to be answered include the following:
-
 - Will old code break in response to this feature?
 - What are the performance impacts with this feature (if any)?
 - How is it useful to include?

.github/workflows/analysis.yaml

@@ -1,19 +0,0 @@
-name: analysis
-
-on: [push, pull_request, workflow_dispatch]
-
-jobs:
-    run:
-        name: Run Luau Analyze
-        runs-on: ubuntu-latest
-
-        steps:
-            - name: Checkout Project
-              uses: actions/checkout@v4
-
-            - name: Install Luau
-              uses: encodedvenom/install-luau@v4.3
-
-            - name: Analyze
-              run: |
-                  output=$(luau-analyze src || true) # Suppress errors for now.

.github/workflows/ci.yaml

@@ -0,0 +1,28 @@
+name: Unit Testing
+
+on: [push, pull_request, workflow_dispatch]
+
+jobs:
+  run:
+    name: Run Luau Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+
+    steps:
+      - name: Checkout Project
+        uses: actions/checkout@v4
+
+      - name: Install Luau
+        uses: encodedvenom/install-luau@v2.1
+
+      - name: Run Unit Tests
+        id: run_tests
+        run: |
+          output=$(luau test/tests.luau)
+          echo "$output"
+          if [[ "$output" == *"0 fails"* ]]; then
+            echo "Unit Tests Passed"
+          else
+            echo "Error: One or More Unit Tests Failed."
+            exit 1
+          fi

.github/workflows/dependabot.yml

@@ -1,11 +0,0 @@
----
-version: 2
-updates:
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    schedule:
-      interval: "daily"
-  - package-ecosystem: npm
-    directory: "/"
-    schedule:
-      interval: "daily"

.github/workflows/deploy-docs.yaml

@@ -1,6 +1,6 @@
 # Sample workflow for building and deploying a VitePress site to GitHub Pages
 #
-name: deploy-docs
+name: Deploy VitePress site to Pages
 
 on:
   # Runs on pushes targeting the `main` branch. Change this to `master` if you're

.github/workflows/publish-npm.yml

@@ -1,17 +0,0 @@
-name: publish-npm
-
-on:
-    push:
-        branches: [main]
-
-jobs:
-    publish:
-        runs-on: ubuntu-latest
-        steps:
-            - uses: actions/checkout@v4
-            - uses: actions/setup-node@v3
-              with:
-                  node-version: "20"
-            - uses: JS-DevTools/npm-publish@v3
-              with:
-                  token: ${{ secrets.NPM_AUTH_TOKEN }}

.github/workflows/release.yaml

@@ -1,8 +1,8 @@
-name: release
+name: Release
 
 on:
   push:
-        tags: ["v*", "workflow_dispatch"]
+    tags: ["v*"]
 
 jobs:
   build:
@@ -22,7 +22,7 @@ jobs:
         run: rojo build --output build.rbxm default.project.json
 
       - name: Upload Build Artifact
-              uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with:
           name: build
           path: build.rbxm
@@ -38,7 +38,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Download Jecs Build
-              uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v3
         with:
           name: build
           path: build

.github/workflows/unit-testing.yaml

@@ -1,31 +0,0 @@
-name: unit-testing
-
-on: [push, pull_request, workflow_dispatch]
-
-jobs:
-    run:
-        name: Run Luau Tests
-        runs-on: ubuntu-latest
-        timeout-minutes: 2
-
-        steps:
-            - name: Checkout Project
-              uses: actions/checkout@v4
-
-            - name: Install Luau
-              uses: encodedvenom/install-luau@v4.3
-              with:
-                  version: "0.667"
-                  verbose: "true"
-
-            - name: Run Unit Tests
-              id: run_tests
-              run: |
-                  output=$(luau test/tests.luau)
-                  echo "$output"
-                  if [[ "$output" == *"0 fails"* ]]; then
-                    echo "Unit Tests Passed"
-                  else
-                    echo "Error: One or More Unit Tests Failed."
-                    exit 1
-                  fi

.gitignore

@@ -62,12 +62,3 @@ drafts/
 
 .vitepress/cache
 .vitepress/dist
-
-# Luau tools
-profile.*
-
-# Patch files
-
-*.patch
-
-genhtml.perl

.luaurc

@@ -1,10 +1,8 @@
 {
     "aliases": {
-        "jecs": "jecs",
-        "testkit": "tools/testkit",
+        "jecs": "src",
+        "testkit": "testkit",
         "mirror": "mirror",
-        "tools": "tools",
-        "addons": "addons"
     },
     "languageMode": "strict"
 }

.prettierrc

@@ -1,6 +0,0 @@
-{
-	"printWidth": 120,
-	"tabWidth": 4,
-	"trailingComma": "all",
-	"useTabs": true
-}

.stylua.toml

@@ -1,9 +0,0 @@
-syntax = "All"
-column_width = 120
-line_endings = "Unix"
-indent_type = "Tabs"
-indent_width = 4
-quote_style = "AutoPreferDouble"
-call_parentheses = "Always"
-space_after_function_names = "Never"
-collapse_simple_statement = "Never"

CHANGELOG.md

@@ -1,212 +1,142 @@
-# Changelog
+# Jecs Changelog
 
-## Unreleased
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog][kac], and this project adheres to
+[Semantic Versioning][semver].
+
+[kac]: https://keepachangelog.com/en/1.1.0/
+[semver]: https://semver.org/spec/v2.0.0.html
+
+## [Unreleased]
+
+## [0.2.10] - 2024-09-07
+
+- `[world]`:
+    - Improved performance for hooks
+    - Changed `world:set` to be idempotent when setting tags
+- `[traits]`:
+    - Added cleanup condition `jecs.OnDelete` for when the entity or component is deleted
+    - Added cleanup action `jecs.Remove` which removes instances of the specified (component) id from all entities
+        - This is the default cleanup action
+    - Added component trait `jecs.Tag` which allows for zero-cost components used as tags
+        - Setting data to a component with this trait will do nothing
+- `[luau]`:
+    - Exported `world:contains()`
+    - Exported `query:drain()`
+    - Exported `Query`
+    - Improved types for the hook `OnAdd`, `OnSet`, `OnRemove`
+    - Changed functions to accept any ID including pairs in type parameters
+      - Applies to `world:add()`, `world:set()`, `world:remove()`, `world:get()`, `world:has()` and `world:query()`
+      - New exported type `Id<T = nil> = Entity<T> | Pair`
+    - Changed `world:contains()` to return a `boolean` instead of an entity which may or may not exist
+    - Fixed `world:has()` to take the correct parameters
+
+
+## [0.2.2] - 2024-07-07
 
 ### Added
-- Added signals that allow listening to relation part of pairs in signals.
+
+- Added `query:replace(function(...T) return ...U end)` for replacing components in place
+  - Method is fast pathed to replace the data to the components for each corresponding entity
 
 ### Changed
-- `OnRemove` hooks so that they are allowed to move entity's archetype even during deletion.
 
-## 0.8.0
+- Iterator now goes backwards instead to prevent common cases of iterator invalidation
+
+## [0.2.1] - 2024-07-06
 
 ### Added
-- `jecs.Exclusive` trait for making exclusive relationships.
+
+- Added `jecs.Component` built-in component which will be added to ids created with `world:component()`.
+    - Used to find every component id with `query(jecs.Component)
+
+## [0.2.0] - 2024-07-03
+
+### Added
+
+- Added `world:parent(entity)` and `jecs.ChildOf` respectively as first class citizen for building parent-child relationships.
+    - Give a parent to an entity with `world:add($source, pair(ChildOf, $target))`
+    - Use `world:parent(entity)` to find the target of the relationship
+- Added user-facing Luau types
 
 ### Changed
-- `jecs.ChildOf` to be an exclusive relationship, which means you can only have one `ChildOf` pair on an entity.
+- Improved iteration speeds 20-40% by manually indexing rather than using `next()` :scream:
+
+
+## [0.1.1] - 2024-05-19
 
-## 0.7.2
 ### Added
-- `jecs.entity_index_try_get_fast` back as to not break the observer addon.
+
+- Added `world:clear(entity)` for removing the components to the corresponding entity
+- Added Typescript Types
+
+## [0.1.0] - 2024-05-13
+
+### Changed
+- Optimized iterator
+
+## [0.1.0-rc.6] - 2024-05-13
+
+### Added
+
+- Added a `jecs.Wildcard` term
+    - it lets you query any partially matched pairs
+
+## [0.1.0-rc.5] - 2024-05-10
+
+### Added
+
+- Added Entity relationships for creating logical connections between entities
+- Added `world:__iter method` which allows for iteration over the whole world to get every entity
+    - used for reconciling whole worlds such as via replication, saving/loading, etc
+- Added `world:add(entity, component)` which adds a component to the entity
+    - it is an idempotent function, so calling it twice and in any order should be fine
 
 ### Fixed
-- A linting problem with the types for `quer:with` and `query:without`.
+- Fixed component overriding when in disorder
+    - Previously setting the components in different order results in it overriding component data because it incorrectly mapped the index of the column. So it took the index from the source archetype rather than the destination archetype
 
-
-## 0.7.0
+## [0.0.0-prototype.rc.3] - 2024-05-01
 
 ### Added
-- `jecs.component_record` for retrieving the component_record of a component.
-- `Column<T>` and `ColumnsMap<T>` types for typescript.
-- `bulk_insert` and `bulk_remove` respectively for moving an entity to an archetype without intermediate steps.
+
+- Added observers
+- Added an arm to query `query:without()` for chaining invariants.
 
 ### Changed
-- The fields `archetype.records[id]` and `archetype.counts[id]` have been removed from the archetype struct and been moved to the component record `component_index[id].records[archetype.id]` and `component_index[id].counts[archetype.id]` respectively.
-- Removed the metatable `jecs.World`. Use `jecs.world()` to create your World.
-- Archetypes will no longer be garbage collected when invalidated, allowing them to be recycled to save a lot of performance during frequent deletion.
-- Removed `jecs.entity_index_try_get_fast`. Use `jecs.entity_index_try_get` instead.
+- Separates ranges for components and entity IDs.
+    - IDs created with `world:component()` will promote array lookups rather than map lookups in the `componentIndex` which is a significant boost
 
-## 0.6.1
+- No longer caches the column pointers directly and instead the column indices which stay persistent even when data is reallocated during swap-removals
+    - This was an issue with the iterator being invalidated when you move an entity to a different archetype.
+
+### Fixedhttps://github.com/Ukendio/jecs/releases/tag/v0.0.0-prototype.rc.3
+
+- Fixed a bug where changing an existing component would be slow because it was always appending changing the row of the entity record
+    - The fix dramatically improves times where it is basically down to just the speed of setting a field in a table
+
+## [0.0.0-prototype.rc.2] - 2024-04-26
 
 ### Changed
-- Entity types now unions with numbers should allow for easier time casting while not causing regressing previous behaviours
+- Optimized the creation of the query
+    - It will now finds the smallest archetype map to iterate over
+- Optimized the query iterator
+    - It will now populates iterator with columns for faster indexing
 
-### Fixed
-- Fixed a critical bug with `(*, R)` pairs not being removed when `R` is deleted
+- Renamed the insertion method from world:add to world:set to better reflect what it does.
 
-## 0.6.0
+## [0.0.0-prototype.rc.2] - 2024-04-23
+- Initial release
 
-### Added
-- `World:range` to restrict entity range to allow for e.g. reserving ids `1000..5000` for clients and everything above that (5000+) for entities from the server. This makes it possible to receive ids from a server that don't have to be mapped to local ids.
-- `jecs.component`, `jecs.tag` and `jecs.meta` for preregistering ids and their metadata before a world
-- Overload to `World:entity` to create an entity at the desired id.
-
-### Changed
-- `World:clear` to remove the `ID` from every entity instead of the previous behaviour of removing all of the components on the entity. You should prefer deleting the entity instead for the previous behaviour.
-- Entity ID layouts by putting the index in the lower bits, which should make every world function 1–5 nanoseconds faster.
-- Hooks now pass the full component ID which is useful for pairs when you need both the relation and the target.
-- Replaced `OnSet` with `OnChange`, which now only runs when the component ID was previously present on the entity.
-- `OnAdd` now runs after the value has been set and also passes the component ID and the value.
-- `OnRemove` now lazily looks up which archetype the entity will move to. This is meant to support interior structural changes within every hook.
-- Optimized `world:has` for both single and multiple component presence. This comes at the cost that it cannot check the component presence for more than 4 components at a time. If this is important, consider calling this function multiple times.
-
-### Fixed
-- `World:delete` not removing every pair with an unalive target. Specifically happened when you had at least two pairs of different relations with multiple targets each.
-
-## 0.5.0
-
-### Added
-- `World:each` to find entities with a specific Tag.
-- `World:children` to find children of an entity.
-- `Query:cached` to add a query cache that updates itself when an archetype matching the query gets created or deleted.
-
-### Changed
-- Inference of entities' types using user-defined type functions.
-- `Pair<First, Second>` to return `Second` if `First` is a `Tag`; otherwise, returns `First`.
-
-### Fixed
-- `World:target` not giving adjacent pairs.
-
-## 0.4.0
-
-### Added
-- Recycling support to `world:entity` so reused entity IDs now increment generation.
-
-### Removed
-- `Query:drain`
-- `Query:next`
-- `Query:replace`
-
-### Changed
-- `jecs.Pair` type in Luau now returns the first element's type to avoid manual typecasting.
-
-### Fixed
-- `Query:archetypes` now correctly takes `self`.
-
-## 0.3.2 - 2024-10-01
-
-### Changed
-- `World:cleanup` to traverse a header type for graph edges.
-
-### Fixed
-- Regression when calling `World:set` after `World:remove` on the same component.
-- Removed explicit error in `JECS_DEBUG` for `World:target` missing index.
-- `World.set` type inference with `NoInfer<T>` in TypeScript.
-
-## 0.3.1 - 2024-10-01
-
-### Added
-- Index parameter to `World:target`.
-- Global config `_G.JECS_HI_COMPONENT_ID` to change component ID limit (must be set before importing JECS).
-- Debug mode via `_G.JECS_DEBUG` (must be set before importing JECS).
-- `world:cleanup` to manually clean up empty archetypes.
-
-### Changed
-- `world:delete` now also deletes dependent archetypes and child entities.
-
-### Fixed
-- `Query` iterator to not drain by default.
-- TypeScript package entry to `src` instead of `src/init`.
-- `Query.next` now returns expected result tuple in typescript.
-- `pair` returns a number instead of entity to prevent misuse.
-- Exported built-in components `ChildOf`, `Name`, and `world.parent`.
-
-## 0.2.10
-
-### Added
-- Trait `jecs.Tag` for zero-cost tag components.
-- Cleanup conditions: `jecs.OnDelete`, `jecs.Remove`.
-
-### Changed
-- `world:set` is now idempotent when setting tags.
-
-### Fixed
-- Improved performance for hooks.
-- Exported types and functions: `world:contains()`, `query:drain()`, `Query`.
-- Hook types: `OnAdd`, `OnSet`, `OnRemove`.
-- ID flexibility for `add`, `set`, `remove`, `get`, `has`, `query`.
-- `world:contains()` now returns `boolean`.
-- `world:has()` parameters now correct.
-
-## 0.2.2
-
-### Added
-- `query:replace(fn)` for in-place replacement of component values.
-
-### Changed
-- Iterator now goes backwards to avoid invalidation during iteration.
-
-## 0.2.1
-
-### Added
-- Built-in `jecs.Component` used to find all component IDs.
-
-## 0.2.0
-
-### Added
-- `world:parent(entity)` and `jecs.ChildOf` for parent-child relationships.
-
-### Changed
-- Iteration performance improved by 20–40% through manual indexing.
-
-## 0.1.1
-
-### Added
-- `world:clear(entity)` for removing all components from an entity.
-- TypeScript types.
-
-## 0.1.0
-
-### Changed
-- Optimized iterator.
-
-## 0.1.0-rc.6
-
-### Added
-- `jecs.Wildcard` term to query partially matched pairs.
-
-## 0.1.0-rc.5
-
-### Added
-- Entity relationships.
-- `world:__iter()` for full world iteration.
-- `world:add(entity, component)` (idempotent).
-
-### Fixed
-- Component overriding when set out of order.
-
-## 0.0.0-prototype.rc.3
-
-### Added
-- Observers.
-- `query:without()` for invariant queries.
-
-### Changed
-- Separate ID ranges for entities and components.
-- Avoid caching pointers; cache stable column indices instead.
-
-### Fixed
-- Slow component updates due to unnecessary row changes.
-
-## 0.0.0-prototype.rc.2 - 2024-04-26
-
-### Changed
-- Query now uses smallest archetype map.
-- Optimized query iterator.
-- Renamed `world:add` to `world:set`.
-
-## 0.0.0-prototype.rc.1
-
-### Added
-- Initial release.
+[unreleased]: https://github.com/ukendio/jecs/compare/v0.0.0.0-prototype.rc.2...HEAD
+[0.2.2]: https://github.com/ukendio/jecs/releases/tag/v0.2.2
+[0.2.1]: https://github.com/ukendio/jecs/releases/tag/v0.2.1
+[0.2.0]: https://github.com/ukendio/jecs/releases/tag/v0.2.0
+[0.1.1]: https://github.com/ukendio/jecs/releases/tag/v0.1.1
+[0.1.0]: https://github.com/ukendio/jecs/releases/tag/v0.1.0
+[0.1.0-rc.6]: https://github.com/ukendio/jecs/releases/tag/v0.1.0-rc.6
+[0.1.0-rc.5]: https://github.com/ukendio/jecs/releases/tag/v0.1.0-rc.5
+[0.0.0-prototype-rc.3]: https://github.com/ukendio/jecs/releases/tag/v0.0.0-prototype.rc.3
+[0.0.0-prototype.rc.2]: https://github.com/ukendio/jecs/releases/tag/v0.0.0-prototype.rc.2
+[0.0.0-prototype-rc.1]: https://github.com/ukendio/jecs/releases/tag/v0.0.0-prototype.rc.1

README.md

@@ -1,33 +1,21 @@
+
 <p align="center">
-  <img src="assets/image-5.png" width=35%/>
+  <img src="jecs_darkmode.svg#gh-dark-mode-only" width=50%/>
+  <img src="jecs_lightmode.svg#gh-light-mode-only" width=50%/>
 </p>
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](LICENSE) [![Wally](https://img.shields.io/github/v/tag/ukendio/jecs?&style=for-the-badge)](https://wally.run/package/ukendio/jecs) [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ukendio/jecs/unit-testing.yaml?&style=for-the-badge)](https://github.com/Ukendio/jecs/actions/workflows/unit-testing.yaml)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache-blue.svg?style=for-the-badge)](LICENSE-APACHE)
+[![Wally](https://img.shields.io/github/v/tag/ukendio/jecs?&style=for-the-badge)](https://wally.run/package/ukendio/jecs)
 
-Just a stupidly fast Entity Component System
+jecs is Just a stupidly fast Entity Component System
 
--   [Entity Relationships](https://ajmmertens.medium.com/building-games-in-ecs-with-entity-relationships-657275ba2c6c) as first class citizens
+- Entity Relationships as first class citizens
 - Iterate 800,000 entities at 60 frames per second
 - Type-safe [Luau](https://luau-lang.org/) API
 - Zero-dependency package
 - Optimized for column-major operations
--   Cache friendly [archetype/SoA](https://ajmmertens.medium.com/building-an-ecs-2-archetypes-and-vectorization-fe21690805f9) storage
--   Rigorously [unit tested](https://github.com/Ukendio/jecs/actions/workflows/unit-testing.yaml) for stability
-
-### Installation
-
-With [Wally](https://wally.run/):
-```bash
-jecs = "ukendio/jecs@0.6.0" # Inside wally.toml
-```
-With [pesde](https://pesde.dev/):
-```bash
-pesde add wally#ukendio/jecs@0.6.0
-```
-With [npm](https://www.npmjs.com/package/@rbxts/jecs) ([roblox-ts](https://roblox-ts.com/)):
-```bash
-npm i @rbxts/jecs
-```
+- Cache friendly archetype/SoA storage
+- Unit tested for stability
 
 ### Example
 
@@ -35,8 +23,6 @@ npm i @rbxts/jecs
 local world = jecs.World.new()
 local pair = jecs.pair
 
--- These components and functions are actually already builtin
--- but have been illustrated for demonstration purposes
 local ChildOf = world:component()
 local Name = world:component()
 
@@ -60,8 +46,8 @@ world:set(sara, Name, "sara")
 
 print(getName(parent(sara)))
 
-for e, name in world:query(Name, pair(ChildOf, alice)) do
-    print(name, "is the child of alice")
+for e in world:query(pair(ChildOf, alice)) do
+    print(getName(e), "is the child of alice")
 end
 
 -- Output
@@ -70,12 +56,10 @@ end
 -- sara is the child of alice
 ```
 
-### Benchmarks
-
 21,000 entities 125 archetypes 4 random components queried.
-![Queries](assets/image-3.png)
+![Queries](image-3.png)
 Can be found under /benches/visual/query.luau
 
 Inserting 8 components to an entity and updating them over 50 times.
-![Insertions](assets/image-4.png)
+![Insertions](image-4.png)
 Can be found under /benches/visual/insertions.luau

addons/ob.luau

@@ -1,376 +0,0 @@
---!strict
-local jecs = require("@jecs")
-
-type World = jecs.World
-type Query<T...> = jecs.Query<T...>
-
-type Id<T=any> = jecs.Id<T>
-
-
-export type Iter<T...> = (Observer<T...>) -> () -> (jecs.Entity, T...)
-
-export type Observer<T...> = {
-	disconnect: (Observer<T...>) -> (),
-}
-
-export type Monitor<T...> = {
-	disconnect: (Observer<T...>) -> (),
-	added: ((jecs.Entity) -> ()) -> (),
-	removed: ((jecs.Entity) -> ()) -> ()
-}
-
-local function observers_new<T...>(
-	query: Query<T...>,
-	callback: (jecs.Entity) -> ()
-): Observer<T...>
-	query:cached()
-
-
-	local world = (query :: Query<T...> & { world: World }).world
-	callback = callback
-
-	local archetypes = {}
-	local terms = query.filter_with :: { jecs.Id }
-	local first = terms[1]
-
-	local observers_on_create = world.observable[jecs.ArchetypeCreate][first]
-	local observer_on_create = observers_on_create[#observers_on_create]
-	observer_on_create.callback = function(archetype)
-		archetypes[archetype.id] = true
-	end
-	local observers_on_delete = world.observable[jecs.ArchetypeDelete][first]
-	local observer_on_delete = observers_on_delete[#observers_on_delete]
-	observer_on_delete.callback = function(archetype)
-		archetypes[archetype.id] = nil
-	end
-
-	local entity_index = world.entity_index :: any
-
-	for _, archetype in query:archetypes() do
-		archetypes[archetype.id] = true
-	end
-
-	local function emplaced<a>(
-		entity: jecs.Entity,
-		id: jecs.Id<a>,
-		value: a
-	)
-		local r = entity_index.sparse_array[jecs.ECS_ID(entity)]
-
-		local archetype = r.archetype
-
-		if archetypes[archetype.id] then
-			callback(entity)
-		end
-	end
-
-	local cleanup = {}
-
-	for _, term in terms do
-		if jecs.IS_PAIR(term) then
-			local rel = jecs.ECS_PAIR_FIRST(term)
-			local tgt = jecs.ECS_PAIR_SECOND(term)
-			local wc = tgt == jecs.w
-
-			local onadded = world:added(rel, function(entity, id)
-				if not wc and id ~= term then
-					return
-				end
-				local r = jecs.record(world, entity)
-				if archetypes[r.archetype.id] then
-					callback(entity)
-				end
-			end)
-			table.insert(cleanup, onadded)
-		else
-			local onadded = world:added(term, emplaced)
-			local onchanged = world:changed(term, emplaced)
-			table.insert(cleanup, onadded)
-			table.insert(cleanup, onchanged)
-		end
- 	end
-
-	local without = query.filter_without
-   	if without then
-		for _, term in without do
-			if jecs.IS_PAIR(term) then
-				local rel = jecs.ECS_PAIR_FIRST(term)
-				local tgt = jecs.ECS_PAIR_SECOND(term)
-				local wc = tgt == jecs.w
-				local onremoved = world:removed(rel, function(entity, id)
-					if not wc and id ~= term then
-						return
-					end
-					local r = jecs.record(world, entity)
-					local archetype = r.archetype
-					if archetype then
-						local dst = jecs.archetype_traverse_remove(world, id, archetype)
-						if archetypes[dst.id] then
-							callback(entity)
-						end
-					end
-				end)
-
-				table.insert(cleanup, onremoved)
-			else
-				local onremoved = world:removed(term, function(entity, id)
-					local r = jecs.record(world, entity)
-					local archetype = r.archetype
-					if archetype then
-						local dst = jecs.archetype_traverse_remove(world, id, archetype)
-						if archetypes[dst.id] then
-							callback(entity)
-						end
-					end
-				end)
-
-				table.insert(cleanup, onremoved)
-			end
-		end
-	end
-
- 	local function disconnect()
-  		table.remove(observers_on_create, table.find(
-	  		observers_on_create,
-	    	observer_on_create
-	   	))
-
-	   	table.remove(observers_on_delete, table.find(
-	      	observers_on_delete,
-	       	observer_on_delete
-       	))
-
-		table.clear(archetypes)
-
-		for _, disconnect in cleanup do
-			disconnect()
-		end
-   	end
-
-	local observer = {
-  		disconnect = disconnect,
-   	}
-
-    return observer
-end
-
-local function monitors_new<T...>(query: Query<T...>): Monitor<T...>
-	query:cached()
-
-	local world = (query :: Query<T...> & { world: World }).world
-
-	local archetypes = {}
-	local terms = query.filter_with :: { jecs.Id<any> }
-	local first = terms[1]
-
-	local observers_on_create = world.observable[jecs.ArchetypeCreate][first]
-	local observer_on_create = observers_on_create[#observers_on_create]
-	observer_on_create.callback = function(archetype)
-		archetypes[archetype.id] = true
-	end
-	local observers_on_delete = world.observable[jecs.ArchetypeDelete][first]
-	local observer_on_delete = observers_on_delete[#observers_on_delete]
-	observer_on_delete.callback = function(archetype)
-		archetypes[archetype.id] = nil
-	end
-
-	for _, archetype in query:archetypes() do
-		archetypes[archetype.id] = true
-	end
-	local entity_index = world.entity_index :: any
-
-	local callback_added: ((jecs.Entity) -> ())?
-	local callback_removed: ((jecs.Entity) -> ())?
-
-	local function emplaced<a>(
-		entity: jecs.Entity,
-		id: jecs.Id<a>,
-		value: a
-	)
-		if callback_added == nil then
-			return
-		end
-
-		local r = jecs.entity_index_try_get_fast(
-			entity_index, entity :: any) :: jecs.Record
-
-		local archetype = r.archetype
-
-		if archetypes[archetype.id] then
-			callback_added(entity)
-		end
-	end
-
-	local function removed(entity: jecs.Entity, component: jecs.Id)
-		if callback_removed == nil then
-			return
-		end
-		local r = jecs.record(world, entity)
-		if not archetypes[r.archetype.id] then
-			return
-		end
-		callback_removed(entity)
-	end
-
-	local cleanup = {}
-
-	for _, term in terms do
-		if jecs.IS_PAIR(term) then
-			local rel = jecs.ECS_PAIR_FIRST(term)
-			local tgt = jecs.ECS_PAIR_SECOND(term)
-			local wc = tgt == jecs.w
-
-			local onadded = world:added(rel, function(entity, id)
-				if callback_added == nil then
-					return
-				end
-
-				if not wc and id ~= term then
-					return
-				end
-
-				local r = jecs.entity_index_try_get_fast(
-					entity_index, entity :: any) :: jecs.Record
-
-				local archetype = r.archetype
-
-				if archetypes[archetype.id] then
-					callback_added(entity)
-				end
-			end)
-			local onremoved = world:removed(rel, function(entity, id)
-				if callback_removed == nil then
-					return
-				end
-				if not wc and id ~= term then
-					return
-				end
-				local r = jecs.record(world, entity)
-				if not archetypes[r.archetype.id] then
-					return
-				end
-				callback_removed(entity)
-			end)
-			table.insert(cleanup, onadded)
-			table.insert(cleanup, onremoved)
-		else
-			local onadded = world:added(term, emplaced)
-			local onremoved = world:removed(term, removed)
-			table.insert(cleanup, onadded)
-			table.insert(cleanup, onremoved)
-		end
- 	end
-
-  	local without = query.filter_without
-   	if without then
-	   	for _, term in without do
-			if jecs.IS_PAIR(term) then
-				local rel = jecs.ECS_PAIR_FIRST(term)
-				local tgt = jecs.ECS_PAIR_SECOND(term)
-				local wc = tgt == jecs.w
-				local onadded = world:added(rel, function(entity, id)
-					if callback_removed == nil then
-						return
-					end
-					if not wc and id ~= term then
-						return
-					end
-					local r = jecs.record(world, entity)
-					local archetype = r.archetype
-					if archetype then
-						local dst = jecs.archetype_traverse_remove(world, id, archetype)
-						if archetypes[dst.id] then
-							callback_removed(entity)
-						end
-					end
-				end)
-				local onremoved = world:removed(rel, function(entity, id)
-					if callback_added == nil then
-						return
-					end
-					if not wc and id ~= term then
-						return
-					end
-					local r = jecs.record(world, entity)
-					local archetype = r.archetype
-					if archetype then
-						local dst = jecs.archetype_traverse_remove(world, id, archetype)
-						if archetypes[dst.id] then
-							callback_added(entity)
-						end
-					end
-				end)
-				table.insert(cleanup, onadded)
-				table.insert(cleanup, onremoved)
-			else
-				local onadded = world:added(term, function(entity, id)
-					if callback_removed == nil then
-						return
-					end
-					local r = jecs.record(world, entity)
-					local archetype = r.archetype
-					if archetype then
-						local dst = jecs.archetype_traverse_remove(world, id, archetype)
-						if archetypes[dst.id] then
-							callback_removed(entity)
-						end
-					end
-				end)
-				local onremoved = world:removed(term, function(entity, id)
-					if callback_added == nil then
-						return
-					end
-					local r = jecs.record(world, entity)
-					local archetype = r.archetype
-					if archetype then
-						local dst = jecs.archetype_traverse_remove(world, id, archetype)
-						if archetypes[dst.id] then
-							callback_added(entity)
-						end
-					end
-				end)
-				table.insert(cleanup, onadded)
-				table.insert(cleanup, onremoved)
-			end
-    	end
-    end
-
- 	local function disconnect()
-  		table.remove(observers_on_create, table.find(
-	  		observers_on_create,
-	    	observer_on_create
-	   	))
-
-	   	table.remove(observers_on_delete, table.find(
-	      	observers_on_delete,
-	       	observer_on_delete
-       	))
-
-		table.clear(archetypes)
-
-		for _, disconnect in cleanup do
-			disconnect()
-		end
-   	end
-
-    local function monitor_added(callback)
-		callback_added = callback
-    end
-
-    local function monitor_removed(callback)
-    	callback_removed = callback
-    end
-
-	local monitor = {
-  		disconnect = disconnect,
-    	added = monitor_added,
-     	removed = monitor_removed
-   	} :: Monitor<T...>
-
-    return monitor
-end
-
-return {
-	monitor = monitors_new,
-	observer = observers_new
-}

bench.project.json

@@ -12,13 +12,16 @@
         "ReplicatedStorage": {
             "$className": "ReplicatedStorage",
             "Lib": {
-				"$path": "jecs.luau"
+                "$path": "src"
+            },
+            "rgb": {
+                "$path": "rgb.luau"
             },
             "benches": {
                 "$path": "benches"
             },
             "mirror": {
-				"$path": "mirror.luau"
+                "$path": "mirror"
             },
             "DevPackages": {
                 "$path": "benches/visual/DevPackages"

benches/cached.luau

@@ -1,5 +1,6 @@
+
 local jecs = require("@jecs")
-local mirror = require("@mirror")
+local mirror = require("../mirror/init")
 
 type i53 = number
 
@@ -38,36 +39,36 @@ do
 
 			if flip() then
 				combination ..= "B"
-				ecs:set(entity, D2, { value = true })
+				ecs:set(entity, D2, {value = true})
 			end
 			if flip() then
 				combination ..= "C"
-				ecs:set(entity, D3, { value = true })
+				ecs:set(entity, D3, {value = true})
 			end
 			if flip() then
 				combination ..= "D"
-				ecs:set(entity, D4, { value = true })
+				ecs:set(entity, D4, {value = true})
 			end
 			if flip() then
 				combination ..= "E"
-				ecs:set(entity, D5, { value = true })
+				ecs:set(entity, D5, {value = true})
 			end
 			if flip() then
 				combination ..= "F"
-				ecs:set(entity, D6, { value = true })
+				ecs:set(entity, D6, {value = true})
 			end
 			if flip() then
 				combination ..= "G"
-				ecs:set(entity, D7, { value = true })
+				ecs:set(entity, D7, {value = true})
 			end
 			if flip() then
 				combination ..= "H"
-				ecs:set(entity, D8, { value = true })
+				ecs:set(entity, D8, {value = true})
 			end
 
 			if #combination == 7 then
 				added += 1
-				ecs:set(entity, D1, { value = true })
+				ecs:set(entity, D1, {value = true})
 			end
 			archetypes[combination] = true
 		end
@@ -116,36 +117,36 @@ do
 
 			if flip() then
 				combination ..= "B"
-				ecs:set(entity, D2, { value = true })
+				ecs:set(entity, D2, {value = true})
 			end
 			if flip() then
 				combination ..= "C"
-				ecs:set(entity, D3, { value = true })
+				ecs:set(entity, D3, {value = true})
 			end
 			if flip() then
 				combination ..= "D"
-				ecs:set(entity, D4, { value = true })
+				ecs:set(entity, D4, {value = true})
 			end
 			if flip() then
 				combination ..= "E"
-				ecs:set(entity, D5, { value = true })
+				ecs:set(entity, D5, {value = true})
 			end
 			if flip() then
 				combination ..= "F"
-				ecs:set(entity, D6, { value = true })
+				ecs:set(entity, D6, {value = true})
 			end
 			if flip() then
 				combination ..= "G"
-				ecs:set(entity, D7, { value = true })
+				ecs:set(entity, D7, {value = true})
 			end
 			if flip() then
 				combination ..= "H"
-				ecs:set(entity, D8, { value = true })
+				ecs:set(entity, D8, {value = true})
 			end
 
 			if #combination == 7 then
 				added += 1
-				ecs:set(entity, D1, { value = true })
+				ecs:set(entity, D1, {value = true})
 			end
 			archetypes[combination] = true
 		end

benches/general.luau

@@ -8,13 +8,12 @@ local function TITLE(s: string)
 	print(testkit.color.white(s))
 end
 
-local N = 2 ^ 17
+local N = 2^17
 
 local pair = jecs.pair
 
-do
-	TITLE("create")
-	local world = jecs.world()
+do TITLE "create"
+	local world = jecs.World.new()
 
 	BENCH("entity", function()
 		for i = 1, START(N) do
@@ -30,13 +29,13 @@ do
 			jecs.pair(A, B)
 		end
 	end)
+
 end
 
-do
-	TITLE("set")
+do TITLE "set"
 
-	local world = jecs.world()
-	local A = world:component()
+	local world = jecs.World.new()
+	local A = world:entity()
 
 	local entities = table.create(N)
 
@@ -66,11 +65,10 @@ end
 -- we have a separate benchmark for relationships.
 -- this is due to that relationships have a very high id compared to normal
 -- components, which cause them to get added into the hashmap portion.
-do
-	TITLE("set relationship")
+do TITLE "set relationship"
 
-	local world = jecs.world()
-	local A = world:component()
+	local world = jecs.World.new()
+	local A = world:entity()
 
 	local entities = table.create(N)
 
@@ -100,10 +98,9 @@ do
 	end)
 end
 
-do
-	TITLE("get")
+do TITLE "get"
 
-	local world = jecs.world()
+	local world = jecs.World.new()
 	local A = world:component()
 	local B = world:component()
 	local C = world:component()
@@ -143,11 +140,10 @@ do
 	end)
 end
 
-do
-	TITLE("target")
+do TITLE "target"
 
 	BENCH("1st target", function()
-		local world = jecs.world()
+		local world = jecs.World.new()
 		local A = world:component()
 		local B = world:component()
 		local C = world:component()
@@ -168,18 +164,18 @@ do
 			world:target(entities[i], A, 0)
 		end
 	end)
+
 end
 
 --- this benchmark is used to view how fragmentation affects query performance
 --- we use this by determining how many entities should fit per arcehtype, instead
 --- of creating x amount of archetypes. this would scale better with any amount of
 --- entities.
-do
-	TITLE(`query {N} entities`)
+do TITLE(`query {N} entities`)
 
 	local function view_bench(n: number)
 		BENCH(`{n} entities per archetype`, function()
-			local world = jecs.world()
+			local world = jecs.World.new()
 
 			local A = world:component()
 			local B = world:component()
@@ -194,19 +190,18 @@ do
 					world:set(id, B, true)
 					world:set(id, C, true)
 					world:set(id, D, true)
-					world:add(id, ct)
+					world:set(id, ct, true)
 				end
 			end
 
-			local q = world:query(A, B, C, D)
-			q:archetypes()
+
 			START()
-			for id in q do
+			for id in world:query(A, B, C, D) do
 			end
 		end)
 
 		BENCH(`inlined query`, function()
-			local world = jecs.world()
+		    local world = jecs.World.new()
 			local A = world:component()
 			local B = world:component()
 			local C = world:component()
@@ -220,28 +215,18 @@ do
 					world:set(id, B, true)
 					world:set(id, C, true)
 					world:set(id, D, true)
-					world:add(id, ct)
+					world:set(id, ct, true)
 				end
 			end
 
-			local archetypes = world:query(A, B, C, D):archetypes()
+
 			START()
-			-- for _, archetype in archetypes do
-			-- 	local columns, records = archetype.columns, archetype.records
-			-- 	local a = columns[records[A]]
-			-- 	local b = columns[records[B]]
-			-- 	local c = columns[records[C]]
-			-- 	local d = columns[records[D]]
-			-- 	for row in archetype.entities do
-			-- 		local _1, _2, _3, _4 = a[row], b[row], c[row], d[row]
-			-- 	end
-			-- end
-			for _, archetype in archetypes do
-				local columns_map = archetype.columns_map
-				local a = columns_map[A]
-				local b = columns_map[B]
-				local c = columns_map[C]
-				local d = columns_map[D]
+			for _, archetype in world:query(A, B, C, D):archetypes() do
+			    local columns, records = archetype.columns, archetype.records
+				local a = columns[records[A].column]
+				local b = columns[records[B].column]
+				local c = columns[records[C].column]
+				local d = columns[records[D].column]
 			    for row in archetype.entities do
 					local _1, _2, _3, _4 = a[row], b[row], c[row], d[row]
 				end
@@ -250,6 +235,7 @@ do
 	end
 
 	for i = 13, 0, -1 do
-		view_bench(2 ^ i)
+		view_bench(2^i)
 	end
+
 end

benches/query.luau

@@ -9,24 +9,17 @@ local function TITLE(title: string)
 end
 
 local jecs = require("@jecs")
-local mirror = require("@mirror")
+local mirror = require("../mirror/init")
+
+type i53 = number
 
 do
 	TITLE(testkit.color.white_underline("Jecs query"))
-	local ecs = jecs.world() :: jecs.World
+	local ecs = jecs.World.new()
 	do
 		TITLE("one component in common")
 
-		local function view_bench(world: jecs.World,
-			A: jecs.Id,
-			B: jecs.Id,
-			C: jecs.Id,
-			D: jecs.Id,
-			E: jecs.Id,
-			F: jecs.Id,
-			G: jecs.Id,
-			H: jecs.Id
-		)
+		local function view_bench(world: jecs.World, A: i53, B: i53, C: i53, D: i53, E: i53, F: i53, G: i53, H: i53)
 		    BENCH("1 component", function()
 				for _ in world:query(A) do
 				end
@@ -93,36 +86,36 @@ do
 
 			if flip() then
 				combination ..= "B"
-				ecs:set(entity, D2, { value = true })
+				ecs:set(entity, D2, {value = true})
 			end
 			if flip() then
 				combination ..= "C"
-				ecs:set(entity, D3, { value = true })
+				ecs:set(entity, D3, {value = true})
 			end
 			if flip() then
 				combination ..= "D"
-				ecs:set(entity, D4, { value = true })
+				ecs:set(entity, D4, {value = true})
 			end
 			if flip() then
 				combination ..= "E"
-				ecs:set(entity, D5, { value = true })
+				ecs:set(entity, D5, {value = true})
 			end
 			if flip() then
 				combination ..= "F"
-				ecs:set(entity, D6, { value = true })
+				ecs:set(entity, D6, {value = true})
 			end
 			if flip() then
 				combination ..= "G"
-				ecs:set(entity, D7, { value = true })
+				ecs:set(entity, D7, {value = true})
 			end
 			if flip() then
 				combination ..= "H"
-				ecs:set(entity, D8, { value = true })
+				ecs:set(entity, D8, {value = true})
 			end
 
 			if #combination == 7 then
 				added += 1
-				ecs:set(entity, D1, { value = true })
+				ecs:set(entity, D1, {value = true})
 			end
 			archetypes[combination] = true
 		end
@@ -138,21 +131,11 @@ end
 
 do
 	TITLE(testkit.color.white_underline("Mirror query"))
-	local ecs = mirror.World.new() :: jecs.World
+	local ecs = mirror.World.new()
 	do
 		TITLE("one component in common")
 
-		local function view_bench(
-			world: mirror.World,
-			A: jecs.Id,
-			B: jecs.Id,
-			C: jecs.Id,
-			D: jecs.Id,
-			E: jecs.Id,
-			F: jecs.Id,
-			G: jecs.Id,
-			H: jecs.Id
-		)
+		local function view_bench(world: jecs.World, A: i53, B: i53, C: i53, D: i53, E: i53, F: i53, G: i53, H: i53)
 			BENCH("1 component", function()
 				for _ in world:query(A) do
 				end
@@ -219,36 +202,36 @@ do
 
 			if flip() then
 				combination ..= "B"
-				ecs:set(entity, D2, { value = true })
+				ecs:set(entity, D2, {value = true})
 			end
 			if flip() then
 				combination ..= "C"
-				ecs:set(entity, D3, { value = true })
+				ecs:set(entity, D3, {value = true})
 			end
 			if flip() then
 				combination ..= "D"
-				ecs:set(entity, D4, { value = true })
+				ecs:set(entity, D4, {value = true})
 			end
 			if flip() then
 				combination ..= "E"
-				ecs:set(entity, D5, { value = true })
+				ecs:set(entity, D5, {value = true})
 			end
 			if flip() then
 				combination ..= "F"
-				ecs:set(entity, D6, { value = true })
+				ecs:set(entity, D6, {value = true})
 			end
 			if flip() then
 				combination ..= "G"
-				ecs:set(entity, D7, { value = true })
+				ecs:set(entity, D7, {value = true})
 			end
 			if flip() then
 				combination ..= "H"
-				ecs:set(entity, D8, { value = true })
+				ecs:set(entity, D8, {value = true})
 			end
 
 			if #combination == 7 then
 				added += 1
-				ecs:set(entity, D1, { value = true })
+				ecs:set(entity, D1, {value = true})
 			end
 			archetypes[combination] = true
 		end

benches/visual/despawn.bench.luau

@@ -1,65 +1,48 @@
-
 --!optimize 2
 --!native
 
 local ReplicatedStorage = game:GetService("ReplicatedStorage")
-local jecs = require(ReplicatedStorage.Lib:Clone())
-local pair = jecs.pair
-local ecs = jecs.world()
-local mirror = require(ReplicatedStorage.mirror:Clone())
-local mcs = mirror.world()
+local Matter = require(ReplicatedStorage.DevPackages.Matter)
+local ecr = require(ReplicatedStorage.DevPackages.ecr)
+local jecs = require(ReplicatedStorage.Lib)
+local rgb = require(ReplicatedStorage.rgb)
+local newWorld = Matter.World.new()
+local ecs = jecs.World.new()
 
-local C1 = ecs:component()
-local C2 = ecs:entity()
-local C3 = ecs:entity()
-local C4 = ecs:entity()
-local E1 = mcs:component()
-local E2 = mcs:entity()
-local E3 = mcs:entity()
-local E4 = mcs:entity()
+local A, B = Matter.component(), Matter.component()
+local C, D = ecs:component(), ecs:component()
 
-local m = mcs:entity()
-local j = ecs:entity()
 
 return {
 	ParameterGenerator = function()
-	end,
+    	local matter_entities = {}
+        local jecs_entities = {}
+        local entities = {
+            matter = matter_entities,
+            jecs = jecs_entities
+        }
+        for i = 1, 1000 do
+            table.insert(matter_entities, newWorld:spawn(A(), B()))
+            local e = ecs:entity()
+            ecs:set(e, C, {})
+            ecs:set(e, D, {})
+            table.insert(jecs_entities, e)
+        end
+        return entities
+	end;
 
 	Functions = {
-		Mirror = function()
-			for i = 1, 10 do
-				local friend2 = mcs:entity()
-				mcs:add(friend2, pair(E2, m))
-				mcs:add(friend2, pair(E3, m))
-				mcs:add(friend2, pair(E4, m))
-
-				-- local r = mirror.entity_index_try_get_fast(mcs.entity_index, friend2)
-				-- local archetype = r.archetype
-
-				-- mirror.archetype_destroy(mcs, archetype)
-
-				mcs:delete(m)
-				m = mcs:entity(m)
+		Matter = function(_, entities)
+		    for _, entity in entities.matter do
+    			newWorld:despawn(entity)
     		end
+        end;
 
-		end,
 
-		Jecs = function()
-			for i = 1, 10 do
-				local friend1 = ecs:entity()
-				ecs:add(friend1, pair(C2, j))
-				ecs:add(friend1, pair(C3, j))
-				ecs:add(friend1, pair(C4, j))
-
-				-- local r = jecs.entity_index_try_get_fast(ecs.entity_index, friend1)
-				-- local archetype = r.archetype
-
-				-- jecs.archetype_destroy(ecs, archetype)
-
-				ecs:delete(j)
-				j = ecs:entity()
+		Jecs = function(_, entities)
+		    for _, entity in entities.jecs do
+				ecs:delete(entity)
 			end
-
-		end,
-	},
+		end;
+	};
 }

benches/visual/insertion.bench.luau

@@ -2,58 +2,101 @@
 --!native
 
 local ReplicatedStorage = game:GetService("ReplicatedStorage")
-local jecs = require(ReplicatedStorage.Lib:Clone())
-local ecs = jecs.world()
-local mirror = require(ReplicatedStorage.mirror:Clone())
-local mcs = mirror.world()
+local Matter = require(ReplicatedStorage.DevPackages.Matter)
+local jecs = require(ReplicatedStorage.Lib)
+local ecr = require(ReplicatedStorage.DevPackages.ecr)
+local newWorld = Matter.World.new()
+local ecs = jecs.World.new()
+local mirror = require(ReplicatedStorage.mirror)
+local mcs = mirror.World.new()
 
-local C1 = ecs:component()
-local C2 = ecs:component()
-local C3 = ecs:component()
-local C4 = ecs:component()
-local C5 = ecs:component()
-local C6 = ecs:component()
-local C7 = ecs:component()
-local C8 = ecs:component()
-local E1 = mcs:component()
-local E2 = mcs:component()
-local E3 = mcs:component()
-local E4 = mcs:component()
-local E5 = mcs:component()
-local E6 = mcs:component()
-local E7 = mcs:component()
-local E8 = mcs:component()
+local A1 = Matter.component()
+local A2 = Matter.component()
+local A3 = Matter.component()
+local A4 = Matter.component()
+local A5 = Matter.component()
+local A6 = Matter.component()
+local A7 = Matter.component()
+local A8 = Matter.component()
 
+local B1 = ecr.component()
+local B2 = ecr.component()
+local B3 = ecr.component()
+local B4 = ecr.component()
+local B5 = ecr.component()
+local B6 = ecr.component()
+local B7 = ecr.component()
+local B8 = ecr.component()
+
+local C1 = ecs:entity()
+local C2 = ecs:entity()
+local C3 = ecs:entity()
+local C4 = ecs:entity()
+local C5 = ecs:entity()
+local C6 = ecs:entity()
+local C7 = ecs:entity()
+local C8 = ecs:entity()
+local E1 = mcs:entity()
+local E2 = mcs:entity()
+local E3 = mcs:entity()
+local E4 = mcs:entity()
+local E5 = mcs:entity()
+local E6 = mcs:entity()
+local E7 = mcs:entity()
+local E8 = mcs:entity()
+
+
+local registry2 = ecr.registry()
 return {
 	ParameterGenerator = function()
 		return
 	end,
 
 	Functions = {
-		Mirror = function()
-			local e = mcs:entity()
+		Matter = function() 
+            local e = newWorld:spawn()
             for i = 1, 5000 do 
-				mcs:set(e, E1, false)
-				mcs:set(e, E2, false)
-				mcs:set(e, E3, false)
-				mcs:set(e, E4, false)
-				mcs:set(e, E5, false)
-				mcs:set(e, E6, false)
-				mcs:set(e, E7, false)
-				mcs:set(e, E8, false)
+                newWorld:insert(e,
+                    A1({ value = true }),
+                    A2({ value = true }),
+                    A3({ value = true }),
+                    A4({ value = true }),
+                    A5({ value = true }),
+                    A6({ value = true }),
+                    A7({ value = true }),
+                    A8({ value = true })
+                )             
             end
 		end,
+
+
+		ECR = function() 
+            local e = registry2.create()
+            for i = 1, 5000 do
+                registry2:set(e, B1, {value = false}) 
+                registry2:set(e, B2, {value = false}) 
+                registry2:set(e, B3, {value = false}) 
+                registry2:set(e, B4, {value = false}) 
+                registry2:set(e, B5, {value = false}) 
+                registry2:set(e, B6, {value = false}) 
+                registry2:set(e, B7, {value = false}) 
+                registry2:set(e, B8, {value = false})
+            end
+		end,
+
+
 		Jecs = function() 
             local e = ecs:entity()
             for i = 1, 5000 do 
-				ecs:set(e, C1, false)
-				ecs:set(e, C2, false)
-				ecs:set(e, C3, false)
-				ecs:set(e, C4, false)
-				ecs:set(e, C5, false)
-				ecs:set(e, C6, false)
-				ecs:set(e, C7, false)
-				ecs:set(e, C8, false)
+                ecs:set(e, C1, {value = false}) 
+                ecs:set(e, C2, {value = false}) 
+                ecs:set(e, C3, {value = false}) 
+                ecs:set(e, C4, {value = false}) 
+                ecs:set(e, C5, {value = false}) 
+                ecs:set(e, C6, {value = false}) 
+                ecs:set(e, C7, {value = false}) 
+                ecs:set(e, C8, {value = false}) 
+
             end
 		end,
 	},

benches/visual/query.bench.luau

@@ -2,11 +2,33 @@
 --!native
 
 local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local rgb = require(ReplicatedStorage.rgb)
+local Matter = require(ReplicatedStorage.DevPackages["_Index"]["matter-ecs_matter@0.8.1"].matter)
+local ecr = require(ReplicatedStorage.DevPackages["_Index"]["centau_ecr@0.8.0"].ecr)
+local newWorld = Matter.World.new()
 
-local jecs = require(ReplicatedStorage.Lib:Clone())
-local mirror = require(ReplicatedStorage.mirror:Clone())
-local mcs = mirror.world()
-local ecs = jecs.world()
+local jecs = require(ReplicatedStorage.Lib)
+local mirror = require(ReplicatedStorage.mirror)
+local mcs = mirror.World.new()
+local ecs = jecs.World.new()
+
+local A1 = Matter.component()
+local A2 = Matter.component()
+local A3 = Matter.component()
+local A4 = Matter.component()
+local A5 = Matter.component()
+local A6 = Matter.component()
+local A7 = Matter.component()
+local A8 = Matter.component()
+
+local B1 = ecr.component()
+local B2 = ecr.component()
+local B3 = ecr.component()
+local B4 = ecr.component()
+local B5 = ecr.component()
+local B6 = ecr.component()
+local B7 = ecr.component()
+local B8 = ecr.component()
 
 local D1 = ecs:component()
 local D2 = ecs:component()
@@ -17,62 +39,111 @@ local D6 = ecs:component()
 local D7 = ecs:component()
 local D8 = ecs:component()
 
-local E1 = mcs:component()
-local E2 = mcs:component()
-local E3 = mcs:component()
-local E4 = mcs:component()
-local E5 = mcs:component()
-local E6 = mcs:component()
-local E7 = mcs:component()
-local E8 = mcs:component()
+
+local E1 = mcs:entity()
+local E2 = mcs:entity()
+local E3 = mcs:entity()
+local E4 = mcs:entity()
+local E5 = mcs:entity()
+local E6 = mcs:entity()
+local E7 = mcs:entity()
+local E8 = mcs:entity()
+
+
+local registry2 = ecr.registry()
 
 local function flip()
-	return math.random() >= 0.3
+	return math.random() >= 0.25
 end
 
-local N = 2 ^ 16 - 2
+local N = 2^16-2
+local archetypes = {}
 
+local hm = 0
 for i = 1, N do
+	local id = registry2.create()
+	local combination = ""
+	local n = newWorld:spawn()
 	local entity = ecs:entity()
 	local m = mcs:entity()
 
 	if flip() then
-		ecs:add(entity, entity)
-		mcs:add(m, m)
+		registry2:set(id, B1, {value = true})
+		ecs:set(entity, D1, { value = true})
+		newWorld:insert(n, A1({value = true}))
+		mcs:set(m, E1, { value = 2})
 	end
 	if flip() then
-		ecs:set(entity, D1, true)
-		mcs:set(m, E1, true)
+		combination ..= "B"
+		registry2:set(id, B2, {value = true})
+		ecs:set(entity, D2, { value = true})
+		mcs:set(m, E2, { value = 2})
+		newWorld:insert(n, A2({value = true}))
 	end
 	if flip() then
-		ecs:set(entity, D2, true)
-		mcs:set(m, E2, true)
+		combination ..= "C"
+		registry2:set(id, B3, {value = true})
+		ecs:set(entity, D3, { value = true})
+		mcs:set(m, E3, { value = 2})
+		newWorld:insert(n, A3({value = true}))
 	end
 	if flip() then
-		ecs:set(entity, D3, true)
-		mcs:set(m, E3, true)
+		combination ..= "D"
+		registry2:set(id, B4, {value = true})
+		ecs:set(entity, D4, { value = true})
+		mcs:set(m, E4, { value = 2})
+
+		newWorld:insert(n, A4({value = true}))
 	end
 	if flip() then
-		ecs:set(entity, D4, true)
-		mcs:set(m, E4, true)
+		combination ..= "E"
+		registry2:set(id, B5, {value = true})
+		ecs:set(entity, D5, { value = true})
+		mcs:set(m, E5, { value = 2})
+
+		newWorld:insert(n, A5({value = true}))
 	end
 	if flip() then
-		ecs:set(entity, D5, true)
-		mcs:set(m, E5, true)
+		combination ..= "F"
+		registry2:set(id, B6, {value = true})
+		ecs:set(entity, D6, { value = true})
+		mcs:set(m, E6, { value = 2})
+		newWorld:insert(n, A6({value = true}))
 	end
 	if flip() then
-		ecs:set(entity, D6, true)
-		mcs:set(m, E6, true)
+		combination ..= "G"
+		registry2:set(id, B7, {value = true})
+		ecs:set(entity, D7, { value = true})
+		mcs:set(m, E7, { value = 2})
+		newWorld:insert(n, A7({value = true}))
 	end
 	if flip() then
-		ecs:set(entity, D7, true)
-		mcs:set(m, E7, true)
+		combination ..= "H"
+		registry2:set(id, B8, {value = true})
+		newWorld:insert(n, A8({value = true}))
+		ecs:set(entity, D8, { value = true})
+		mcs:set(m, E8, { value = 2})
+
 	end
-	if flip() then
-		ecs:set(entity, D8, true)
-		mcs:set(m, E8, true)
+
+
+
+	if combination:find("BCDF") then
+		if not archetypes[combination] then
+			 print(combination)
 		end
+		hm += 1
+	end
+	archetypes[combination] = true
 end
+print("TEST", hm)
+
+local white = rgb.white
+local yellow = rgb.yellow
+local gray = rgb.gray
+local green = rgb.green
+
+local WALL = gray(" │ ")
 
 local count = 0
 
@@ -80,11 +151,7 @@ for _, archetype in ecs:query(D2, D4, D6, D8):archetypes() do
     count += #archetype.entities
 end
 
-
-local mq = mcs:query(E2, E4, E6, E8):cached()
-local jq = ecs:query(D2, D4, D6, D8):cached()
-
-print(count, #jq:archetypes())
+print(count)
 
 return {
 	ParameterGenerator = function()
@@ -92,23 +159,18 @@ return {
 	end,
 
 	Functions = {
-		-- Matter = function()
-		-- 	for entityId, firstComponent in newWorld:query(A2, A4, A6, A8) do
-		-- 	end
-		-- end,
+		Matter = function()
+			for entityId, firstComponent in newWorld:query(A2, A4, A6, A8) do
+			end
+		end,
 
-		-- ECR = function()
-		-- 	for entityId, firstComponent in registry2:view(B2, B4, B6, B8) do
-		-- 	end
-		-- end,
-		--
-		Mirror = function()
-			for entityId, firstComponent in mq do
+		ECR = function()
+    		for entityId, firstComponent in registry2:view(B2, B4, B6, B8) do
             end
 	    end,
 
 		Jecs = function()
-			for entityId, firstComponent in jq do
+    		for entityId, firstComponent in ecs:query(D2, D4, D6, D8) do
             end
 		end,
 	},

benches/visual/remove.bench.luau

@@ -1,52 +0,0 @@
---!optimize 2
---!native
-
-local ReplicatedStorage = game:GetService("ReplicatedStorage")
-local Matter = require(ReplicatedStorage.DevPackages.Matter)
-local ecr = require(ReplicatedStorage.DevPackages.ecr)
-local jecs = require(ReplicatedStorage.Lib:Clone())
-local pair = jecs.pair
-local ecs = jecs.world()
-local mirror = require(ReplicatedStorage.mirror:Clone())
-local mcs = mirror.world()
-
-local C1 = ecs:component()
-local C2 = ecs:entity()
-ecs:add(C2, pair(jecs.OnDeleteTarget, jecs.Delete))
-ecs:add(C2, jecs.Exclusive)
-
-local C3 = ecs:entity()
-ecs:add(C3, pair(jecs.OnDeleteTarget, jecs.Delete))
-local C4 = ecs:entity()
-ecs:add(C4, pair(jecs.OnDeleteTarget, jecs.Delete))
-local E1 = mcs:component()
-local E2 = mcs:entity()
-mcs:add(E2, pair(jecs.OnDeleteTarget, jecs.Delete))
-local E3 = mcs:entity()
-mcs:add(E3, pair(jecs.OnDeleteTarget, jecs.Delete))
-local E4 = mcs:entity()
-mcs:add(E4, pair(jecs.OnDeleteTarget, jecs.Delete))
-
-return {
-	ParameterGenerator = function()
-	end,
-
-	Functions = {
-		Mirror = function()
-			local m = mcs:entity()
-			for i = 1, 100 do
-				mcs:add(m, pair(E2, E3))
-				mcs:remove(m, pair(E2, E3))
-				mcs:add(m, pair(E2, E4))
-			end
-		end,
-
-		Jecs = function()
-			local j = ecs:entity()
-			for i = 1, 100 do
-				ecs:add(j, pair(C2, C3))
-				ecs:add(j, pair(C2, C4))
-			end
-		end,
-	},
-}

benches/visual/spawn.bench.luau

@@ -2,32 +2,37 @@
 --!native
 
 local ReplicatedStorage = game:GetService("ReplicatedStorage")
-local jecs = require(ReplicatedStorage.Lib:Clone())
-local mirror = require(ReplicatedStorage.mirror:Clone())
-
-
+local Matter = require(ReplicatedStorage.DevPackages.Matter)
+local ecr = require(ReplicatedStorage.DevPackages.ecr)
+local jecs = require(ReplicatedStorage.Lib)
+local rgb = require(ReplicatedStorage.rgb)
+local newWorld = Matter.World.new()
+local ecs = jecs.World.new()
 
 return {
 	ParameterGenerator = function()
-		local ecs = jecs.world()
-		ecs:range(1000, 20000)
-		local mcs = mirror.World.new()
-		return ecs, mcs
-	end,
+		local registry2 = ecr.registry()
+
+		return registry2
+	end;
 
 	Functions = {
-		Mirror = function(_, ecs, mcs)
-			for i = 1, 100 do
-
-				mcs:entity()
+		Matter = function()
+			for i = 1, 1000 do
+				newWorld:spawn()
 			end
-		end,
+		end;
 
-		Jecs = function(_, ecs, mcs)
-			for i = 1, 100 do
+		ECR = function(_, registry2)
+			for i = 1, 1000 do
+				registry2.create()
+			end
+		end;
 
+		Jecs = function()
+			for i = 1, 1000 do
 				ecs:entity()
 			end
-		end,
-},
+		end;
+	};
 }

default.project.json

@@ -1,6 +1,6 @@
 {
     "name": "jecs",
     "tree": {
-		"$path": "jecs.luau"
+      "$path": "src"
+    }
   }
-}

demo/.config/blink

@@ -0,0 +1,18 @@
+option ClientOutput = "../net/client.luau"
+option ServerOutput = "../net/server.luau"
+
+event UpdateTransform {
+    From: Server,
+    Type: Unreliable,
+    Call: SingleSync,
+    Poll: true,
+    Data: (f64, CFrame)
+}
+
+event SpawnMob {
+    From: Server,
+    Type: Reliable,
+    Call: SingleSync,
+    Poll: true,
+    Data: (f64, CFrame, u8)
+}

demo/default.project.json

@@ -1,13 +1,15 @@
 {
     "name": "demo",
-	"emitLegacyScripts": false,
     "tree": {
         "$className": "DataModel",
         "ReplicatedStorage": {
             "$className": "ReplicatedStorage",
             "$path": "src/ReplicatedStorage",
             "ecs": {
-				"$path": "../jecs.luau"
+                "$path": "../src"
+            },
+            "net": {
+                "$path": "net/client.luau"
             },
             "Packages": {
                 "$path": "Packages"
@@ -15,7 +17,10 @@
         },
         "ServerScriptService": {
             "$className": "ServerScriptService",
-			"$path": "src/ServerScriptService"
+            "$path": "src/ServerScriptService",
+            "net": {
+                "$path": "net/server.luau"
+            }
         },
         "Workspace": {
             "$properties": {
@@ -25,16 +30,32 @@
                 "$className": "Part",
                 "$properties": {
                     "Anchored": true,
-					"Color": [0.38823, 0.37254, 0.38823],
+                    "Color": [
+                        0.38823,
+                        0.37254,
+                        0.38823
+                    ],
                     "Locked": true,
-					"Position": [0, -10, 0],
-					"Size": [512, 20, 512]
+                    "Position": [
+                        0,
+                        -10,
+                        0
+                    ],
+                    "Size": [
+                        512,
+                        20,
+                        512
+                    ]
                 }
             }
         },
         "Lighting": {
             "$properties": {
-				"Ambient": [0, 0, 0],
+                "Ambient": [
+                    0,
+                    0,
+                    0
+                ],
                 "Brightness": 2,
                 "GlobalShadows": true,
                 "Outlines": false,

demo/net/client.luau

@@ -0,0 +1,337 @@
+--!strict
+--!native
+--!optimize 2
+--!nolint LocalShadow
+--#selene: allow(shadowing)
+-- File generated by Blink v0.14.1 (https://github.com/1Axen/Blink)
+-- This file is not meant to be edited
+
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local RunService = game:GetService("RunService")
+
+if not RunService:IsClient() then
+    error("Client network module can only be required from the client.")
+end
+
+local Reliable: RemoteEvent = ReplicatedStorage:WaitForChild("BLINK_RELIABLE_REMOTE") :: RemoteEvent
+local Unreliable: UnreliableRemoteEvent = ReplicatedStorage:WaitForChild("BLINK_UNRELIABLE_REMOTE") :: UnreliableRemoteEvent
+
+local Invocations = 0
+
+local SendSize = 64
+local SendOffset = 0
+local SendCursor = 0
+local SendBuffer = buffer.create(64)
+local SendInstances = {}
+
+local RecieveCursor = 0
+local RecieveBuffer = buffer.create(64)
+
+local RecieveInstances = {}
+local RecieveInstanceCursor = 0
+
+type Entry = {
+    value: any,
+    next: Entry?
+}
+
+type Queue = {
+    head: Entry?,
+    tail: Entry?
+}
+
+type BufferSave = {
+    Size: number, 
+    Cursor: number, 
+    Buffer: buffer, 
+    Instances: {Instance}
+}
+
+local function Read(Bytes: number)
+    local Offset = RecieveCursor
+    RecieveCursor += Bytes
+    return Offset
+end
+
+local function Save(): BufferSave
+    return {
+        Size = SendSize,
+        Cursor = SendCursor,
+        Buffer = SendBuffer,
+        Instances = SendInstances
+    }
+end
+
+local function Load(Save: BufferSave?)
+    if Save then
+        SendSize = Save.Size
+        SendCursor = Save.Cursor
+        SendOffset = Save.Cursor
+        SendBuffer = Save.Buffer
+        SendInstances = Save.Instances
+        return
+    end
+
+    SendSize = 64
+    SendCursor = 0
+    SendOffset = 0
+    SendBuffer = buffer.create(64)
+    SendInstances = {}
+end
+
+local function Invoke()
+    if Invocations == 255 then
+        Invocations = 0
+    end
+
+    local Invocation = Invocations
+    Invocations += 1
+    return Invocation
+end
+
+local function Allocate(Bytes: number)
+    local InUse = (SendCursor + Bytes)
+    if InUse > SendSize then
+        --> Avoid resizing the buffer for every write
+        while InUse > SendSize do
+            SendSize *= 1.5
+        end
+
+        local Buffer = buffer.create(SendSize)
+        buffer.copy(Buffer, 0, SendBuffer, 0, SendCursor)
+        SendBuffer = Buffer
+    end
+
+    SendOffset = SendCursor
+    SendCursor += Bytes
+    
+    return SendOffset
+end
+
+local function CreateQueue(): Queue
+    return {
+        head = nil,
+        tail = nil
+    }
+end
+
+local function Pop(queue: Queue): any
+    local head = queue.head
+    if head == nil then
+        return
+    end
+
+    queue.head = head.next
+    return head.value
+end
+
+local function Push(queue: Queue, value: any)
+    local entry: Entry = {
+        value = value,
+        next = nil
+    }
+
+    if queue.tail ~= nil then
+        queue.tail.next = entry
+    end
+
+    queue.tail = entry
+
+    if queue.head == nil then
+        queue.head = entry
+    end
+end
+
+local Types = {}
+local Calls = table.create(256)
+
+local Events: any = {
+    Reliable = table.create(256),
+    Unreliable = table.create(256)
+}
+
+local Queue: any = {
+    Reliable = table.create(256),
+    Unreliable = table.create(256)
+}
+
+Queue.Unreliable[0] = CreateQueue()
+Queue.Reliable[0] = CreateQueue()
+
+function Types.ReadEVENT_UpdateTransform(): (number, CFrame)
+	-- Read BLOCK: 32 bytes
+	local BLOCK_START = Read(32)
+	local Value1 = buffer.readf64(RecieveBuffer, BLOCK_START + 0)
+	local X = buffer.readf32(RecieveBuffer, BLOCK_START + 8)
+	local Y = buffer.readf32(RecieveBuffer, BLOCK_START + 12)
+	local Z = buffer.readf32(RecieveBuffer, BLOCK_START + 16)
+	local Position = Vector3.new(X, Y, Z)
+	local rX = buffer.readf32(RecieveBuffer, BLOCK_START + 20)
+	local rY = buffer.readf32(RecieveBuffer, BLOCK_START + 24)
+	local rZ = buffer.readf32(RecieveBuffer, BLOCK_START + 28)
+	local Value2 = CFrame.new(Position) * CFrame.fromOrientation(rX, rY, rZ)
+	return Value1, Value2
+end
+
+function Types.WriteEVENT_UpdateTransform(Value1: number, Value2: CFrame): ()
+	-- Allocate BLOCK: 33 bytes
+	local BLOCK_START = Allocate(33)
+	buffer.writeu8(SendBuffer, BLOCK_START + 0, 0)
+	buffer.writef64(SendBuffer, BLOCK_START + 1, Value1)
+	local Vector = Value2.Position
+	buffer.writef32(SendBuffer, BLOCK_START + 9, Vector.X)
+	buffer.writef32(SendBuffer, BLOCK_START + 13, Vector.Y)
+	buffer.writef32(SendBuffer, BLOCK_START + 17, Vector.Z)
+	local rX, rY, rZ = Value2:ToOrientation()
+	buffer.writef32(SendBuffer, BLOCK_START + 21, rX)
+	buffer.writef32(SendBuffer, BLOCK_START + 25, rY)
+	buffer.writef32(SendBuffer, BLOCK_START + 29, rZ)
+end
+
+function Types.ReadEVENT_SpawnMob(): (number, CFrame, number)
+	-- Read BLOCK: 33 bytes
+	local BLOCK_START = Read(33)
+	local Value1 = buffer.readf64(RecieveBuffer, BLOCK_START + 0)
+	local X = buffer.readf32(RecieveBuffer, BLOCK_START + 8)
+	local Y = buffer.readf32(RecieveBuffer, BLOCK_START + 12)
+	local Z = buffer.readf32(RecieveBuffer, BLOCK_START + 16)
+	local Position = Vector3.new(X, Y, Z)
+	local rX = buffer.readf32(RecieveBuffer, BLOCK_START + 20)
+	local rY = buffer.readf32(RecieveBuffer, BLOCK_START + 24)
+	local rZ = buffer.readf32(RecieveBuffer, BLOCK_START + 28)
+	local Value2 = CFrame.new(Position) * CFrame.fromOrientation(rX, rY, rZ)
+	local Value3 = buffer.readu8(RecieveBuffer, BLOCK_START + 32)
+	return Value1, Value2, Value3
+end
+
+function Types.WriteEVENT_SpawnMob(Value1: number, Value2: CFrame, Value3: number): ()
+	-- Allocate BLOCK: 34 bytes
+	local BLOCK_START = Allocate(34)
+	buffer.writeu8(SendBuffer, BLOCK_START + 0, 0)
+	buffer.writef64(SendBuffer, BLOCK_START + 1, Value1)
+	local Vector = Value2.Position
+	buffer.writef32(SendBuffer, BLOCK_START + 9, Vector.X)
+	buffer.writef32(SendBuffer, BLOCK_START + 13, Vector.Y)
+	buffer.writef32(SendBuffer, BLOCK_START + 17, Vector.Z)
+	local rX, rY, rZ = Value2:ToOrientation()
+	buffer.writef32(SendBuffer, BLOCK_START + 21, rX)
+	buffer.writef32(SendBuffer, BLOCK_START + 25, rY)
+	buffer.writef32(SendBuffer, BLOCK_START + 29, rZ)
+	buffer.writeu8(SendBuffer, BLOCK_START + 33, Value3)
+end
+
+
+local function StepReplication()
+    if SendCursor <= 0 then
+        return
+    end
+
+    local Buffer = buffer.create(SendCursor)
+    buffer.copy(Buffer, 0, SendBuffer, 0, SendCursor)
+    Reliable:FireServer(Buffer, SendInstances)
+
+    SendSize = 64
+    SendCursor = 0
+    SendOffset = 0
+    SendBuffer = buffer.create(64)
+    table.clear(SendInstances)
+end
+
+local Elapsed = 0
+RunService.Heartbeat:Connect(function(DeltaTime: number)
+	Elapsed += DeltaTime
+	if Elapsed >= (1 / 61) then
+		Elapsed -= (1 / 61)
+		StepReplication()
+	end
+end)
+
+Reliable.OnClientEvent:Connect(function(Buffer: buffer, Instances: {Instance})
+	RecieveCursor = 0
+	RecieveBuffer = Buffer
+	RecieveInstances = Instances
+	RecieveInstanceCursor = 0
+	local Size = buffer.len(RecieveBuffer)
+	while (RecieveCursor < Size) do
+		-- Read BLOCK: 1 bytes
+		local BLOCK_START = Read(1)
+		local Index = buffer.readu8(RecieveBuffer, BLOCK_START + 0)
+		if Index == 0 then
+			Push(Queue.Reliable[0], table.pack(Types.ReadEVENT_SpawnMob()))
+		end
+	end
+end)
+
+Unreliable.OnClientEvent:Connect(function(Buffer: buffer, Instances: {Instance})
+	RecieveCursor = 0
+	RecieveBuffer = Buffer
+	RecieveInstances = Instances
+	RecieveInstanceCursor = 0
+	local Size = buffer.len(RecieveBuffer)
+	while (RecieveCursor < Size) do
+		-- Read BLOCK: 1 bytes
+		local BLOCK_START = Read(1)
+		local Index = buffer.readu8(RecieveBuffer, BLOCK_START + 0)
+		if Index == 0 then
+			Push(Queue.Unreliable[0], table.pack(Types.ReadEVENT_UpdateTransform()))
+		end
+	end
+end)
+
+return {
+	StepReplication = StepReplication,
+
+	UpdateTransform = {
+		Iter = function(): () -> (number, number, CFrame)
+			local index = 0
+			local queue = Queue.Unreliable[0]
+			return function (): (number, number, CFrame)
+				index += 1
+				local arguments = Pop(queue)
+				if arguments ~= nil then
+					return index, unpack(arguments, 1, arguments.n)
+				end
+				return 
+			end
+		end,
+		Next = function(): () -> (number, number, CFrame)
+			local index = 0
+			local queue = Queue.Unreliable[0]
+			return function (): (number, number, CFrame)
+				index += 1
+				local arguments = Pop(queue)
+				if arguments ~= nil then
+					return index, unpack(arguments, 1, arguments.n)
+				end
+				return 
+			end
+		end
+	},
+	SpawnMob = {
+		Iter = function(): () -> (number, number, CFrame, number)
+			local index = 0
+			local queue = Queue.Reliable[0]
+			return function (): (number, number, CFrame, number)
+				index += 1
+				local arguments = Pop(queue)
+				if arguments ~= nil then
+					return index, unpack(arguments, 1, arguments.n)
+				end
+				return 
+			end
+		end,
+		Next = function(): () -> (number, number, CFrame, number)
+			local index = 0
+			local queue = Queue.Reliable[0]
+			return function (): (number, number, CFrame, number)
+				index += 1
+				local arguments = Pop(queue)
+				if arguments ~= nil then
+					return index, unpack(arguments, 1, arguments.n)
+				end
+				return 
+			end
+		end
+	},
+
+}

demo/net/server.luau

@@ -0,0 +1,374 @@
+--!strict
+--!native
+--!optimize 2
+--!nolint LocalShadow
+--#selene: allow(shadowing)
+-- File generated by Blink v0.14.1 (https://github.com/1Axen/Blink)
+-- This file is not meant to be edited
+
+local Players = game:GetService("Players")
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local RunService = game:GetService("RunService")
+
+if not RunService:IsServer() then
+    error("Server network module can only be required from the server.")
+end
+
+local Reliable: RemoteEvent = ReplicatedStorage:FindFirstChild("BLINK_RELIABLE_REMOTE") :: RemoteEvent
+if not Reliable then
+    local RemoteEvent = Instance.new("RemoteEvent")
+    RemoteEvent.Name = "BLINK_RELIABLE_REMOTE"
+    RemoteEvent.Parent = ReplicatedStorage
+    Reliable = RemoteEvent
+end
+
+local Unreliable: UnreliableRemoteEvent = ReplicatedStorage:FindFirstChild("BLINK_UNRELIABLE_REMOTE") :: UnreliableRemoteEvent
+if not Unreliable then
+    local UnreliableRemoteEvent = Instance.new("UnreliableRemoteEvent")
+    UnreliableRemoteEvent.Name = "BLINK_UNRELIABLE_REMOTE"
+    UnreliableRemoteEvent.Parent = ReplicatedStorage
+    Unreliable = UnreliableRemoteEvent
+end
+
+local Invocations = 0
+
+local SendSize = 64
+local SendOffset = 0
+local SendCursor = 0
+local SendBuffer = buffer.create(64)
+local SendInstances = {}
+
+local RecieveCursor = 0
+local RecieveBuffer = buffer.create(64)
+
+local RecieveInstances = {}
+local RecieveInstanceCursor = 0
+
+type Entry = {
+    value: any,
+    next: Entry?
+}
+
+type Queue = {
+    head: Entry?,
+    tail: Entry?
+}
+
+type BufferSave = {
+    Size: number, 
+    Cursor: number, 
+    Buffer: buffer, 
+    Instances: {Instance}
+}
+
+local function Read(Bytes: number)
+    local Offset = RecieveCursor
+    RecieveCursor += Bytes
+    return Offset
+end
+
+local function Save(): BufferSave
+    return {
+        Size = SendSize,
+        Cursor = SendCursor,
+        Buffer = SendBuffer,
+        Instances = SendInstances
+    }
+end
+
+local function Load(Save: BufferSave?)
+    if Save then
+        SendSize = Save.Size
+        SendCursor = Save.Cursor
+        SendOffset = Save.Cursor
+        SendBuffer = Save.Buffer
+        SendInstances = Save.Instances
+        return
+    end
+
+    SendSize = 64
+    SendCursor = 0
+    SendOffset = 0
+    SendBuffer = buffer.create(64)
+    SendInstances = {}
+end
+
+local function Invoke()
+    if Invocations == 255 then
+        Invocations = 0
+    end
+
+    local Invocation = Invocations
+    Invocations += 1
+    return Invocation
+end
+
+local function Allocate(Bytes: number)
+    local InUse = (SendCursor + Bytes)
+    if InUse > SendSize then
+        --> Avoid resizing the buffer for every write
+        while InUse > SendSize do
+            SendSize *= 1.5
+        end
+
+        local Buffer = buffer.create(SendSize)
+        buffer.copy(Buffer, 0, SendBuffer, 0, SendCursor)
+        SendBuffer = Buffer
+    end
+
+    SendOffset = SendCursor
+    SendCursor += Bytes
+    
+    return SendOffset
+end
+
+local function CreateQueue(): Queue
+    return {
+        head = nil,
+        tail = nil
+    }
+end
+
+local function Pop(queue: Queue): any
+    local head = queue.head
+    if head == nil then
+        return
+    end
+
+    queue.head = head.next
+    return head.value
+end
+
+local function Push(queue: Queue, value: any)
+    local entry: Entry = {
+        value = value,
+        next = nil
+    }
+
+    if queue.tail ~= nil then
+        queue.tail.next = entry
+    end
+
+    queue.tail = entry
+
+    if queue.head == nil then
+        queue.head = entry
+    end
+end
+
+local Types = {}
+local Calls = table.create(256)
+
+local Events: any = {
+    Reliable = table.create(256),
+    Unreliable = table.create(256)
+}
+
+local Queue: any = {
+    Reliable = table.create(256),
+    Unreliable = table.create(256)
+}
+
+
+function Types.ReadEVENT_UpdateTransform(): (number, CFrame)
+	-- Read BLOCK: 32 bytes
+	local BLOCK_START = Read(32)
+	local Value1 = buffer.readf64(RecieveBuffer, BLOCK_START + 0)
+	local X = buffer.readf32(RecieveBuffer, BLOCK_START + 8)
+	local Y = buffer.readf32(RecieveBuffer, BLOCK_START + 12)
+	local Z = buffer.readf32(RecieveBuffer, BLOCK_START + 16)
+	local Position = Vector3.new(X, Y, Z)
+	local rX = buffer.readf32(RecieveBuffer, BLOCK_START + 20)
+	local rY = buffer.readf32(RecieveBuffer, BLOCK_START + 24)
+	local rZ = buffer.readf32(RecieveBuffer, BLOCK_START + 28)
+	local Value2 = CFrame.new(Position) * CFrame.fromOrientation(rX, rY, rZ)
+	return Value1, Value2
+end
+
+function Types.WriteEVENT_UpdateTransform(Value1: number, Value2: CFrame): ()
+	-- Allocate BLOCK: 33 bytes
+	local BLOCK_START = Allocate(33)
+	buffer.writeu8(SendBuffer, BLOCK_START + 0, 0)
+	buffer.writef64(SendBuffer, BLOCK_START + 1, Value1)
+	local Vector = Value2.Position
+	buffer.writef32(SendBuffer, BLOCK_START + 9, Vector.X)
+	buffer.writef32(SendBuffer, BLOCK_START + 13, Vector.Y)
+	buffer.writef32(SendBuffer, BLOCK_START + 17, Vector.Z)
+	local rX, rY, rZ = Value2:ToOrientation()
+	buffer.writef32(SendBuffer, BLOCK_START + 21, rX)
+	buffer.writef32(SendBuffer, BLOCK_START + 25, rY)
+	buffer.writef32(SendBuffer, BLOCK_START + 29, rZ)
+end
+
+function Types.ReadEVENT_SpawnMob(): (number, CFrame, number)
+	-- Read BLOCK: 33 bytes
+	local BLOCK_START = Read(33)
+	local Value1 = buffer.readf64(RecieveBuffer, BLOCK_START + 0)
+	local X = buffer.readf32(RecieveBuffer, BLOCK_START + 8)
+	local Y = buffer.readf32(RecieveBuffer, BLOCK_START + 12)
+	local Z = buffer.readf32(RecieveBuffer, BLOCK_START + 16)
+	local Position = Vector3.new(X, Y, Z)
+	local rX = buffer.readf32(RecieveBuffer, BLOCK_START + 20)
+	local rY = buffer.readf32(RecieveBuffer, BLOCK_START + 24)
+	local rZ = buffer.readf32(RecieveBuffer, BLOCK_START + 28)
+	local Value2 = CFrame.new(Position) * CFrame.fromOrientation(rX, rY, rZ)
+	local Value3 = buffer.readu8(RecieveBuffer, BLOCK_START + 32)
+	return Value1, Value2, Value3
+end
+
+function Types.WriteEVENT_SpawnMob(Value1: number, Value2: CFrame, Value3: number): ()
+	-- Allocate BLOCK: 34 bytes
+	local BLOCK_START = Allocate(34)
+	buffer.writeu8(SendBuffer, BLOCK_START + 0, 0)
+	buffer.writef64(SendBuffer, BLOCK_START + 1, Value1)
+	local Vector = Value2.Position
+	buffer.writef32(SendBuffer, BLOCK_START + 9, Vector.X)
+	buffer.writef32(SendBuffer, BLOCK_START + 13, Vector.Y)
+	buffer.writef32(SendBuffer, BLOCK_START + 17, Vector.Z)
+	local rX, rY, rZ = Value2:ToOrientation()
+	buffer.writef32(SendBuffer, BLOCK_START + 21, rX)
+	buffer.writef32(SendBuffer, BLOCK_START + 25, rY)
+	buffer.writef32(SendBuffer, BLOCK_START + 29, rZ)
+	buffer.writeu8(SendBuffer, BLOCK_START + 33, Value3)
+end
+
+
+local PlayersMap: {[Player]: BufferSave} = {}
+
+Players.PlayerRemoving:Connect(function(Player)
+    PlayersMap[Player] = nil
+end)
+
+local function StepReplication()
+    for Player, Send in PlayersMap do
+        if Send.Cursor <= 0 then
+            continue
+        end
+
+        local Buffer = buffer.create(Send.Cursor)
+        buffer.copy(Buffer, 0, Send.Buffer, 0, Send.Cursor)
+        Reliable:FireClient(Player, Buffer, Send.Instances)
+
+        Send.Size = 64
+        Send.Cursor = 0
+        Send.Buffer = buffer.create(64)
+        table.clear(Send.Instances)
+    end
+end
+
+RunService.Heartbeat:Connect(StepReplication)
+
+Reliable.OnServerEvent:Connect(function(Player: Player, Buffer: buffer, Instances: {Instance})
+	RecieveCursor = 0
+	RecieveBuffer = Buffer
+	RecieveInstances = Instances
+	RecieveInstanceCursor = 0
+	local Size = buffer.len(RecieveBuffer)
+	while (RecieveCursor < Size) do
+		-- Read BLOCK: 1 bytes
+		local BLOCK_START = Read(1)
+		local Index = buffer.readu8(RecieveBuffer, BLOCK_START + 0)
+	end
+end)
+
+Unreliable.OnServerEvent:Connect(function(Player: Player, Buffer: buffer, Instances: {Instance})
+	RecieveCursor = 0
+	RecieveBuffer = Buffer
+	RecieveInstances = Instances
+	RecieveInstanceCursor = 0
+	local Size = buffer.len(RecieveBuffer)
+	while (RecieveCursor < Size) do
+		-- Read BLOCK: 1 bytes
+		local BLOCK_START = Read(1)
+		local Index = buffer.readu8(RecieveBuffer, BLOCK_START + 0)
+	end
+end)
+
+return {
+	StepReplication = StepReplication,
+
+	UpdateTransform = {
+		Fire = function(Player: Player, Value1: number, Value2: CFrame): ()
+			Load()
+			Types.WriteEVENT_UpdateTransform(Value1, Value2)
+			local Buffer = buffer.create(SendCursor)
+			buffer.copy(Buffer, 0, SendBuffer, 0, SendCursor)
+			Unreliable:FireClient(Player, Buffer, SendInstances)
+		end,
+		FireAll = function(Value1: number, Value2: CFrame): ()
+			Load()
+			Types.WriteEVENT_UpdateTransform(Value1, Value2)
+			local Buffer = buffer.create(SendCursor)
+			buffer.copy(Buffer, 0, SendBuffer, 0, SendCursor)
+			Unreliable:FireAllClients(Buffer, SendInstances)
+		end,
+		FireList = function(List: {Player}, Value1: number, Value2: CFrame): ()
+			Load()
+			Types.WriteEVENT_UpdateTransform(Value1, Value2)
+			local Buffer = buffer.create(SendCursor)
+			buffer.copy(Buffer, 0, SendBuffer, 0, SendCursor)
+			for _, Player in List do
+				Unreliable:FireClient(Player, Buffer, SendInstances)
+			end
+		end,
+		FireExcept = function(Except: Player, Value1: number, Value2: CFrame): ()
+			Load()
+			Types.WriteEVENT_UpdateTransform(Value1, Value2)
+			local Buffer = buffer.create(SendCursor)
+			buffer.copy(Buffer, 0, SendBuffer, 0, SendCursor)
+			for _, Player in Players:GetPlayers() do
+				if Player == Except then
+					continue
+				end
+				Unreliable:FireClient(Player, Buffer, SendInstances)
+			end
+		end,
+	},
+	SpawnMob = {
+		Fire = function(Player: Player, Value1: number, Value2: CFrame, Value3: number): ()
+			Load(PlayersMap[Player])
+			Types.WriteEVENT_SpawnMob(Value1, Value2, Value3)
+			PlayersMap[Player] = Save()
+		end,
+		FireAll = function(Value1: number, Value2: CFrame, Value3: number): ()
+			Load()
+			Types.WriteEVENT_SpawnMob(Value1, Value2, Value3)
+			local Buffer, Size, Instances = SendBuffer, SendCursor, SendInstances
+			for _, Player in Players:GetPlayers() do
+				Load(PlayersMap[Player])
+				local Position = Allocate(Size)
+				buffer.copy(SendBuffer, Position, Buffer, 0, Size)
+				table.move(Instances, 1, #Instances, #SendInstances + 1, SendInstances)
+				PlayersMap[Player] = Save()
+			end
+		end,
+		FireList = function(List: {Player}, Value1: number, Value2: CFrame, Value3: number): ()
+			Load()
+			Types.WriteEVENT_SpawnMob(Value1, Value2, Value3)
+			local Buffer, Size, Instances = SendBuffer, SendCursor, SendInstances
+			for _, Player in List do
+				Load(PlayersMap[Player])
+				local Position = Allocate(Size)
+				buffer.copy(SendBuffer, Position, Buffer, 0, Size)
+				table.move(Instances, 1, #Instances, #SendInstances + 1, SendInstances)
+				PlayersMap[Player] = Save()
+			end
+		end,
+		FireExcept = function(Except: Player, Value1: number, Value2: CFrame, Value3: number): ()
+			Load()
+			Types.WriteEVENT_SpawnMob(Value1, Value2, Value3)
+			local Buffer, Size, Instances = SendBuffer, SendCursor, SendInstances
+			for _, Player in Players:GetPlayers() do
+				if Player == Except then
+					continue
+				end
+				Load(PlayersMap[Player])
+				local Position = Allocate(Size)
+				buffer.copy(SendBuffer, Position, Buffer, 0, Size)
+				table.move(Instances, 1, #Instances, #SendInstances + 1, SendInstances)
+				PlayersMap[Player] = Save()
+			end
+		end,
+	},
+
+}

demo/src/ReplicatedStorage/collect.luau

@@ -1,33 +0,0 @@
-
---!strict
-local function collect(signal)
-	local enqueued = {}
-
-	local i = 0
-
-	local connection = signal:Connect(function(...)
-		table.insert(enqueued, { ... })
-		i += 1
-	end)
-
-	return function(): any
-		if i == 0 then
-			return
-		end
-
-		i -= 1
-
-		local args: any = table.remove(enqueued, 1)
-
-		return unpack(args)
-	end, connection
-end
-
-type Signal<T... = ...any> = {
-    Connect: (self: Signal<T...>, callback: (T...) -> ()) -> RBXScriptConnection,
-    ConnectParallel: (self: Signal<T...>, callback: (T...) -> ()) -> RBXScriptConnection,
-    Once: (self: Signal<T...>, callback: (T...) -> ()) -> RBXScriptConnection,
-    Wait: (self: Signal<T...>) -> (T...)
-}
-
-return collect :: <T...>(Signal<T...>) -> (() -> (T...), RBXScriptConnection)

demo/src/ReplicatedStorage/components.luau

@@ -1,65 +0,0 @@
---!strict
-local RunService = game:GetService("RunService")
-local ReplicatedStorage = game:GetService("ReplicatedStorage")
-local jecs = require(ReplicatedStorage.ecs)
-local types = require("./types")
-
-local Networked = jecs.tag()
-local NetworkedPair = jecs.tag()
-
-local InstanceMapping = jecs.component() :: jecs.Id<Instance>
-jecs.meta(InstanceMapping, jecs.OnAdd, function(component)
-	jecs.meta(component, jecs.OnAdd, function(entity, _, instance)
-		if RunService:IsServer() then
-			instance:SetAttribute("entity_server")
-		else
-			instance:SetAttribute("entity_client")
-		end
-	end)
-end)
-
-local function networked_id(ct)
-	jecs.meta(ct, Networked)
-	return ct
-end
-local function networked_pair(ct)
-	jecs.meta(ct, NetworkedPair)
-	return ct
-end
-local function instance_mapping_id(ct)
-	jecs.meta(ct, InstanceMapping)
-	return ct
-end
-
-local Renderable = jecs.component() :: types.Id<Instance>
-local Poison = jecs.component() :: types.Id<number>
-local Health = jecs.component() :: types.Id<number>
-local Player = jecs.component() :: types.Id<Player>
-local Debuff = jecs.tag() :: types.Entity
-local Lifetime = jecs.component() :: types.Id<{
-	duration: number,
-	created: number
-}>
-local Destroy = jecs.tag()
-
-local components = {
-	Renderable = networked_id(instance_mapping_id(Renderable)),
-	Player = networked_id(Player),
-	Poison = networked_id(Poison),
-	Health = networked_id(Health),
-	Lifetime = networked_id(Lifetime),
-	Debuff = networked_id(Debuff),
-	Destroy = networked_id(Destroy),
-
-	-- We have to define that some builtin IDs can also be networked
-	ChildOf = networked_pair(jecs.ChildOf),
-
-	Networked = Networked,
-	NetworkedPair = NetworkedPair,
-}
-
-for name, component in components :: {[string]: types.Id<any> } do
-	jecs.meta(component, jecs.Name, name)
-end
-
-return components

demo/src/ReplicatedStorage/ecs_init.luau

@@ -0,0 +1,4 @@
+_G.JECS_DEBUG = true
+_G.JECS_HI_COMPONENT_ID = 32
+require(game:GetService("ReplicatedStorage").ecs)
+return

demo/src/ReplicatedStorage/main.client.luau

@@ -1,10 +0,0 @@
-local ReplicatedStorage = game:GetService("ReplicatedStorage")
-local jecs = require(ReplicatedStorage.ecs)
-local schedule = require(ReplicatedStorage.schedule)
-
-local heartbeat = schedule(world,
-	systems.entities_delete,
-	systems.replication
-)
-
-game:GetService("RunService").Heartbeat:Connect(heartbeat)

demo/src/ReplicatedStorage/remotes.luau

@@ -1,42 +0,0 @@
-local ReplicatedStorage = game:GetService("ReplicatedStorage")
-local types = require("../ReplicatedStorage/types")
-
-type Remote<T...> = {
-	FireClient: (Remote<T...>, Player, T...) -> (),
-	FireAllClients: (Remote<T...>, T...) -> (),
-	FireServer: (Remote<T...>, T...) -> (),
-	OnServerEvent: RBXScriptSignal<(Player, T...)>,
-	OnClientEvent: RBXScriptSignal<T...>
-}
-
-local function stream_ensure(name)
-	local remote = ReplicatedStorage:FindFirstChild(name)
-	if not remote then
-		remote = Instance.new("RemoteEvent")
-		remote.Name = name
-		remote.Parent = ReplicatedStorage
-	end
-	return remote
-end
-
-local function datagram_ensure(name)
-	local remote = ReplicatedStorage:FindFirstChild(name)
-	if not remote then
-		remote = Instance.new("UnreliableRemoteEvent")
-		remote.Name = name
-		remote.Parent = ReplicatedStorage
-	end
-	return remote
-end
-
-return {
-	input = datagram_ensure("input") :: Remote<string>,
-	replication = stream_ensure("replication") :: Remote<{
-		[string]: {
-			set: { types.Entity }?,
-			values: { any }?,
-			removed: { types.Entity }?
-		}
-	}>,
-
-}

demo/src/ReplicatedStorage/schedule.luau

@@ -1,91 +0,0 @@
---!strict
-local ReplicatedStorage = game:GetService("ReplicatedStorage")
-local jabby = require(ReplicatedStorage.Packages.jabby)
-local ct = require(ReplicatedStorage.components)
-local jecs = require(ReplicatedStorage.ecs)
-
-jabby.set_check_function(function(player) return true end)
-
-local scheduler = jabby.scheduler.create()
-
-jabby.register({
-	applet = jabby.applets.scheduler,
-	name = "Scheduler",
-	configuration = {
-		scheduler = scheduler,
-	},
-}::any)
-
-local ContextActionService = game:GetService("ContextActionService")
-
-local function create_widget(_, state: Enum.UserInputState): Enum.ContextActionResult
-	local client = jabby.obtain_client()
-    if state ~= Enum.UserInputState.Begin then
-    	return Enum.ContextActionResult.Pass
-    end
-    client.spawn_app(client.apps.home::any, nil)
-    return Enum.ContextActionResult.Sink
-end
-
-local RunService = game:GetService("RunService")
-
-local function schedule(world, ...)
-	local function get_entity_from_part(part: BasePart): (jecs.Entity<any>?, PVInstance?)
-		for id, model in world:query(ct.Renderable) do
-			if not part:IsDescendantOf(model) then continue end
-			return id, model
-		end
-		return nil, nil
-	end
-
-	jabby.register({
-		applet = jabby.applets.world,
-		name = "World",
-		configuration = {
-			world = world,
-			get_entity_from_part = get_entity_from_part,
-		},
-	}::any)
-
-	local systems = { ... }
-
-	local function systems_load(mod: ModuleScript, ...)
-		local fn = require(mod) :: (...any) -> ()
-		local system = fn(...) or fn
-
-		local system_id = scheduler:register_system({
-			name = mod.Name,
-			module = mod,
-		})
-
-		return {
-			system = system,
-			id = system_id
-		}
-	end
-
-	for i, mod in systems do
-		systems[i] = systems_load(mod, world, 0)
-	end
-
-	if RunService:IsClient() then
-		ContextActionService:BindAction(
-			"Open Jabby Home",
-			create_widget,
-			false,
-			Enum.KeyCode.F4
-		)
-	end
-
-	return function(dt: number, input: InputObject?)
-		for i, config in systems do
-			-- config.system(world, dt, input)
-			local system = config.system
-			local id = config.id
-			scheduler:run(id, system,
-				world, dt, input)
-		end
-	end
-end
-
-return schedule

demo/src/ReplicatedStorage/start.luau

@@ -0,0 +1,34 @@
+local RunService = game:GetService("RunService")
+local UserInputService = game:GetService("UserInputService")
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local jabby = require(ReplicatedStorage.Packages.jabby)
+local std = require(ReplicatedStorage.std)
+local Scheduler = std.Scheduler
+local world = std.world
+
+local function start(modules)
+    local scheduler = Scheduler.new(world, require(ReplicatedStorage.std.components))
+    for _, module in modules do
+        require(module)(scheduler)
+    end
+    local events = scheduler.collect.all()
+    scheduler.systems.begin(events)
+
+    jabby.set_check_function(function(player)
+        return true
+    end)
+    if RunService:IsClient() then
+        local client = jabby.obtain_client()
+        local dtor
+        UserInputService.InputBegan:Connect(function(input)
+            if input.KeyCode == Enum.KeyCode.F4 then
+                if dtor then
+                    dtor()
+                end
+                dtor = client.spawn_app(client.apps.home)
+ 			end
+        end)
+	end
+end
+
+return start

demo/src/ReplicatedStorage/std/bt.luau

@@ -0,0 +1,40 @@
+--!optimize 2
+--!native
+
+-- original author @centau
+
+local SUCCESS = 0
+local FAILURE = 1
+local RUNNING = 2
+
+local function SEQUENCE(nodes)
+    return function(...)
+        for _, node in nodes do
+            local status = node(...)
+            if status == FAILURE or status == RUNNING then
+                return status
+            end
+        end
+        return SUCCESS
+    end
+end
+
+local function FALLBACK(nodes)
+    return function(...)
+        for _, node in nodes do
+            local status = node(...)
+            if status == SUCCESS or status == RUNNING then
+                return status
+            end
+        end
+        return FAILURE
+    end
+end
+
+local bt = {
+    SEQUENCE = SEQUENCE,
+    FALLBACK = FALLBACK,
+    RUNNING = RUNNING
+}
+
+return bt

demo/src/ReplicatedStorage/std/changetracker.luau

@@ -0,0 +1,133 @@
+local jecs = require(game:GetService("ReplicatedStorage").ecs)
+type World = jecs.World
+
+type Tracker<T> = { track: (world: World, fn: (changes: {
+        added: () -> () -> (number, T),
+        removed: () -> () -> number,
+        changed: () -> () -> (number, T, T)
+    }) -> ()) -> ()
+}
+
+type Entity<T = any> = number & { __nominal_type_dont_use: T }
+
+local function diff(a, b)
+    local size = 0
+    for k, v in a do
+        if b[k] ~= v then
+            return true
+        end
+        size += 1
+    end
+    for k, v in b do
+        size -= 1
+    end
+
+    if size ~= 0 then
+        return true
+    end
+
+    return false
+end
+
+local function ChangeTracker<T>(world: World, T: Entity<T>): Tracker<T>
+    local sparse = world.entityIndex.sparse
+    local PreviousT = jecs.pair(jecs.Rest, T)
+    local add = {}
+    local added
+    local removed
+    local is_trivial
+
+    local function changes_added()
+        added = true
+        local q = world:query(T):without(PreviousT):drain()
+        return function()
+            local id, data = q.next()
+            if not id then
+                return nil
+            end
+
+            is_trivial = typeof(data) ~= "table"
+
+            add[id] = data
+
+            return id, data
+        end
+    end
+
+    local function changes_changed()
+        local q = world:query(T, PreviousT):drain()
+
+        return function()
+            local id, new, old = q.next()
+            while true do
+                if not id then
+                    return nil
+                end
+
+                if not is_trivial then
+                    if diff(new, old) then
+                        break
+                    end
+                elseif new ~= old then
+                    break
+                end
+
+                id, new, old = q.next()
+            end
+
+            local record = sparse[id]
+            local archetype = record.archetype
+            local column = archetype.records[PreviousT].column
+            local data = if is_trivial then new else table.clone(new)
+            archetype.columns[column][record.row] = data
+
+            return id, old, new
+        end
+    end
+
+    local function changes_removed()
+        removed = true
+
+        local q = world:query(PreviousT):without(T):drain()
+        return function()
+            local id = q.next()
+            if id then
+                world:remove(id, PreviousT)
+            end
+            return id
+        end
+    end
+
+    local changes = {
+        added = changes_added,
+        changed = changes_changed,
+        removed = changes_removed,
+    }
+
+    local function track(fn)
+        added = false
+        removed = false
+
+        fn(changes)
+
+        if not added then
+            for _ in changes_added() do
+            end
+        end
+
+        if not removed then
+            for _ in changes_removed() do
+            end
+        end
+
+        for e, data in add do
+            world:set(e, PreviousT, if is_trivial then data else table.clone(data))
+        end
+    end
+
+    local tracker = { track = track }
+
+    return tracker
+end
+
+return ChangeTracker

demo/src/ReplicatedStorage/std/collect.luau

@@ -0,0 +1,67 @@
+--!nonstrict
+
+--[[
+	local signal = Signal.new() :: Signal.Signal<string, string>
+	local events = collect(signal)
+	local function system(world)
+		for id, str1, str2 in events do
+			--
+		end
+	end
+]]
+
+--[[
+original author by @memorycode
+
+MIT License
+
+Copyright (c) 2024 Michael
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+--]]
+
+type Signal<T...> = { [any]: any }
+local function collect<T...>(event: Signal<T...>)
+	local storage = {}
+	local mt = {}
+	local iter = function()
+		local n = #storage
+		return function()
+			if n <= 0 then
+				mt.__iter = nil
+				return nil
+			end
+
+			n -= 1
+			return n + 1, unpack(table.remove(storage, 1) :: any)
+		end
+	end
+
+	local disconnect = event:Connect(function(...)
+		table.insert(storage, { ... })
+		mt.__iter = iter
+	end)
+
+	setmetatable(storage, mt)
+	return (storage :: any) :: () -> (number, T...), function()
+		disconnect()
+	end
+end
+
+return collect

demo/src/ReplicatedStorage/std/components.luau

@@ -0,0 +1,25 @@
+local jecs = require(game:GetService("ReplicatedStorage").ecs)
+local world = require(script.Parent.world)
+
+type Entity<T=nil> = jecs.Entity<T>
+local components: {
+    Character: Entity<Model>,
+    Mob: Entity,
+    Model: Entity<Model>,
+    Player: Entity,
+    Target: Entity,
+    Transform: Entity<CFrame>,
+    Velocity: Entity<number>,
+    Previous: Entity,
+} = {
+    Character = world:component(),
+    Mob = world:component(),
+    Model = world:component(),
+    Player = world:component(),
+    Target = world:component(),
+    Transform = world:component(),
+    Velocity = world:component(),
+    Previous = world:component(),
+}
+
+return table.freeze(components)

demo/src/ReplicatedStorage/std/ctx.luau

@@ -0,0 +1,11 @@
+local world = require(script.Parent.world)
+local handle = require(script.Parent.handle)
+
+local singleton = world:entity()
+
+local function ctx()
+    -- Cannot cache handles because they will get invalidated
+    return handle(singleton)
+end
+
+return ctx

demo/src/ReplicatedStorage/std/handle.luau

@@ -0,0 +1,56 @@
+local jecs = require(game:GetService("ReplicatedStorage").ecs)
+local world = require(script.Parent.world)
+
+type Handle = {
+    has: (self: Handle, id: jecs.Entity) -> boolean,
+    get: <T>(self: Handle, id: jecs.Entity<T>) -> T?,
+    add: <T>(self: Handle, id: jecs.Entity<T>) -> Handle,
+    set: <T>(self: Handle, id: jecs.Entity<T>, value: T) -> Handle,
+    id: (self: Handle?) -> jecs.Entity
+}
+
+local handle: (e: jecs.Entity) -> Handle
+
+do
+    local e
+    local function has(_, id)
+        return world:has(e, id)
+    end
+    local function get(_, id)
+        return world:get(e, id)
+    end
+    local function set(self, id, value)
+        world:set(e, id, value)
+        return self
+    end
+    local function add(self, id)
+        world:add(e, id)
+        return self
+    end
+    local function clear(self)
+        world:clear(e)
+        return self
+    end
+    local function delete(self)
+        world:delete(e)
+    end
+    local function id()
+        return e
+    end
+
+    local entity = {
+        has = has,
+        get = get,
+        set = set,
+        add = add,
+        clear = clear,
+        id = id,
+    }
+
+    function handle(id)
+        e = id
+        return entity
+    end
+end
+
+return handle

demo/src/ReplicatedStorage/std/hooks.luau

@@ -0,0 +1,32 @@
+--!native
+--!optimize 2
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local jecs = require(ReplicatedStorage.ecs)
+
+local function create_cache(hook)
+    local columns = setmetatable({}, {
+        __index = function(self, component)
+            local column = {}
+            self[component] = column
+            return column
+        end
+    })
+
+    return function(world, component, fn)
+        local column = columns[component]
+        table.insert(column, fn)
+        world:set(component, hook, function(entity, value)
+            for _, callback in column do
+                callback(entity, value)
+            end
+        end)
+    end
+end
+
+local hooks = {
+    OnSet = create_cache(jecs.OnSet),
+    OnAdd = create_cache(jecs.OnAdd),
+    OnRemove = create_cache(jecs.OnRemove)
+}
+
+return hooks

demo/src/ReplicatedStorage/std/init.luau

@@ -0,0 +1,25 @@
+local jecs = require(game:GetService("ReplicatedStorage").ecs)
+
+local world = require(script.world) :: jecs.World
+export type World = jecs.World
+
+local Scheduler = require(script.scheduler)
+export type Scheduler = Scheduler.Scheduler
+
+local std = {
+    ChangeTracker = require(script.changetracker),
+    Scheduler = Scheduler,
+    bt = require(script.bt),
+    collect = require(script.collect),
+    components = require(script.components),
+    ctx = require(script.ctx),
+    handle = require(script.handle),
+    interval = require(script.interval),
+    ref = require(script.ref),
+    world = world :: World,
+    pair = jecs.pair,
+    __ = jecs.w,
+    hooks = require(script.hooks)
+}
+
+return std

demo/src/ReplicatedStorage/std/interval.luau

@@ -0,0 +1,19 @@
+local function interval(s)
+    local pin
+
+    local function throttle()
+        if not pin then
+            pin = os.clock()
+        end
+
+        local elapsed = os.clock() - pin > s
+        if elapsed then
+            pin = os.clock()
+        end
+
+        return elapsed
+    end
+    return throttle
+end
+
+return interval

demo/src/ReplicatedStorage/std/ref.luau

@@ -0,0 +1,24 @@
+local world = require(script.Parent.world)
+local handle = require(script.Parent.handle)
+local refs = {}
+
+local function fini(key)
+    return function()
+        refs[key] = nil
+    end
+end
+
+local function ref(key): (handle.Handle, (() -> ())?)
+    if not key then
+        return handle(world:entity())
+    end
+    local e = refs[key]
+    if not e then
+        e = world:entity()
+        refs[key] = e
+    end
+    -- Cannot cache handles because they will get invalidated
+    return handle(e), fini(key)
+end
+
+return ref

demo/src/ReplicatedStorage/std/registry.luau

@@ -0,0 +1,31 @@
+local reserved = 0
+
+local function reserve()
+    reserved += 1
+    return reserved
+end
+
+-- If you don't like passing around a world singleton
+-- and you need to register component IDs, just register them.
+-- I dont use this because I like adding component traits
+--[[
+    local components = {
+        Model = registry.reserve(),
+        Transform = registry.reserve(),
+    }
+
+    local world = registry.register(jecs.World.new())
+    local e = world:entity()
+    world:set(e, components.Transform, CFrame)
+]]
+local function register(world)
+    for _ = 1, reserved do
+        world:component()
+    end
+    return world
+end
+
+return {
+    reserve = reserve,
+    register = register,
+}

demo/src/ReplicatedStorage/std/scheduler.luau

@@ -0,0 +1,251 @@
+--!native
+--!optimize 2
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local jabby = require(ReplicatedStorage.Packages.jabby)
+local jecs = require(ReplicatedStorage.ecs)
+local pair = jecs.pair
+local Name = jecs.Name
+
+type World = jecs.World
+type Entity<T=nil> = jecs.Entity<T>
+
+type System = {
+    callback: (world: World) -> (),
+    id: number,
+}
+
+type Systems = { System }
+
+
+type Events = {
+    RenderStepped: Systems,
+    Heartbeat: Systems
+}
+
+export type Scheduler = {
+    components: {
+        Disabled: Entity,
+        System: Entity<System>,
+        Phase: Entity,
+        DependsOn: Entity
+    },
+
+    collect: {
+        under_event: (event: Entity) -> Systems,
+        all: () -> Events
+    },
+
+    systems: {
+        begin: (events: Events) -> { [Entity]: thread },
+        new: (callback: (dt: number) -> (), phase: Entity) -> Entity
+    },
+
+    phases: {
+        RenderStepped: Entity,
+        Heartbeat: Entity,
+    },
+
+    phase: (after: Entity) -> Entity,
+
+    debugging: boolean,
+}
+
+local scheduler_new: (w: World, components: { [string]: Entity }) -> Scheduler
+
+do
+    local world: World
+    local Disabled: Entity
+    local System: Entity<System>
+    local DependsOn: Entity
+    local Phase: Entity
+    local Event: Entity<RBXScriptSignal>
+
+    local scheduler
+
+    local RenderStepped
+    local Heartbeat
+    local PreAnimation
+    local PreSimulation
+
+    local sys: System
+    local dt
+
+    local function run()
+        local id = sys.id
+        local system_data = scheduler.system_data[id]
+		if system_data.paused then return end
+
+  		scheduler:mark_system_frame_start(id)
+        sys.callback(dt)
+        scheduler:mark_system_frame_end(id)
+    end
+
+    local function panic(str)
+        -- We don't want to interrupt the loop when we error
+        task.spawn(error, str)
+    end
+    local function begin(events: { Systems })
+        local threads = {}
+        for event, systems in events  do
+            if not event then continue end
+            local event_name = tostring(event)
+            threads[event] = task.spawn(function()
+                while true do
+                    dt = event:Wait()
+
+                    debug.profilebegin(event_name)
+                    for _, s in systems do
+                        sys = s
+                        local didNotYield, why = xpcall(function()
+                            for _ in run do break end
+                        end, debug.traceback)
+
+                        if didNotYield then
+            				continue
+             			end
+
+             			if string.find(why, "thread is not yieldable") then
+            				panic("Not allowed to yield in the systems."
+                				.. "\n"
+                				.. "System: "
+                				.. debug.info(s.callback, "n")
+                				.. " has been ejected"
+				            )
+            				continue
+             			end
+             			panic(why)
+                    end
+                    debug.profileend()
+                end
+            end)
+        end
+        return threads
+    end
+
+    local function scheduler_collect_systems_under_phase_recursive(systems, phase)
+        local phase_name = world:get(phase, Name)
+        for _, s in world:query(System):with(pair(DependsOn, phase)) do
+            table.insert(systems, {
+                id = scheduler:register_system({
+                    name = s.name,
+                    phase = phase_name
+                }),
+                callback = s.callback
+            })
+        end
+        for after in world:query(Phase):with(pair(DependsOn, phase)) do
+            scheduler_collect_systems_under_phase_recursive(systems, after)
+        end
+    end
+
+    local function scheduler_collect_systems_under_event(event)
+        local systems = {}
+        scheduler_collect_systems_under_phase_recursive(systems, event)
+        return systems
+    end
+
+    local function scheduler_collect_systems_all()
+        local events = {}
+        for phase, event in world:query(Event):with(Phase) do
+            events[event] = scheduler_collect_systems_under_event(phase)
+        end
+        return events
+    end
+
+    local function scheduler_phase_new(after)
+        local phase = world:entity()
+        world:add(phase, Phase)
+        local dependency = pair(DependsOn, after)
+        world:add(phase, dependency)
+        return phase
+    end
+
+    local function scheduler_systems_new(callback, phase)
+        local system = world:entity()
+        local name = debug.info(callback, "n")
+        world:set(system, System, { callback = callback, name = name })
+        world:add(system, pair(DependsOn, phase))
+        return system
+    end
+
+    function scheduler_new(w: World, components: { [string]: Entity })
+        world = w
+        Disabled = world:component()
+        System = world:component()
+        Phase = world:component()
+        DependsOn = world:component()
+        Event = world:component()
+
+        RenderStepped = world:component()
+        Heartbeat = world:component()
+        PreSimulation = world:component()
+        PreAnimation = world:component()
+
+        local RunService = game:GetService("RunService")
+        if RunService:IsClient() then
+            world:add(RenderStepped, Phase)
+            world:set(RenderStepped, Event, RunService.RenderStepped)
+        end
+
+        world:add(Heartbeat, Phase)
+        world:set(Heartbeat, Event, RunService.Heartbeat)
+
+        world:add(PreSimulation, Phase)
+        world:set(PreSimulation, Event, RunService.PreSimulation)
+
+        world:add(PreAnimation, Phase)
+        world:set(PreAnimation, Event, RunService.PreAnimation)
+
+        for name, component in components do
+            world:set(component, Name, name)
+        end
+
+        table.insert(jabby.public, {
+            class_name = "World",
+            name = "MyWorld",
+            world = world,
+            debug = Name,
+            entities = {}
+        })
+
+
+        jabby.public.updated = true
+        scheduler = jabby.scheduler.create("scheduler")
+
+        table.insert(jabby.public, scheduler)
+
+        return {
+            phase = scheduler_phase_new,
+
+            phases = {
+                RenderStepped = RenderStepped,
+                PreSimulation = PreSimulation,
+                Heartbeat = Heartbeat,
+                PreAnimation = PreAnimation
+            },
+
+            world = world,
+
+            components = {
+                DependsOn = DependsOn,
+                Disabled = Disabled,
+                Phase = Phase,
+                System = System,
+            },
+
+            collect = {
+                under_event = scheduler_collect_systems_under_event,
+                all = scheduler_collect_systems_all
+            },
+
+            systems = {
+                new = scheduler_systems_new,
+                begin = begin
+            }
+        }
+    end
+end
+
+return {
+    new = scheduler_new
+}

demo/src/ReplicatedStorage/std/world.luau

@@ -0,0 +1,4 @@
+local jecs = require(game:GetService("ReplicatedStorage").ecs)
+
+-- I like the idea of only having the world be a singleton.
+return jecs.World.new() :: jecs.World

demo/src/ReplicatedStorage/systems/entities_delete.luau

@@ -1,13 +0,0 @@
-
---!strict
-local ReplicatedStorage = game:GetService("ReplicatedStorage")
-local types = require(ReplicatedStorage.types)
-local ct = require(ReplicatedStorage.components)
-
-local function entities_delete(world: types.World, dt: number)
-	for e in world:each(ct.Destroy) do
-		world:delete(e)
-	end
-end
-
-return entities_delete

demo/src/ReplicatedStorage/systems/receive_replication.luau

@@ -1,121 +0,0 @@
-local types = require("../types")
-local jecs = require(game:GetService("ReplicatedStorage").ecs)
-local remotes = require("../remotes")
-local collect = require("../collect")
-local components = require("../components")
-
-
-local client_ids: {[jecs.Entity]: jecs.Entity } = {}
-
-local function ecs_ensure_entity(world: jecs.World, id: jecs.Entity)
-	local e = 0
-
-	local ser_id = id
-	local deser_id = client_ids[ser_id]
-	if deser_id then
-		if deser_id == 0 then
-			local new_id = world:entity()
-			client_ids[ser_id] = new_id
-			deser_id = new_id
-		end
-	else
-		if not world:exists(ser_id)
-			or (world:contains(ser_id) and not world:get(ser_id, jecs.Name))
-		then
-			deser_id = world:entity()
-		else
-			if world:contains(ser_id) and world:get(ser_id, jecs.Name) then
-				deser_id = ser_id
-			else
-				deser_id = world:entity()
-			end
-		end
-		client_ids[ser_id] = deser_id
-	end
-
-	e = deser_id
-
-	return e
-end
-
--- local rel_render = `e{jecs.ECS_ID(rel)}v{jecs.ECS_GENERATION(rel)}`
--- local tgt_render = `e{jecs.ECS_ID(tgt)}v{jecs.ECS_GENERATION(tgt)}`
--- local function ecs_deser_pairs_str(world, token)
--- 	local tokens = string.split(token, ",")
--- 	local rel = tonumber(tokens[1]) :: jecs.Entity
--- 	local tgt = tonumber(tokens[2]) :: jecs.Entity
-
--- 	rel = ecs_ensure_entity(world, rel)
--- 	tgt = ecs_ensure_entity(world, tgt)
-
--- 	return jecs.pair(rel, tgt)
--- end
-
-local function ecs_deser_pairs(world, rel, tgt)
-	rel = ecs_ensure_entity(world, rel)
-	tgt = ecs_ensure_entity(world, tgt)
-
-	return jecs.pair(rel, tgt)
-end
-
-local snapshots = collect(remotes.replication.OnClientEvent)
-
-return function(world: jecs.World)
-	for entity in world:each(components.Destroy) do
-		client_ids[entity] = nil
-	end
-    for snapshot in snapshots do
-        for ser_id, map in snapshot do
-        	local id = (tonumber(ser_id) :: any) :: jecs.Entity
-            if jecs.IS_PAIR(id) and map.pair then
-            	id = ecs_deser_pairs(world, map.relation, map.target)
-            elseif id then
-            	id = ecs_ensure_entity(world, id)
-            end
-            -- if not id then
-            --    	id = ecs_deser_pairs_str(world, ser_id)
-            -- else
-            --    	id = ecs_ensure_entity(world, id)
-            -- end
-            local members = world:get(id, components.NetworkedMembers)
-
-            local set = map.set
-            if set then
-                if jecs.is_tag(world, id) then
-                   	for _, entity in set do
-                       	entity = ecs_ensure_entity(world, entity)
-                  		world:add(entity, id)
-                   	end
-                else
-	                local values = map.values :: { any }
-	                for i, entity in set do
-						entity = ecs_ensure_entity(world, entity)
-						local value = values[i]
-						if members then
-							for _, member in members do
-								local data = value[member] :: {jecs.Entity} | jecs.Entity -- targets
-								if typeof(data) == "table" then
-									for pos, tgt in data :: { jecs.Entity } do
-										data[pos] = ecs_ensure_entity(world, tgt)
-									end
-								else
-									value[member] = ecs_ensure_entity(world, data :: any)
-								end
-							end
-						end
-						world:set(entity, id, value)
-                   	end
-			    end
-            end
-
-            local removed = map.removed
-
-            if removed then
-                for _, entity in removed do
-                    entity = ecs_ensure_entity(world, entity)
-                    world:remove(entity, id)
-                end
-            end
-        end
-    end
-end

demo/src/ReplicatedStorage/types.luau

@@ -1,14 +0,0 @@
-local jecs = require(game:GetService("ReplicatedStorage").ecs)
-
-export type World = typeof(jecs.world())
-export type Entity = jecs.Entity
-export type Id<T> = jecs.Id<T>
-export type Snapshot = {
-	[string]: {
-		set: { jecs.Entity }?,
-		values: { any }?,
-		removed: { jecs.Entity }?
-	}
-}
-
-return {}

demo/src/ServerScriptService/main.server.luau

@@ -1,21 +1,4 @@
 local ReplicatedStorage = game:GetService("ReplicatedStorage")
-local ServerScriptService = game:GetService("ServerScriptService")
-local jecs = require(ReplicatedStorage.ecs)
-local schedule = require(ReplicatedStorage.schedule)
+local start = require(ReplicatedStorage.start)
 
-require(ReplicatedStorage.components)
-local world = jecs.world()
-
-local systems = ServerScriptService.systems
-
-local heartbeat = schedule(world,
-	systems.players_added,
-	systems.poison_hurts,
-	systems.health_regen,
-	systems.lifetimes_expire,
-	systems.life_is_painful,
-	systems.entities_delete,
-	systems.replication
-)
-
-game:GetService("RunService").Heartbeat:Connect(heartbeat)
+start(script.Parent:WaitForChild("systems"):GetChildren())

demo/src/ServerScriptService/systems/health_regen.luau

@@ -1,15 +0,0 @@
-local ReplicatedStorage = game:GetService("ReplicatedStorage")
-local ct = require(ReplicatedStorage.components)
-local types = require(ReplicatedStorage.types)
-
-return function(world: types.World, dt: number)
-	for e in world:query(ct.Player):without(ct.Health) do
-		world:set(e, ct.Health, 100)
-	end
-
-	for e, health in world:query(ct.Health) do
-		if math.random() < 1 / 60 / 30 then
-			world:set(e, ct.Health, 100)
-		end
-	end
-end

demo/src/ServerScriptService/systems/life_is_painful.luau

@@ -1,19 +0,0 @@
-local ReplicatedStorage = game:GetService("ReplicatedStorage")
-local ct = require(ReplicatedStorage.components)
-local types = require(ReplicatedStorage.types)
-local jecs = require(ReplicatedStorage.ecs)
-
-return function(world: types.World, dt: number)
-	if math.random() < (1 / 60 / 7) then
-		for e in world:each(ct.Health) do
-			local poison = world:entity()
-			world:add(poison, ct.Debuff)
-			world:add(poison, jecs.pair(jecs.ChildOf, e))
-			world:set(poison, ct.Poison, 10)
-			world:set(poison, ct.Lifetime, {
-				duration = 3,
-				created = os.clock()
-			})
-		end
-	end
-end

demo/src/ServerScriptService/systems/lifetimes_expire.luau

@@ -1,12 +0,0 @@
-
-local ReplicatedStorage = game:GetService("ReplicatedStorage")
-local ct = require(ReplicatedStorage.components)
-local types = require(ReplicatedStorage.types)
-
-return function(world: types.World, dt: number)
-	for e, lifetime in world:query(ct.Lifetime) do
-		if os.clock() > lifetime.created + lifetime.duration then
-			world:add(e, ct.Destroy)
-		end
-	end
-end

demo/src/ServerScriptService/systems/mobs.luau

@@ -0,0 +1,78 @@
+--!optimize 2
+--!native
+--!strict
+
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local blink = require(game:GetService("ServerScriptService").net)
+local jecs = require(ReplicatedStorage.ecs)
+local __ = jecs.Wildcard
+
+local std = require(ReplicatedStorage.std)
+local ref = std.ref
+local interval = std.interval
+
+local world: std.World = std.world
+local cts = std.components
+
+local Mob = cts.Mob
+local Transform = cts.Transform
+local Velocity = cts.Velocity
+local Player = cts.Player
+local Character = cts.Character
+
+local function mobsMove(dt: number)
+    local targets = {}
+    for _, character in world:query(Character):with(Player):iter() do
+        table.insert(targets, (character.PrimaryPart :: Part).Position)
+    end
+
+    for mob, transform, v in world:query(Transform, Velocity):with(Mob):iter() do
+        local cf = transform.new
+        local p = cf.Position
+
+        local target
+        local closest
+
+        for _, pos in targets do
+            local distance = (p - pos).Magnitude
+            if not target or distance < closest then
+                target = pos
+                closest = distance
+            end
+        end
+
+        if not target then
+            continue
+        end
+
+        local moving = CFrame.new(p + (target - p).Unit * dt * v)
+        transform.new = moving
+        blink.UpdateTransform.FireAll(mob, moving)
+    end
+end
+
+local throttle = interval(5)
+
+local function spawnMobs()
+    if throttle() then
+        local p = Vector3.new(0, 5, 0)
+        local cf = CFrame.new(p)
+        local v = 5
+
+        local id = ref()
+            :set(Velocity, v)
+            :set(Transform, { new = cf })
+            :add(Mob)
+            .id()
+
+        blink.SpawnMob.FireAll(id, cf, v)
+    end
+end
+
+return function(scheduler: std.Scheduler)
+    local phases = scheduler.phases
+    local system_new = scheduler.systems.new
+    system_new(mobsMove, phases.Heartbeat)
+    system_new(spawnMobs, phases.Heartbeat)
+
+end

demo/src/ServerScriptService/systems/players.luau

@@ -0,0 +1,46 @@
+local Players = game:GetService("Players")
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local std = require(ReplicatedStorage.std)
+local ref = std.ref
+local collect = std.collect
+
+local cts = std.components
+local Player = cts.Player
+local Character = cts.Character
+
+local playersAdded = collect(Players.PlayerAdded)
+local playersRemoved = collect(Players.PlayerRemoving)
+local world: std.World = std.world
+
+local conn = {}
+
+local function players()
+    for _, player in playersAdded do
+        world:set(
+            std.world:entity(),
+            cts.Transform
+        )
+
+        local e = ref(player.UserId):set(Player, player)
+        local characterAdd = player.CharacterAdded
+        conn[e.id()] = characterAdd:Connect(function(rig)
+            while rig.Parent ~= workspace do
+                task.wait()
+            end
+            e:set(Character, rig)
+        end)
+    end
+
+    for _, player in playersRemoved do
+        local id = ref(player.UserId):clear().id()
+        conn[id]:Disconnect()
+        conn[id] = nil
+    end
+end
+
+return function(scheduler: std.Scheduler)
+    local phases = scheduler.phases
+    local system_new = scheduler.systems.new
+    system_new(players, phases.Heartbeat)
+end

demo/src/ServerScriptService/systems/players_added.luau

@@ -1,24 +0,0 @@
-local collect = require("../../ReplicatedStorage/collect")
-local types = require("../../ReplicatedStorage/types")
-local ct = require("../../ReplicatedStorage/components")
-local Players = game:GetService("Players")
-
-local player_added = collect(Players.PlayerAdded)
-return function(world: types.World, dt: number)
-	for player in player_added do
-		local entity = world:entity()
-		world:set(entity, ct.Player, player)
-	end
-
-	for entity, player in world:query(ct.Player):without(ct.Renderable) do
-		local character = player.Character
-		if not character then
-			continue
-		end
-		if not character.Parent then
-			continue
-		end
-
-		world:set(entity, ct.Renderable, character)
-	end
-end

demo/src/ServerScriptService/systems/poison_hurts.luau

@@ -1,18 +0,0 @@
-local ReplicatedStorage = game:GetService("ReplicatedStorage")
-local ct = require(ReplicatedStorage.components)
-local types = require(ReplicatedStorage.types)
-local jecs = require(ReplicatedStorage.ecs)
-
-return function(world: types.World, dt: number)
-	for e, poison_tick in world:query(ct.Poison, jecs.pair(jecs.ChildOf, jecs.w)) do
-		local tgt = world:target(e, jecs.ChildOf)
-		local health = world:get(tgt, ct.Health)
-		if not health then
-			continue
-		end
-
-		if math.random() < 1 / 60 / 1 and health > 1 then
-			world:set(tgt, ct.Health, health - 1)
-		end
-	end
-end

demo/src/ServerScriptService/systems/replication.luau

@@ -1,222 +0,0 @@
---!strict
-local Players = game:GetService("Players")
-local ReplicatedStorage = game:GetService("ReplicatedStorage")
-local ct = require(ReplicatedStorage.components)
-local components = ct :: { [string]: jecs.Entity }
-local remotes = require(ReplicatedStorage.remotes)
-local jecs = require(ReplicatedStorage.ecs)
-local collect = require(ReplicatedStorage.collect)
-local ty = require(ReplicatedStorage.types)
-
-return function(world: jecs.World)
-    local storages = {} :: { [jecs.Entity]: {[jecs.Entity]: any }}
-    local networked_components = {}
-    local networked_pairs = {}
-
-	for component in world:each(ct.Networked) do
-		local name = world:get(component, jecs.Name)
-		assert(name)
-		if components[name] == nil then
-			error("Invalid component:"..name)
-		end
-
-        storages[component] = {}
-
-        table.insert(networked_components, component)
-    end
-
-	for relation in world:each(ct.NetworkedPair) do
-		local name = world:get(relation, jecs.Name)
-		assert(name)
-		if not components[name] then
-			error("Invalid component")
-		end
-		table.insert(networked_pairs, relation)
-	end
-
-	for _, component in networked_components do
-		local name = world:get(component, jecs.Name)
-		if not name or not components[name] then
-			-- error("Invalid component")
-			error(`Networked Component (%id{component}%name{name})`)
-		end
-		local is_tag = jecs.is_tag(world, component)
-		local storage = storages[component]
-		if is_tag then
-			world:added(component, function(entity)
-				storage[entity] = true
-			end)
-		else
-			world:added(component, function(entity, _, value)
-				storage[entity] = value
-			end)
-			world:changed(component, function(entity, _, value)
-				storage[entity] = value
-			end)
-		end
-
-        world:removed(component, function(entity)
-            storage[entity] = "jecs.Remove"
-		end)
-	end
-
-	for _, relation in networked_pairs do
-		world:added(relation, function(entity: jecs.Entity, id: jecs.Id, value)
-			local is_tag = jecs.is_tag(world, id)
-			local storage = storages[id]
-			if not storage then
-				storage = {}
-				storages[id] = storage
-			end
-			if is_tag then
-				storage[entity] = true
-			else
-				storage[entity] = value
-			end
-		end)
-
-		world:changed(relation, function(entity: jecs.Id, id: jecs.Id, value)
-			local is_tag = jecs.is_tag(world, id)
-			if is_tag then
-				return
-			end
-
-			local storage = storages[id]
-			if not storage then
-				storage = {}
-				storages[id] = storage
-			end
-
-			storage[entity] = value
-		end)
-
-		world:removed(relation, function(entity, id)
-			local storage = storages[id]
-			if not storage then
-				storage = {}
-				storages[id] = storage
-			end
-
-			storage[entity] = "jecs.Remove"
-		end)
-	end
-
-    -- local requested_snapshots = collect(remotes.request_snapshot.OnServerEvent)
-    local players_added = collect(Players.PlayerAdded)
-
-    return function(_, dt: number)
-        local snapshot_lazy: ty.snapshot
-        local set_ids_lazy: { jecs.Entity }
-
-        -- In the future maybe it should be requested by the player instead when they
-        -- are ready to receive the replication. Otherwise streaming could be complicated
-        -- with intances references being nil.
-		for player in players_added do
-			if not snapshot_lazy then
-				snapshot_lazy, set_ids_lazy =  {}, {}
-
-				for component, storage in storages do
-					local set_values = {}
-					local set_n = 0
-
-					local q = world:query(component)
-					local is_tag = jecs.is_tag(world, component)
-					for _, archetype in q:archetypes() do
-						local entities = archetype.entities
-						local entities_len = #entities
-						table.move(entities, 1, entities_len, set_n + 1, set_ids_lazy)
-						if not is_tag then
-							local column = archetype.columns_map[component]
-							table.move(column, 1, entities_len, set_n + 1, set_values)
-						end
-
-						set_n += entities_len
-					end
-
-					local set = table.move(set_ids_lazy, 1, set_n, 1, {})
-
-					local map = {
-	                    set = if set_n > 0 then set else nil,
-	                    values = if set_n > 0 then set_values else nil,
-	                }
-
-					if jecs.IS_PAIR(component) then
-						map.relation = jecs.pair_first(world, component)
-						map.target = jecs.pair_second(world, component)
-						map.pair = true
-					end
-				   	snapshot_lazy[tostring(component)] = map
-				end
-			end
-
-			remotes.replication:FireClient(player, snapshot_lazy)
-		end
-
-		-- accumulator += dt
-
-		-- Purposely sending less diffs of the world because doing it at 60hz
-		-- gets expensive. But this requires interpolated elements in the scene.
-		-- if accumulator > 1/60 then
-		-- 	accumulator = 0
-
-		local snapshot = {} :: ty.snapshot
-
-		local set_ids = {}
-		local removed_ids = {}
-
-		for component, storage in storages do
-		    local set_values = {} :: { any }
-		    local set_n = 0
-		    local removed_n = 0
-		    for e, v in storage do
-		        if v ~= "jecs.Remove" then
-		            set_n += 1
-		            set_ids[set_n] = e
-		            set_values[set_n] = v or true
-		        elseif world:contains(e) then
-		            removed_n += 1
-		            removed_ids[removed_n] = e
-		        end
-		    end
-
-		    table.clear(storage)
-
-            local dirty = false
-
-            if set_n > 0 or removed_n > 0 then
-            	dirty = true
-            end
-
-            if dirty then
-            	local removed = table.move(removed_ids, 1, removed_n, 1, {}) :: { jecs.Entity }
-             	local set = table.move(set_ids, 1, set_n, 1, {}) :: { jecs.Entity }
-
-              	-- local ser_id: string = nil :: any
-
-				-- if jecs.IS_PAIR(component) then
-				-- 	ser_id = `{jecs.pair_first(world, component)},{jecs.pair_second(world, component)}`
-				-- else
-				-- 	ser_id = tostring(component)
-				-- end
-
-				local map = {
-                    set = if set_n > 0 then set else nil,
-                    values = if set_n > 0 then set_values else nil,
-                    removed = if removed_n > 0 then removed else nil,
-                }
-
-				if jecs.IS_PAIR(component) then
-					map.relation = jecs.pair_first(world, component)
-					map.target = jecs.pair_second(world, component)
-					map.pair = true
-				end
-
-				snapshot[tostring(component)] = map
-	        end
-        end
-        if next(snapshot) ~= nil then
-        	remotes.replication:FireAllClients(snapshot)
-			-- print(snapshot)
-        end
-    end
-end

demo/src/StarterPlayer/StarterPlayerScripts/main.client.luau

@@ -0,0 +1,4 @@
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local start = require(ReplicatedStorage.start)
+
+start(script.Parent:WaitForChild("systems"):GetChildren())

demo/src/StarterPlayer/StarterPlayerScripts/systems/move.luau

@@ -0,0 +1,39 @@
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local blink = require(ReplicatedStorage.net)
+local std = require(ReplicatedStorage.std)
+local world = std.world
+local ref = std.ref
+
+local cts = std.components
+
+local Model = cts.Model
+local Transform = cts.Transform
+
+local function move(dt: number)
+    for _, transform, model in world:query(Transform, Model):iter() do
+        local cf = transform.new
+        if cf ~= transform.old then
+            local origo = model.PrimaryPart.CFrame
+            model.PrimaryPart.CFrame = origo:Lerp(cf, 1)
+            transform.old = cf
+        end
+    end
+end
+
+local function syncTransforms()
+    for _, id, cf in blink.UpdateTransform.Iter() do
+        local e = ref("server-"..id)
+        local transform = e:get(cts.Transform)
+        if not transform then
+            continue
+        end
+        transform.new = cf
+    end
+end
+
+return function(scheduler: std.Scheduler)
+    local phases = scheduler.phases
+    local system_new = scheduler.systems.new
+    system_new(move, phases.Heartbeat)
+    system_new(syncTransforms, phases.RenderStepped)
+end

demo/src/StarterPlayer/StarterPlayerScripts/systems/syncMobs.luau

@@ -0,0 +1,31 @@
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local blink = require(ReplicatedStorage.net)
+local std = require(ReplicatedStorage.std)
+local ref = std.ref
+local world = std.world
+local cts = std.components
+
+local function syncMobs()
+    for _, id, cf, vel in blink.SpawnMob.Iter() do
+        local part = Instance.new("Part")
+        part.Size = Vector3.one * 5
+        part.BrickColor = BrickColor.Red()
+        part.Anchored = true
+        local model = Instance.new("Model")
+        model.PrimaryPart = part
+        part.Parent = model
+        model.Parent = workspace
+
+        ref("server-"..id)
+            :set(cts.Transform, { new = cf, old = cf })
+            :set(cts.Velocity, vel)
+            :set(cts.Model, model)
+            :add(cts.Mob)
+    end
+end
+
+return function(scheduler: std.Scheduler)
+    local phases = scheduler.phases
+    local system_new = scheduler.systems.new
+    system_new(syncMobs, phases.RenderStepped)
+end

demo/wally.toml

@@ -5,4 +5,4 @@ registry = "https://github.com/UpliftGames/wally-index"
 realm = "shared"
 
 [dependencies]
-jabby = "alicesaidhi/jabby@0.2.2"
+jabby = "alicesaidhi/jabby@0.1.0"

docs/.vitepress/config.mts

@@ -1,4 +1,4 @@
-import { defineConfig } from "vitepress";
+import { defineConfig } from 'vitepress'
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
@@ -8,43 +8,62 @@ export default defineConfig({
     themeConfig: {
         // https://vitepress.dev/reference/default-theme-config
         nav: [
-			{ text: "Learn", link: "/learn/overview.md" },
-			{ text: "API", link: "/api/jecs.md" },
-			{ text: "Resources", link: "/resources" },
+            { text: 'Learn', link: '/' },
+            { text: 'API', link: '/api/jecs.md' },
+            { text: 'Examples', link: 'https://github.com/Ukendio/jecs/tree/main/examples' },
         ],
 
         sidebar: {
             "/api/": [
                 {
-					text: "Namespaces",
+                    text: "API reference",
                     items: [
                         { text: "jecs", link: "/api/jecs" },
                         { text: "World", link: "/api/world" },
-						{ text: "Query", link: "/api/query" },
-					],
-				},
+                        { text: "Query", link: "/api/query" }
+                    ]
+                }
             ],
             "/learn/": [
                 {
-					text: "API Reference",
+                    text: "Introduction",
                     items: [
-						{ text: "jecs", link: "/api/jecs" },
-						{ text: "World", link: "/api/world" },
-						{ text: "Query", link: "/api/query" },
-					],
+                        { text: 'Getting Started', link: '/learn/overview/get-started' },
+                        { text: 'First Jecs Project', link: '/learn/overview/first-jecs-project' }
+                    ]
                 },
                 {
-					text: "Contributing",
+                    text: 'Concepts',
                     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: "Code Coverage", link: "/learn/contributing/coverage" },
-					],
+                        { text: 'Entities and Components', link: '/learn/concepts/entities-and-components' },
+                        { text: 'Queries', link: '/learn/concepts/queries' },
+                        { text: 'Relationships', link: '/learn/concepts/relationships' },
+                        { text: 'Component Traits', link: 'learn/concepts/component-traits' },
+                        { text: 'Addons', link: '/learn/concepts/addons' }
+                    ]
                 },
-			],
+                {
+                    text: "FAQ",
+                    items: [
+                        { text: 'How can I contribute?', link: '/learn/faq/contributing' }
+                    ]
                 },
 
-		socialLinks: [{ icon: "github", link: "https://github.com/ukendio/jecs" }],
+            ],
+            "/contributing/": [
+                {
+                    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' },
+                    ]
+                }
+            ]
         },
-});
+
+        socialLinks: [
+            { icon: 'github', link: 'https://github.com/ukendio/jecs' }
+        ]
+    }
+})

docs/api/jecs.md

@@ -2,7 +2,7 @@
 
 Jecs. Just an Entity Component System.
 
-# Members
+# Properties
 
 ## World
 ```luau
@@ -12,93 +12,27 @@ A world is a container of all ECS data. Games can have multiple worlds but compo
 
 ## Wildcard
 ```luau
-jecs.Wildcard: Id
+jecs.Wildcard: Entity
 ```
 Builtin component type. This ID is used for wildcard queries.
 
 ## Component
 ```luau
-jecs.Component: Id
+jecs.Component: Entity
 ```
 Builtin component type. Every ID created with [world:component()](world.md#component()) has this type added to it. This is meant for querying every component ID.
 
 ## ChildOf
 ```luau
-jecs.ChildOf: Id
+jecs.ChildOf: Entity
 ```
 Builtin component type. This ID is for creating parent-child hierarchies.
 
-## OnAdd
-
-```luau
-jecs.OnAdd: Id
-```
-Builtin component type. This ID is for setting up a callback that is invoked when an instance of a component is added.
-
-## OnRemove
-
-```luau
-jecs.OnRemove: Id
-```
-
-Builtin component type. This ID is for setting up a callback that is invoked when an instance of a component is removed.
-
-## OnChange
-
-```luau
-jecs.OnChange: Id
-```
-
-Builtin component type. This ID is for setting up a callback that is invoked when an instance of a component is changed.
-
-## Exclusive
-
-```lua
-jecs.Exclusive: Id
-```
-
-Builtin component type. This ID is for encoding that an ID is Exclusive meaning that an entity can never have more than one target for that exclusive relation.
-
-:::code-group
-```luau [luau]
-local ChildOf = world:entity()
-world:add(ChildOf, jecs.Exclusive)
-
-local pop = world:entity()
-local dad = world:entity()
-local kid = world:entity()
-
-world:add(kid, pair(ChildOf, dad))
-print(world:target(kid, ChildOf, 0) == dad)
-world:add(kid, pair(ChildOf, pop))
-print(world:target(kid, ChildOf, 1) == dad) -- If ChildOf was not exclusive this would have been true
-print(world:target(kid, ChildOf, 0) == pop)
-
--- Output:
---  true
---  false
---  true
-```
-
-:::info
-By default, jecs.ChildOf is already an exclusive relationship and this is just a demonstration of how to use it.
-In some cases you can use Exclusive relationships as a performance optimization as you can guarantee there will only be one target, therefore
-retrieving the data from a wildcard pair with that exclusive relationship can be deterministic.
-:::
-
-## Name
-```luau
-jecs.Name: Id
-```
-Builtin component type. This ID is for naming components, but realistically you could use any component to do that.
-
 ## Rest
 ```luau
-jecs.Rest: Id
+jecs.Rest: Entity
 ```
 
-Builtin component type. This ID is simply for denoting the end of the range for builtin component IDs.
-
 # Functions
 
 ## pair()
@@ -106,38 +40,11 @@ Builtin component type. This ID is simply for denoting the end of the range for
 function jecs.pair(
     first: Entity, -- The first element of the pair, referred to as the relationship of the relationship pair.
     object: Entity, -- The second element of the pair, referred to as the target of the relationship pair.
-): number -- Returns the ID with those two elements
+): number -- Returns the Id with those two elements
 
 ```
 ::: info
 
-While relationship pairs can be used as components and have data associated with an ID, they cannot be used as entities. Meaning you cannot add components to a pair as the source of a binding.
+Note that while relationship pairs can be used as components, meaning you can add data with it as an ID, however they cannot be used as entities. Meaning you cannot add components to a pair as the source of a binding.
 
 :::
-
-## pair_first()
-```luau
-function jecs.pair_first(
-   	pair: Id, -- A full pair ID encoded using a relation-target pair.
-): Entity -- The ID of the first element. Returns 0 if the ID is not alive.
-```
-Returns the first element (the relation part) of a pair ID.
-
-**Example:**
-```luau
-local Likes = world:component()
-local alice = world:entity()
-local bob = world:entity()
-
-local pair_id = pair(Likes, alice)
-local relation = jecs.pair_first(pair_id)
-print(relation == Likes) -- true
-```
-
-## pair_second()
-```luau
-function jecs.pair_second(
-   	pair: Id, -- A full pair ID encoded using a relation-target pair.
-): Entity -- The ID of the second element. Returns 0 if the ID is not alive.
-```
-Returns the second element (the target part) of a pair ID.

docs/api/observers.md

@@ -1,196 +0,0 @@
-# Observers
-
-The observers addon extends the World with signal-based reactivity and query-based observers. This addon provides a more ergonomic way to handle component lifecycle events and query changes.
-
-## Installation
-
-The observers addon is included with jecs and can be imported directly:
-
-```luau
-local jecs = require(path/to/jecs)
-local observers_add = require(path/to/jecs/addons/observers)
-
-local world = observers_add(jecs.world())
-```
-
-## Methods
-
-### added
-
-Registers a callback that is invoked when a component is added to any entity.
-
-```luau
-function World:added<T>(
-    component: Id<T>,
-    callback: (entity: Entity, id: Id<T>, value: T?) -> ()
-): () -> () -- Returns an unsubscribe function
-```
-
-**Parameters:**
-- `component` - The component ID to listen for additions
-- `callback` - Function called when component is added, receives entity, component ID, and value
-
-**Returns:** An unsubscribe function that removes the listener when called
-
-**Example:**
-```luau
-local Health = world:component() :: jecs.Entity<number>
-
-local unsubscribe = world:added(Health, function(entity, id, value)
-    print("Health component added to entity", entity, "with value", value)
-end)
-
--- Later, to stop listening:
-unsubscribe()
-```
-
-### removed
-
-Registers a callback that is invoked when a component is removed from any entity.
-
-```luau
-function World:removed<T>(
-    component: Id<T>,
-    callback: (entity: Entity, id: Id<T>) -> ()
-): () -> () -- Returns an unsubscribe function
-```
-
-**Parameters:**
-- `component` - The component ID to listen for removals
-- `callback` - Function called when component is removed, receives entity and component ID
-
-**Returns:** An unsubscribe function that removes the listener when called
-
-**Example:**
-```luau
-local Health = world:component() :: jecs.Entity<number>
-
-local unsubscribe = world:removed(Health, function(entity, id)
-    print("Health component removed from entity", entity)
-end)
-```
-
-### changed
-
-Registers a callback that is invoked when a component's value is changed on any entity.
-
-```luau
-function World:changed<T>(
-    component: Id<T>,
-    callback: (entity: Entity, id: Id<T>, value: T) -> ()
-): () -> () -- Returns an unsubscribe function
-```
-
-**Parameters:**
-- `component` - The component ID to listen for changes
-- `callback` - Function called when component value changes, receives entity, component ID, and new value
-
-**Returns:** An unsubscribe function that removes the listener when called
-
-**Example:**
-```luau
-local Health = world:component() :: jecs.Entity<number>
-
-local unsubscribe = world:changed(Health, function(entity, id, value)
-    print("Health changed to", value, "for entity", entity)
-end)
-```
-
-### observer
-
-Creates a query-based observer that triggers when entities match or stop matching a query.
-
-```luau
-function World:observer<T...>(
-    query: Query<T...>,
-    callback: ((entity: Entity, id: Id, value: any?) -> ())?
-): () -> () -> Entity -- Returns an iterator function
-```
-
-**Parameters:**
-- `query` - The query to observe for changes
-- `callback` - Optional function called when entities match the query
-
-**Returns:** An iterator function that returns entities that matched the query since last iteration
-
-**Example:**
-```luau
-local Position = world:component() :: jecs.Id<Vector3>
-local Velocity = world:component() :: jecs.Id<Vector3>
-
-local moving_entities = world:observer(
-    world:query(Position, Velocity),
-    function(entity, id, value)
-        print("Entity", entity, "started moving")
-    end
-)
-
--- In your game loop:
-for entity in moving_entities() do
-    -- Process newly moving entities
-end
-```
-
-### monitor
-
-Creates a query-based monitor that triggers when entities are added to or removed from a query.
-
-```luau
-function World:monitor<T...>(
-    query: Query<T...>,
-    callback: ((entity: Entity, id: Id, value: any?) -> ())?
-): () -> () -> Entity -- Returns an iterator function
-```
-
-**Parameters:**
-- `query` - The query to monitor for additions/removals
-- `callback` - Optional function called when entities are added or removed from the query
-
-**Returns:** An iterator function that returns entities that were added or removed since last iteration
-
-**Example:**
-```luau
-local Health = world:component() :: jecs.Id<number>
-
-local health_changes = world:monitor(
-    world:query(Health),
-    function(entity, id, value)
-        print("Health component changed for entity", entity)
-    end
-)
-
--- In your game loop:
-for entity in health_changes() do
-    -- Process entities with health changes
-end
-```
-
-## Usage Patterns
-
-### Component Lifecycle Tracking
-
-```luau
-local Player = world:component()
-local Health = world:component() :: jecs.Id<number>
-
--- Track when players are created
-world:added(Player, function(entity, id, instance)
-	instance:SetAttribute("entityid", entity)
-end)
-
-world:removed(Player, function(entity, id)
-	world:add(entity, Destroy) -- process its deletion later!
-end)
-```
-
-## Performance Considerations
-
-- **Signal listeners** are called immediately when components are added/removed/changed
-- **Query observers** cache the query for better performance
-- **Multiple listeners** for the same component are supported and called in registration order
-- **Unsubscribe functions** should be called when listeners are no longer needed to prevent memory leaks
-- **Observer iterators** should be called regularly to clear the internal buffer
-
-## Integration with Built-in Hooks
-
-The observers addon integrates with the built-in component hooks (`OnAdd`, `OnRemove`, `OnChange`). If a component already has these hooks configured, the observers addon will preserve them and call both the original hook and any registered signal listeners.

docs/api/query.md

@@ -2,50 +2,27 @@
 
 A World contains entities which have components. The World is queryable and can be used to get entities with a specific set of components.
 
-# Methods
-
-## cached
-
-Returns a cached version of the query. This is useful if you want to create a query that you can iterate multiple times.
+# Functions
 
+## drain()
 ```luau
-function Query:cached(): Query -- Returns the cached Query
+function query:drain(): Query
 ```
-Example:
-
-::: code-group
-
-```luau [luau]
-local lerps = world:query(Lerp):cached() -- Ensure that you cache this outside a system so you do not create a new cache for a query every frame
-
-local function system(dt)
-	for entity, lerp in lerps do
-		-- Do something
-	end
-end
-```
-
-```ts [typescript]
-const lerps = world.query(Lerp).cached()
-
-function system(dt) {
-	for (const [entity, lerp] of lerps) {
-		// Do something
-	}
-}
-```
-
-:::
-
-## with
-
-Adds components (IDs) to query with, but will not use their data. This is useful for Tags or generally just data you do not care for.
+This function will impede it from being reset when the query is being iterated.
 
+## next()
 ```luau
-function Query:with(
+function query:next(): Query
+```
+Get the next result in the query. Drain must have been called beforehand or otherwise it will error.
+
+## with()
+```luau
+function query:with(
     ...: Entity -- The IDs to query with
 ): Query
 ```
+Adds IDs to query with, but will not use their data. This is useful for Tags or generally just data you do not care for.
 
 Example:
 ::: code-group
@@ -68,83 +45,87 @@ for (const [id, position] of world.query(Position).with(Velocity)) {
 Put the IDs inside of `world:query()` instead if you need the data.
 :::
 
-## without
-
-Removes entities with the provided components from the query.
+## without()
 
 ```luau
-function Query:without(
+function query:without(
     ...: Entity -- The IDs to filter against.
 ): Query -- Returns the Query
 ```
+Removes entities with the provided IDs from the query.
 
 Example:
-
 ::: code-group
 
 ```luau [luau]
-for entity, position in world:query(Position):without(Velocity) do
+for _ in world:query(Position):without(Velocity) do
     -- Do something
 end
 ```
 
 ```ts [typescript]
-for (const [entity, position] of world.query(Position).without(Velocity)) {
+for (const _ of world.query(Position).without(Velocity)) {
     // Do something
 }
 ```
 
 :::
 
-## archetypes
-
-Returns the matching archetypes of the query.
+## replace()
 
 ```luau
-function Query:archetypes(): { Archetype }
+function query:replace(
+    fn: (entity: Entity, ...: T...) -> U... -- ): () -- The callback that will transform the entities' data
 ```
+This function takes a callback which is given the current queried data of each matching entity. The values returned by the callback will be set as the new data for each given ID on the entity.
 
 Example:
+::: code-group
 
 ```luau [luau]
-for i, archetype in world:query(Position, Velocity):archetypes() do
-    local field = archetype.columns_map
-    local positions = field[Position]
-    local velocities = field[Velocity]
+world:query(Position, Velocity):replace(function(e, position, velocity)
+    return position + velocity, velocity * 0.9
+end
+```
+
+```ts [typescript]
+world
+    .query(Position, Velocity)
+    .replace((e, position, velocity) =>
+        $tuple(position.add(velocity), velocity.mul(0.9)),
+    );
+```
+
+:::
+
+
+## archetypes()
+```luau
+function query.archetypes(): { Archetype }
+```
+Returns the matching archetypes of the query.
+
+Example:
+::: code-group
+
+```luau [luau]
+for i, archetype in world:query(Position, Velocity).archetypes() do
+    local columns = archetype.columns
+    local field = archetype.records
+
+    local P = field[Position]
+    local V = field[Velocity]
 
     for row, entity in archetype.entities do
-        local position = positions[row]
-        local velocity = velocities[row]
+        local position = columns[P][row]
+        local velocity = columns[V][row]
         -- Do something
     end
 end
 ```
 
-:::info
-This function is meant for people who want to really customize their query behaviour at the archetype-level
 :::
 
-## iter
-In most cases, you can iterate over queries directly using `for entity, ... in query do`. The `:iter()` method is mainly useful if you are on the old solver, to get types for the returned values.
-
-```luau
-function Query:iter(): () -> (Entity, ...)
-```
-
-Example:
-
-::: code-group
-```luau [luau]
-local query = world:query(Position, Velocity)
-
--- Direct iteration (recommended)
-for entity, position, velocity in query do
-    -- Process entity
-end
-
--- Using explicit iterator (when needed for the old solver)
-local iterator = query:iter()
-for entity, position, velocity in iterator do
-    -- Process entity
-end
-```
+:::info
+This function is meant for internal usage. Use this if you want to maximize performance by inlining the iterator.
+:::

docs/api/world.md

@@ -1,277 +1,138 @@
 # World
 
-A World contains entities which have components. The World is queryable and can be used to get entities with a specific set of components and to perform different kinds of operations on them.
+A World contains entities which have components. The World is queryable and can be used to get entities with a specific set of components.
 
 # Functions
 
-## new
-
-`World` utilizes a class, meaning jecs allows you to create multiple worlds.
-
+## new()
 ```luau
 function World.new(): World
 ```
+Creates a new world.
 
 Example:
-
 ::: code-group
 
 ```luau [luau]
 local world = jecs.World.new()
-local myOtherWorld = jecs.World.new()
 ```
 
 ```ts [typescript]
 import { World } from "@rbxts/jecs";
 
 const world = new World();
-const myOtherWorld = new World();
 ```
 
 :::
 
-# Methods
-
-## entity
-
-Creates a new entity. It accepts the overload to create an entity with a specific ID.
-
+## entity()
 ```luau
-function World:entity<T>(
-	id: Entity<T>? -- The desired id
-): Entity<T>
+function World:entity(): Entity -- The new entit.
 ```
+Creates a new entity.
 
 Example:
-
 ::: code-group
+
 ```luau [luau]
 local entity = world:entity()
 ```
+
 ```ts [typescript]
 const entity = world.entity();
 ```
-:::
-
-## component
-
-Creates a new component. Do note components are entities as well, meaning jecs allows you to add other components onto them.
-
-These are meant to be added onto other entities through `add` and `set`
-
-```luau
-function World:component<T>(): Entity<T> -- The new component.
-```
-
-Example:
-
-::: code-group
-
-```luau [luau]
-local Health = world:component() :: jecs.Entity<number> -- Typecasting this will allow us to know what kind of data the component holds!
-```
-
-```ts [typescript]
-const Health = world.component<number>();
-```
 
 :::
 
-## get
-
-Returns the data present in the component that was set in the entity. Will return nil if the component was a tag or is not present.
-
+## component()
 ```luau
-function World:get<T>(
-    entity: Entity, -- The entity
-    id: Entity<T> -- The component ID to fetch
-): T?
+function World:component<T>(): Entity<T> -- The new componen.
 ```
+Creates a new component.
 
 Example:
-
 ::: code-group
 
 ```luau [luau]
 local Health = world:component() :: jecs.Entity<number>
-
-local Entity = world:entity()
-world:set(Entity, Health, 100)
-
-print(world:get(Entity, Health))
-
--- Outputs:
--- 100
 ```
 
 ```ts [typescript]
 const Health = world.component<number>();
-
-const Entity = world.entity();
-world.set(Entity, Health, 100);
-
-print(world.get(Entity, Health));
-
-// Outputs:
-// 100
 ```
-
 :::
 
-## has
+::: info
+You should use this when creating components.
 
-Returns whether an entity has a component (ID). Useful for checking if an entity has a tag or if you don't care of the data that is inside the component.
+For example, a Health type should be created using this.
+:::
 
+## get()
+```luau
+function World:get<T>(
+    entity: Entity, -- The entity
+    id: Entity<T> -- The component ID to fetch
+): T
+```
+Returns the data for the component data the corresponding entity, nil if entity does not have the ID or was a tag.
+
+## has()
 ```luau
 function World:has(
     entity: Entity, -- The entity
     id: Entity<T> -- The component ID to check
 ): boolean
 ```
-
-Example:
-
-::: code-group
-
-```luau [luau]
-local IsMoving = world:component()
-local Ragdolled = world:entity() -- This is a tag, meaning it won't contain data
-local Health = world:component() :: jecs.Entity<number>
-
-local Entity = world:entity()
-world:set(Entity, Health, 100)
-world:add(Entity, Ragdolled)
-
-print(world:has(Entity, Health))
-print(world:has(Entity, IsMoving)
-
-print(world:get(Entity, Ragdolled))
-print(world:has(Entity, Ragdolled))
-
--- Outputs:
--- true
--- false
--- nil
--- true
-```
-
-```ts [typescript]
-const IsMoving = world.component();
-const Ragdolled = world.entity(); // This is a tag, meaning it won't contain data
-const Health = world.component<number>();
-
-const Entity = world.entity();
-world.set(Entity, Health, 100);
-world.add(Entity, Ragdolled);
-
-print(world.has(Entity, Health));
-print(world.has(Entity, IsMoving));
-
-print(world.get(Entity, Ragdolled));
-print(world.has(Entity, Ragdolled));
-
-// Outputs:
-// true
-// false
-// nil
-// true
-```
+Returns whether the entity has the ID.
 
 :::
 
-## add
-
-Adds a component (ID) to the entity. Useful for adding a tag to an entity, as this adds the component to the entity without any additional values inside
-
+## add()
 ```luau
 function World:add(
     entity: Entity, -- The entity
     id: Entity<T> -- The component ID to add
-): void
+): ()
 ```
+Adds a component ID to the entity.
+
+This operation adds a single (component) id to an entity.
 
 ::: info
 This function is idempotent, meaning if the entity already has the id, this operation will have no side effects.
 :::
 
-## set
-
-Adds or changes data in the entity's component.
 
+## set()
 ```luau
 function World:set(
     entity: Entity, -- The entity
     id: Entity<T>, -- The component ID to set
     data: T -- The data of the component's type
-): void
+): ()
 ```
+Adds or changes the entity's component.
 
-Example:
-
-::: code-group
-
-```luau [luau]
-local Health = world:component() :: jecs.Entity<number>
-
-local Entity = world:entity()
-world:set(Entity, Health, 100)
-
-print(world:get(Entity, Health))
-
-world:set(Entity, Health, 50)
-print(world:get(Entity, Health))
-
--- Outputs:
--- 100
--- 50
-```
-
-```ts [typescript]
-const Health = world.component<number>();
-
-const Entity = world.entity();
-world.set(Entity, Health, 100);
-
-print(world.get(Entity, Health));
-
-world.set(Entity, Health, 50);
-print(world.get(Entity, Health));
-
-// Outputs:
-// 100
-// 50
-```
-:::
-
-:::info
-`world:set(entity, component, value)` propagates that a change has happened for thes component on this entity, while mutating a value directly would not.
-:::
-
-## query
-
-Creates a [`query`](query) with the given components (IDs). Entities that satisfies the conditions of the query will be returned and their corresponding data.
-
+## query()
 ```luau
 function World:query(
-    ...: Entity -- The components to query with
+    ...: Entity -- The IDs to query with
 ): Query
 ```
+Creates a [`query`](query) with the given IDs. Entities that satisfies the conditions of the query will be returned and their corresponding data.
 
 Example:
-
 ::: code-group
 
 ```luau [luau]
--- Entity could also be a component if a component also meets the requirements, since they are also entities which you can add more components onto
-for entity, position, velocity in world:query(Position, Velocity) do
-
+for id, position, velocity in world:query(Position, Velocity) do
+	-- Do something
 end
 ```
 
 ```ts [typescript]
-// Roblox-TS allows to deconstruct tuples on the act like if they were arrays!
-// Entity could also be a component if a component also meets the requirements, since they are also entities which you can add more components onto
-for (const [entity, position, velocity] of world.query(Position, Velocity) {
+for (const [id, position, velocity] of world.query(Position, Velocity) {
     // Do something
 }
 ```
@@ -282,362 +143,33 @@ for (const [entity, position, velocity] of world.query(Position, Velocity) {
 Queries are uncached by default, this is generally very cheap unless you have high fragmentation from e.g. relationships.
 
 :::
-
-## target
-
-Get the target of a relationship.
-This will return a target (second element of a pair) of the entity for the specified relationship. The index allows for iterating through the targets, if a single entity has multiple targets for the same relationship.
-If the index is larger than the total number of instances the entity has for the relationship or if there is no pair with the specified relationship on the entity, the operation will return nil.
-
+## target()
 ```luau
 function World:target(
     entity: Entity, -- The entity
-    relation: Id, -- The relationship between the entity and the target
+    relation: Entity, -- The relationship between the entity and the target
     nth: number, -- The index
-): Id? -- The target for the relationship at the specified index.
-```
-Example:
+): Entity? -- The target for the relationship at the specified index.
 
-::: code-group
-
-```luau [luau]
-local function timers_count(world: types.World)
-	local timers = world
-		:query(jecs.pair(ct.Timer, jecs.w))
-		:without(ct.Destroy)
-		:cached()
-
-	return function(_, dt: number)
-		for entity in timers do
-			local index = 0
-			local nth = world:target(entity, ct.Timer, index)
-			while nth do
-				local timer = world:get(entity, jecs.pair(ct.Timer, nth))
-				local elapsed = timer.elapsed + dt
-				if elapsed >= timer.duration then
-					world:add(entity, ct.Destroy)
-				end
-				timer.elapsed = elapsed
-			end
-		end
-	end
-end
 ```
 
-```ts [typescript]
-const entity = world.entity();
-print(world.contains(entity));
-print(world.contains(1));
-print(world.contains(2));
+Get the target of a relationship.
 
-// Outputs:
-// true
-// true
-// false
-```
+This will return a target (second element of a pair) of the entity for the specified relationship. The index allows for iterating through the targets, if a single entity has multiple targets for the same relationship.
 
-:::
-
-
-## parent
-
-Get parent (target of ChildOf relationship) for entity. If there is no ChildOf relationship pair, it will return nil.
+If the index is larger than the total number of instances the entity has for the relationship or if there is no pair with the specified relationship on the entity, the operation will return nil.
 
+## parent()
 ```luau
 function World:parent(
     child: Entity -- The child ID to find the parent of
 ): Entity? -- Returns the parent of the child
 ```
 
+Get parent (target of ChildOf relationship) for entity. If there is no ChildOf relationship pair, it will return nil.
+
 This operation is the same as calling:
 
 ```luau
 world:target(entity, jecs.ChildOf, 0)
 ```
-
-:::
-
-
-## remove
-
-Removes a component (ID) from an entity
-
-```luau
-function World:remove<T>(
-    entity: Entity,
-	component: Id<T>
-): void
-```
-
-Example:
-
-::: code-group
-
-```luau [luau]
-local IsMoving = world:component()
-
-local entity = world:entity()
-world:add(entity, IsMoving)
-
-print(world:has(entity, IsMoving))
-
-world:remove(entity, IsMoving)
-print(world:has(entity, IsMoving))
-
--- Outputs:
--- true
--- false
-```
-
-```ts [typescript]
-const IsMoving = world.component();
-
-const entity = world.entity();
-world.add(entity, IsMoving);
-
-print(world.has(entity, IsMoving));
-
-world.remove(entity, IsMoving);
-print(world.has(entity, IsMoving));
-
-// Outputs:
-// true
-// false
-```
-
-:::
-
-## delete
-
-Deletes an entity and all of its related components and relationships.
-
-```luau
-function World:delete(
-    entity: Entity
-): void
-```
-
-Example:
-
-::: code-group
-
-```luau [luau]
-local entity = world:entity()
-print(world:contains(entity))
-
-world:delete(entity)
-
-print(world:contains(entity))
-
--- Outputs:
--- true
--- false
-```
-
-```ts [typescript]
-const entity = world.entity();
-print(world.has(entity));
-
-world.delete(entity);
-
-print(world.has(entity));
-
-// Outputs:
-// true
-// false
-```
-
-:::
-
-## clear
-
-Clears all of the components and relationships of the entity without deleting it.
-
-```luau
-function World:clear(
-    entity: Entity
-): void
-```
-
-## each
-
-Iterate over all entities with the specified component.
-Useful when you only need the entity for a specific ID and you want to avoid creating a query.
-
-```luau
-function World:each(
-	component: Id -- The component ID
-): () -> Entity
-```
-
-Example:
-::: code-group
-```luau [luau]
-local id = world:component()
-for entity in world:each(id) do
-	-- Do something
-end
-```
-```ts [typescript]
-const id = world.component();
-for (const entity of world.each(id)) {
-	// Do something
-}
-```
-:::
-
-## children
-
-Iterate entities in root of parent
-
-```luau
-function World:children(
-	parent: Entity -- The parent entity
-): () -> Entity
-```
-
-This is the same as calling:
-
-```luau
-world:each(pair(ChildOf, parent))
-```
-
-## range
-
-Enforces a check for entities to be created within a desired range.
-```luau
-function World:range(
-	range_begin: number -- The starting point,
-	range_end: number? -- The end point (optional)
-)
-```
-
-Example:
-
-::: code-group
-```luau [luau]
-world:range(1000, 5000) -- Entities will be created with IDs 1000-5000
-
-local entity = world:entity()
-print(entity) -- Will be >= 1000 and < 5000
-```
-```ts [typescript]
-world.range(1000, 5000) // Entities will be created with IDs 1000-5000
-
-const entity = world.entity()
-print(entity) // Will be >= 1000 and < 5000
-```
-:::
-
-## parent
-
-Gets the parent entity of the specified entity using the built-in `ChildOf` relationship.
-
-```luau
-function World:parent(
-    entity: Entity
-): Entity? -- Returns the parent entity or nil if no parent
-```
-
-Example:
-
-::: code-group
-```luau [luau]
-local parent = world:entity()
-local child = world:entity()
-
-world:add(child, pair(jecs.ChildOf, parent))
-
-local retrieved_parent = world:parent(child)
-print(retrieved_parent == parent) -- true
-```
-```ts [typescript]
-const parent = world.entity()
-const child = world.entity()
-
-world.add(child, pair(jecs.ChildOf, parent))
-
-const retrievedParent = world.parent(child)
-print(retrievedParent === parent) // true
-```
-:::
-
-## contains
-
-Checks if an entity or component (id) exists and is alive in the world.
-
-```luau
-function World:contains(
-    entity: Entity
-): boolean
-```
-
-Example:
-
-::: code-group
-```luau [luau]
-local entity = world:entity()
-print(world:contains(entity)) -- true
-
-world:delete(entity)
-print(world:contains(entity)) -- false
-```
-```ts [typescript]
-const entity = world.entity()
-print(world.contains(entity)) // true
-
-world.delete(entity)
-print(world.contains(entity)) // false
-```
-:::
-
-## exists
-
-Checks if the entity ID exists regardless of whether it is alive or not. Useful to know if the ID is occupied in the entity index.
-
-```luau
-function World:exists(
-    entity: Entity
-): boolean
-```
-
-## cleanup
-
-Cleans up empty archetypes.
-
-```luau
-function World:cleanup(): void
-```
-
-:::info
-It is recommended to profile the optimal interval you should cleanup because it varies completely from game to game.
-
-Here are a couple of reasons from Sander Mertens:
-	- some applications are memory constrained, so any wasted memory on empty
-	  archetypes has to get cleaned up
-	- many archetypes can get created during game startup but aren't used later
-	  on, so it would be wasteful to keep them around
-	- empty archetypes can slow queries down, especially if there are many more
-	  empty ones than non-empty ones
-	- if the total number of component permutations (/relationships) is too
-	  high, you have no choice but to periodically cleanup empty archetypes
-:::
-
-Example:
-
-::: code-group
-```luau [luau]
-local entity = world:entity()
-world:delete(entity)
-
--- Cleanup is usually automatic, but can be called manually
-world:cleanup()
-```
-```ts [typescript]
-const entity = world.entity()
-world.delete(entity)
-
-// Cleanup is usually automatic, but can be called manually
-world.cleanup()
-```
-:::

docs/contributing/guidelines.md

@@ -0,0 +1,3 @@
+## TODO
+
+This is a TODO stub.

docs/contributing/issues.md

@@ -0,0 +1,3 @@
+## TODO
+
+This is a TODO stub.

docs/contributing/pull-requests.md

@@ -0,0 +1,3 @@
+## TODO
+
+This is a TODO stub.

docs/index.md

@@ -10,8 +10,8 @@ hero:
     alt: Jecs logo
   actions:
     - theme: brand
-      text: Overview
-      link: learn/overview.md
+      text: Get Started
+      link: learn/overview/get-started.md
     - theme: alt
       text: API References
       link: /api/jecs.md
@@ -19,7 +19,7 @@ hero:
 features:
   - title: Stupidly Fast
     icon: 🔥
-    details: Iterates 800,000 entities at 60 frames per second.
+    details: Iterates 500,000 entities at 60 frames per second.
   - title: Strictly Typed API
     icon: 🔒
     details: Has typings for both Luau and Typescript.

docs/learn/concepts/addons.md

@@ -0,0 +1,18 @@
+# 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)!
+
+# Debuggers
+## [jabby](https://github.com/alicesaidhi/jabby)
+A jecs debugger with a string-based query language and entity editing capabilities.
+
+# Schedulers
+## [lockstep scheduler](https://gist.github.com/1Axen/6d4f78b3454cf455e93794505588354b)
+A simple fixed step system scheduler.
+
+## [sapphire-jecs](https://github.com/Mark-Marks/sapphire/tree/main/crates/sapphire-jecs)
+A batteries-included [sapphire](https://github.com/mark-marks/sapphire) scheduler for jecs
+
+## [jam](https://github.com/revvy02/Jam)
+Provides hooks and a scheduler that implements jabby and a topographical runtime
+
+This page takes wording and terminology directly from Bevy's [assets page](https://bevyengine.org/assets/)

docs/learn/concepts/component-traits.md

@@ -0,0 +1,150 @@
+# Component Traits
+Component traits are IDs and pairs that can be added to components to modify their behavior. Although it is possible to create custom traits, this manual only contains an overview of all builtin component traits supported by Jecs.
+
+# Component
+Every (component) ID comes with a `Component` which helps with the distinction between normal entities and component IDs.
+
+# Tag
+A (component) ID can be marked with `Tag´ in which the component will never contain any data. This allows for zero-cost components which improves performance for structural changes.
+
+# Hooks
+Hooks are part of the "interface" of a component. You could consider hooks as the counterpart to OOP methods in ECS. They define the behavior of a component, but can only be invoked through mutations on the component data. You can only configure a single `OnAdd`, `OnRemove` and `OnSet` hook per component, just like you can only have a single constructor and destructor.
+
+## Examples
+::: code-group
+
+```luau [luau]
+local Transform= world:component()
+world:set(Transform, OnAdd, function(entity)
+    -- A transform component has been added to an entity
+end)
+world:set(Transform, OnRemove, function(entity)
+    -- A transform component has been removed from the entity
+end)
+world:set(Transform, OnSet, function(entity, value)
+    -- A transform component has been assigned/changed to value on the entity
+end)
+```
+
+```typescript [typescript]
+
+const Transform = world.component()
+world.set(Transform, OnAdd, (entity) => {
+    // A transform component has been added to an entity
+})
+world.set(Transform, OnRemove, (entity) => {
+    // A transform component has been removed from the entity
+})
+world.set(Transform, OnSet, (entity, value) => {
+    // A transform component has been assigned/changed to value on the entity
+})
+
+```
+
+:::
+
+# Cleanup Traits
+When entities that are used as tags, components, relationships or relationship targets are deleted, cleanup traits ensure that the store does not contain any dangling references. Any cleanup policy provides this guarantee, so while they are configurable, games cannot configure traits that allows for dangling references.
+
+We also want to specify this per relationship. If an entity has `(Likes, parent)` we may not want to delete that entity, meaning the cleanup we want to perform for `Likes` and `ChildOf` may not be the same.
+
+This is what cleanup traits are for: to specify which action needs to be executed under which condition. They are applied to entities that have a reference to the entity being deleted: if I delete the `Archer` tag I remove the tag from all entities that have it.
+
+To configure a cleanup policy for an entity, a `(Condition, Action)` pair can be added to it. If no policy is specified, the default cleanup action (`Remove`) is performed.
+
+There are two cleanup actions:
+
+- `Remove`: removes instances of the specified (component) id from all entities (default)
+- `Delete`: deletes all entities with specified id
+
+There are two cleanup conditions:
+
+- `OnDelete`: the component, tag or relationship is deleted
+- `OnDeleteTarget`: a target used with the relationship is deleted
+
+## Examples
+The following examples show how to use cleanup traits
+
+### (OnDelete, Remove)
+::: code-group
+
+```luau [luau]
+local Archer = world:component()
+world:add(Archer, pair(jecs.OnDelete, jecs.Remove))
+
+local e = world:entity()
+world:add(e, Archer)
+
+-- This will remove Archer from e
+world:delete(Archer)
+```
+
+```typescript [typescript]
+const Archer = world.component()
+world.add(Archer, pair(jecs.OnDelete, jecs.Remove))
+
+const e = world:entity()
+world.add(e, Archer)
+
+// This will remove Archer from e
+world.delete(Archer)
+```
+
+:::
+
+### (OnDelete, Delete)
+::: code-group
+
+```luau [luau]
+local Archer = world:component()
+world:add(Archer, pair(jecs.OnDelete, jecs.Remove))
+
+local e = world:entity()
+world:add(e, Archer)
+
+-- This will remove Archer from e
+world:delete(Archer)
+```
+
+```typescript [typescript]
+const Archer = world.component()
+world.add(Archer, pair(jecs.OnDelete, jecs.Remove))
+
+const e = world:entity()
+world.add(e, Archer)
+
+// This will remove Archer from e
+world.delete(Archer)
+```
+
+:::
+
+### (OnDeleteTarget, Delete)
+::: code-group
+
+```luau [luau]
+local ChildOf = world:component()
+world:add(ChildOf, pair(jecs.OnDeleteTarget, jecs.Delete))
+
+local parent = world:entity()
+local child = world:entity()
+world:add(child, pair(ChildOf, parent))
+
+-- This will delete both parent and child
+world:delete(parent)
+```
+
+```typescript [typescript]
+const Archer = world.component()
+world.add(Archer, pair(jecs.OnDelete, jecs.Remove))
+
+const e = world:entity()
+world.add(e, Archer)
+
+// This will delete e
+world.delete(Archer)
+```
+
+:::
+
+This page takes wording and terminology directly from Flecs [documentation](https://www.flecs.dev/flecs/md_docs_2ComponentTraits.html)

docs/learn/concepts/entities-and-components.md

@@ -0,0 +1,115 @@
+# Entities and Components
+
+## Entities
+Entities represent things in a game. In a game there may be entities of characters, buildings, projectiles, particle effects etc.
+
+By itself, an entity is just an unique identifier without any data
+
+### Creation
+
+## Components
+A component is something that is added to an entity. Components can simply tag an entity ("this entity is an `Npc`"), attach data to an entity ("this entity is at `Position` `Vector3.new(10, 20, 30)`") and create relationships between entities ("bob `Likes` alice") that may also contain data ("bob `Eats` `10` apples").
+
+### Operations
+Operation | Description
+----------|------------
+`get`     | Get a specific component or set of components from an entity.
+`add`     | Adds component to an entity. If entity already has the component, `add` does nothing.
+`set`     | Sets the value of a component for an entity. `set` behaves as a combination of `add` and `get`
+`remove`  | Removes component from entity. If entity doesn't have the component, `remove` does nothing.
+`clear`   | Remove all components from an entity. Clearing is more efficient than removing one by one.
+
+### Components are entities
+
+In an ECS, components need to be uniquely identified. In Jecs this is done by making each component is its own unique entity. If a game has a component Position and Velocity, there will be two entities, one for each component. Component entities can be distinguished from "regular" entities as they have a `Component` component. An example:
+
+::: code-group
+
+```luau [luau]
+local Position = world:component() :: jecs.Entity<Vector3>
+print(world:has(Position, Jecs.Component))
+```
+
+```typescript [typescript]
+const Position = world.component<Vector3>();
+print(world.has(Position, Jecs.Component))
+```
+
+:::
+
+All of the APIs that apply to regular entities also apply to component entities. This means it is possible to contexualize components with logic by adding traits to components
+
+::: code-group
+
+```luau [luau]
+local Networked = world:component()
+local Type = world:component()
+local Name = world:component()
+local Position = world:component() :: jecs.Entity<Vector3>
+world:add(Position, Networked)
+world:set(Position, Name, "Position")
+world:set(Position, Type, { size = 12, type = "Vector3" } ) -- 12 bytes to represent a Vector3
+
+for id, ty, name in world:query(Type, Name):with(Networked) do
+    local batch = {}
+    for entity, data in world:query(id) do
+        table.insert(batch, { entity = entity, data = data })
+    end
+    -- entities are sized f64
+    local packet = buffer.create(#batch * (8 + ty.size))
+    local offset = 0
+    for _, entityData in batch do
+        offset+=8
+        buffer.writef64(packet, offset, entityData.entity)
+        if ty.type == "Vector3" then
+            local vec3 = entity.data :: Vector3
+            offset += 4
+            buffer.writei32(packet, offset, vec3.X)
+            offset += 4
+            buffer.writei32(packet, offset, vec3.Y)
+            offset += 4
+            buffer.writei32(packet, offset, vec3.Z)
+        end
+    end
+
+    updatePositions:FireServer(packet)
+end
+```
+
+```typescript [typescript]
+const Networked = world.component()
+const Type = world.component()
+const Name = world.component()
+const Position = world.component<Vector3>();
+world.add(Position, Networked)
+world.set(Position, Name, "Position")
+world.set(Position, Type, { size: 12, type: "Vector3" } ) // 12 bytes to represent a Vector3
+
+for (const [id, ty, name] of world.query(Type, Name).with(Networked)) {
+    const batch = new Array<{ entity: Entity, data: unknown}>()
+
+    for (const [entity, data] of world.query(id)) {
+        batch.push({ entity, data })
+    }
+    // entities are sized f64
+    const packet = buffer.create(batch.size() * (8 + ty.size))
+    const offset = 0
+    for (const [_, entityData] of batch) {
+        offset+=8
+        buffer.writef64(packet, offset, entityData.entity)
+        if (ty.type == "Vector3") {
+            const vec3 = entity.data as Vector3
+            offset += 4
+            buffer.writei32(packet, offsetm, vec3.X)
+            offset += 4
+            buffer.writei32(packet, offset, vec3.Y)
+            offset += 4
+            buffer.writei32(packet, offset, vec3.Z)
+        }
+    }
+
+    updatePositions.FireServer(packet)
+}
+```
+
+:::

docs/learn/concepts/queries.md

@@ -0,0 +1,104 @@
+# Queries
+
+## Introductiuon
+
+Queries enable games to quickly find entities that satifies provided conditions.
+
+Jecs queries can do anything from returning entities that match a simple list of components, to matching against entity graphs.
+
+This manual contains a full overview of the query features available in Jecs. Some of the features of Jecs queries are:
+
+- Queries have support for relationships pairs which allow for matching against entity graphs without having to build complex data structures for it.
+- Queries support filters such as `query:with(...)` if entities are required to have the components but you don’t actually care about components value. And `query:without(...)` which selects entities without the components.
+- Queries can be drained or reset on when called, which lets you choose iterator behaviour.
+- Queries can be called with any ID, including entities created dynamically, this is useful for pairs.
+- Queries are already fast but can be futher inlined via `query:archetypes()` for maximum performance to eliminate function call overhead which is roughly 70-80% of the cost for iteration.
+
+## Creating Queries
+This section explains how to create queries in the different language bindings.
+
+:::code-group
+```luau [luau]
+for _ in world:query(Position, Velocity) do end
+```
+```typescript [typescript]
+for (const [_] of world.query(Position, Velocity)) {}
+```
+:::
+
+### Components
+A component is any single ID that can be added to an entity. This includes tags and regular entities, which are IDs that do not have the builtin `Component` component. To match a query, an entity must have all the requested components. An example:
+
+```luau
+local e1 = world:entity()
+world:add(e1, Position)
+
+local e2 = world:entity()
+world:add(e2, Position)
+world:add(e2, Velocity)
+
+local e3 = world:entity()
+world:add(e3, Position)
+world:add(e3, Velocity)
+world:add(e3, Mass)
+
+```
+Only entities `e2` and `e3` match the query Position, Velocity.
+
+### Wildcards
+
+Jecs currently only supports the `Any` type of wildcards which a single result for the first component that it matches.
+
+When using the `Any` type wildcard it is undefined which component will be matched, as this can be influenced by other parts of the query. It is guaranteed that iterating the same query twice on the same dataset will produce the same result.
+
+Wildcards are particularly useful when used in combination with pairs (next section).
+
+### Pairs
+
+A pair is an ID that encodes two elements. Pairs, like components, can be added to entities and are the foundation for [Relationships](relationships.md).
+
+The elements of a pair are allowed to be wildcards. When a query pair returns an `Any` type wildcard, the query returns at most a single matching pair on an entity.
+
+The following sections describe how to create queries for pairs in the different language bindings.
+
+:::code-group
+```luau [luau]
+local Likes = world:entity()
+local bob = world:entity()
+for _ in world:query(pair(Likes, bob)) do end
+```
+```typescript [typescript]
+const Likes = world.entity()
+const bob = world.entity()
+for (const [_] of world.query(pair(Likes, bob))) {}
+```
+:::
+
+When a query pair contains a wildcard, the `world:target()` function can be used to determine the target of the pair element that matched the query:
+
+:::code-group
+```luau [luau]
+for id in world:query(pair(Likes, jecs.Wildcard)) do
+    print(`entity {getName(id)} likes {getName(world, world:target(id, Likes))}`)
+end
+```
+```typescript [typescript]
+const Likes = world.entity()
+const bob = world.entity()
+for (const [_] of world.query(pair(Likes, jecs.Wildcard))) {
+    print(`entity ${getName(id)} likes ${getName(world.target(id, Likes))}`)
+}
+```
+:::
+
+### Filters
+Filters are extensions to queries which allow you to select entities from a more complex pattern but you don't actually care about the component values.
+
+The following filters are supported by queries:
+
+Identifier | Description
+---------- | -----------
+With       | Must match with all terms.
+Without    | Must not match with provided terms.
+
+This page takes wording and terminology directly from Flecs [documentation](https://www.flecs.dev/flecs/md_docs_2Queries.html)

docs/learn/concepts/relationships.md

@@ -0,0 +1,210 @@
+# Relationships
+Relationships makes it possible to describe entity graphs natively in ECS.
+
+Adding/removing relationships is similar to adding/removing regular components, with as difference that instead of a single component id, a relationship adds a pair of two things to an entity. In this pair, the first element represents the relationship (e.g. "Eats"), and the second element represents the relationship target (e.g. "Apples").
+
+Relationships can be used to describe many things, from hierarchies to inventory systems to trade relationships between players in a game. The following sections go over how to use relationships, and what features they support.
+
+## Definitions
+
+Name      | Description
+----------|------------
+Id	      | An id that can be added and removed
+Component | Id with a single element (same as an entity id)
+Relationship | Used to refer to first element of a pair
+Target    | Used to refer to second element of a pair
+Source    | Entity to which an id is added
+
+## Relationship queries
+There are a number of ways a game can query for relationships. The following kinds of queries are available for all (unidirectional) relationships, and are all constant time:
+
+Test if entity has a relationship pair
+
+:::code-group
+```luau [luau]
+world:has(bob, pair(Eats, Apples)
+```
+```typescript [typescript]
+world.has(bob, pair(Eats, Apples)
+```
+:::
+
+Test if entity has a relationship wildcard
+
+:::code-group
+```luau [luau]
+world:has(bob, pair(Eats, jecs.Wildcard)
+```
+```typescript [typescript]
+world.has(bob, pair(Eats, jecs.Wildcard)
+```
+:::
+
+Get parent for entity
+
+:::code-group
+```luau [luau]
+world:parent(bob)
+```
+```typescript [typescript]
+world.parent(bob, pair(Eats, jecs.Wildcard)
+```
+:::
+
+Find first target of a relationship for entity
+
+:::code-group
+```luau [luau]
+world:target(bob, Eats)
+```
+```typescript [typescript]
+world.target(bob, Eats)
+```
+:::
+
+
+Find first target of a relationship for entity
+
+:::code-group
+```luau [luau]
+world:target(bob, Eats)
+```
+```typescript [typescript]
+world.target(bob, Eats)
+```
+:::
+
+Find all entities with a pair
+
+:::code-group
+```luau [luau]
+for id in world:query(pair(Eats, Apples)) do
+    -- ...
+end
+```
+```typescript [typescript]
+for (const [id] of world.query(pair(Eats, Apples)) {
+    // ...
+}
+```
+:::
+
+Find all entities with a pair wildcard
+
+:::code-group
+```luau [luau]
+for id in world:query(pair(Eats, jecs.Wildcard)) do
+    local food = world:target(id, Eats) -- Apples, ...
+end
+```
+```typescript [typescript]
+for (const [id] of world.query(pair(Eats, jecs.Wildcard)) {
+    const food = world.target(id, Eats) // Apples, ...
+}
+```
+:::
+
+Iterate all children for a parent
+
+:::code-group
+```luau [luau]
+for child in world:query(pair(jecs.ChildOf, parent)) do
+    -- ...
+end
+```
+```typescript [typescript]
+for (const [child] of world.query(pair(jecs.ChildOf, parent)) {
+    // ...
+}
+```
+:::
+
+Relationship components
+
+Relationship pairs, just like regular component, can be associated with data.
+
+:::code-group
+```luau [luau]
+local Position = world:component()
+local Eats = world:component()
+local Apples = world:entity()
+local Begin = world:entity()
+local End = world:entity()
+
+local e = world:entity()
+world:set(e, pair(Eats, Apples), { amount = 1 })
+
+world:set(e, pair(Begin, Position), Vector3.new(0, 0, 0))
+world:set(e, pair(End, Position), Vector3.new(10, 20, 30))
+
+world:add(e, jecs.ChildOf, Position)
+
+```
+```typescript [typescript]
+const Position = world.component()
+const Eats = world.component()
+const Apples = world.entity()
+const Begin = world.entity()
+const End = world.entity()
+
+const e = world.entity()
+world.set(e, pair(Eats, Apples), { amount: 1 })
+
+world.set(e, pair(Begin, Position), new Vector3(0, 0, 0))
+world.set(e, pair(End, Position), new Vector3(10, 20, 30))
+
+world.add(e, jecs.ChildOf, Position)
+```
+:::
+
+## Relationship wildcards
+
+When querying for relationship pairs, it is often useful to be able to find all instances for a given relationship or target. To accomplish this, an game can use wildcard expressions.
+
+Wildcards may used for the relationship or target part of a pair
+
+```luau
+pair(Likes, jecs.Wildcard) -- Matches all Likes relationships
+pair(jecs.Wildcard, Alice) -- Matches all relationships with Alice as target
+```
+
+## Relationship performance
+This section goes over the performance implications of using relationships.
+
+### Introduction
+The ECS storage needs to know two things in order to store components for entities:
+- Which IDs are associated with an entity
+- Which types are associated with those ids
+Ids represent anything that can be added to an entity. An ID that is not associated with a type is called a tag. An ID associated with a type is a component. For regular components, the ID is a regular entity that has the builtin `Component` component.
+
+### Storing relationships
+Relationships do not fundamentally change or extend the capabilities of the storage. Relationship pairs are two elements encoded into a single 53-bit ID, which means that on the storage level they are treated the same way as regular component IDs. What changes is the function that determines which type is associated with an id. For regular components this is simply a check on whether an entity has `Component`. To support relationships, new rules are added to determine the type of an id.
+
+Because of this, adding/removing relationships to entities has the same performance as adding/removing regular components. This becomes more obvious when looking more closely at a function that adds a relationship pair.
+
+### Id ranges
+Jecs reserves entity ids under a threshold (HI_COMPONENT_ID, default is 256) for components. This low id range is used by the storage to more efficiently encode graph edges between archetypes. Graph edges for components with low ids use direct array indexing, whereas graph edges for high ids use a hashmap. Graph edges are used to find the next archetype when adding/removing component ids, and are a contributing factor to the performance overhead of add/remove operations.
+
+Because of the way pair IDs are encoded, a pair will never be in the low id range. This means that adding/removing a pair ID always uses a hashmap to find the next archetype. This introduces a small overhead.
+
+### Fragmentation
+Fragmentation is a property of archetype-based ECS implementations where entities are spread out over more archetypes as the number of different component combinations increases. The overhead of fragmentation is visible in two areas:
+- Archetype creation
+- ueries (queries have to match & iterate more archetypes)
+Games that make extensive use of relationships might observe high levels of fragmentation, as relationships can introduce many different combinations of components. While the Jecs storage is optimized for supporting large amounts (hundreds of thousands) of archetypes, fragmentation is a factor to consider when using relationships.
+
+Union relationships are planned along with other improvements to decrease the overhead of fragmentation introduced by relationships.
+
+### Archetype Creation
+
+When an ID added to an entity is deleted, all references to that ID are deleted from the storage. For example, when the component Position is deleted it is removed from all entities, and all archetypes with the Position component are deleted. While not unique to relationships, it is more common for relationships to trigger cleanup actions, as relationship pairs contain regular entities.
+
+The opposite is also true. Because relationship pairs can contain regular entities which can be created on the fly, archetype creation is more common than in games that do not use relationships. While Jecs is optimized for fast archetypes creation, creating and cleaning up archetypes is inherently more expensive than creating/deleting an entity. Therefore archetypes creation is a factor to consider, especially for games that make extensive use of relationships.
+
+### Indexing
+
+To improve the speed of evaluating queries, Jecs has indices that store all archetypes for a given component ID. Whenever a new archetype is created, it is registered with the indices for the IDs the archetype has, including IDs for relationship pairs.
+
+While registering a archetype for a relationship index is not more expensive than registering a archetype for a regular index, a archetype with relationships has to also register itself with the appropriate wildcard indices for its relationships. For example, an archetype with relationship `pair(Likes, Apples)` registers itself with the `pair(Likes, Apples)`, `pair(Likes, jecs.Wildcard)` and `pair(jecs.Wildcard, Apples)` indices. For this reason, creating new archetypes with relationships has a higher overhead than a archetype without relationships.
+
+This page takes wording and terminology directly from Flecs, the first ECS with full support for [Entity Relationships](https://www.flecs.dev/flecs/md_docs_2Relationships.html).

docs/learn/contributing/coverage.md

@@ -1,17 +0,0 @@
-# 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/learn/contributing/guidelines.md

@@ -1,21 +0,0 @@
-# Contribution Guidelines
-
-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/learn/contributing/issues.md

@@ -1,24 +0,0 @@
-# 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.

docs/learn/contributing/pull-requests.md

@@ -1,77 +0,0 @@
-# Submitting Pull Requests
-
-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 [resources page](../../resources), 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` 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/faq/contributing.md

@@ -0,0 +1,3 @@
+## TODO
+
+This is a TODO stub.

docs/learn/overview.md

@@ -1,718 +0,0 @@
-# Introduction
-Jecs is a standalone entity-component-system module written in Luau.
-ECS ("entity-component-system") describes one way to write games in a more data oriented design.
-
-## Installation
-
-Jecs supports the following installation methods using package managers:
-:::code-group
-```bash [wally]
-jecs = "ukendio/jecs@0.6.0" # Inside wally.toml
-```
-```bash [pesde]
-pesde add wally#ukendio/jecs@0.6.0
-```
-```bash [npm]
-npm i @rbxts/jecs
-```
-:::
-
-Additionally an `rbxm` is published with [each release under the assets submenu](https://github.com/Ukendio/jecs/releases/latest).
-
-## Hello World, Entity and Component
-It all has to start somewhere. A world stores entities and their components, and manages them. This tour will reference it for every operation.
-:::code-group
-```luau [luau]
-local jecs = require(path/to/jecs)
-local world = jecs.world()
-```
-```typescript [typescript]
-import * as jecs from "@rbxts/jecs"
-const world = jecs.world()
-// creates a new entity with no components and returns its identifier
-const entity = world.entity()
-
-// deletes an entity and all its components
-world.delete(entity)
-```
-:::
-
-## Entities
-
-Entities represent things in a game. In a game there may be entities of characters, buildings, projectiles, particle effects etc.
-
-By itself, an entity is just an unique entity identifier without any data. An entity identifier contains information about the entity itself and its generation.
-
-:::code-group
-```luau [luau]
--- creates a new entity with no components and returns its identifier
-local entity = world:entity()
-
--- deletes an entity and all its components
-world:delete(entity)
-```
-```typescript [typescript]
-// creates a new entity with no components and returns its identifier
-const entity = world.entity()
-
-// deletes an entity and all its components
-world.delete(entity)
-```
-:::
-
-The `entity` member function also accepts an overload that allows you to create an entity with a desired id which bypasses the [`entity range`](#Entity-Ranges).
-
-## Components
-
-A component is something that is added to an entity. Components can simply tag an entity ("this entity is an `Npc`"), attach data to an entity ("this entity is at `Position` `Vector3.new(10, 20, 30)`") and create relationships between entities ("bob `Likes` alice") that may also contain data ("bob `Eats` `10` apples").
-
-## Operations
-
-| Operation | Description                                                                                    |
-| --------- | ---------------------------------------------------------------------------------------------- |
-| `get`     | Get a specific component or set of components from an entity.                                  |
-| `add`     | Adds component to an entity. If entity already has the component, `add` does nothing.          |
-| `set`     | Sets the value of a component for an entity. `set` behaves as a combination of `add` and `get` |
-| `remove`  | Removes component from entity. If entity doesn't have the component, `remove` does nothing.    |
-| `clear`   | Remove all components from an entity. Clearing is more efficient than removing one by one.     |
-
-## Components are entities
-
-In an ECS, components need to be uniquely identified. In Jecs this is done by making each component its own unique entity. This means that everything is customizable. Components are no exception
-and all of the APIs that apply to regular entities also apply to component entities.
-
-If a game has a component Position and Velocity, there will be two entities, one for each component. Component entities can be distinguished from "regular" entities as they have a `Component` component trait.
-
-::: code-group
-```luau [luau]
-local Position = world:component() :: jecs.Entity<Vector3>
-world:set(Position, jecs.Name, "Position") -- Using regular apis to set metadata on component entities!
-
-print(`{world:get(Position, jecs.Name)} is a Component: {world:has(Position, jecs.Component)}`);
-
--- Output:
---  Position is a Component: true
-```
-```typescript [typescript]
-const Position = world.component<Vector3>();
-world.set(Position, jecs.Name, "Position") // Using regular apis to set metadata on component entities!
-
-print(`${world.get(Position, jecs.Name)} is a Component: ${world.has(Position, jecs.Component)}`);
-// Output:
-//  Position is a Component: true
-```
-:::
-
-### Entity ranges
-Jecs reserves entity ids under a threshold (HI_COMPONENT_ID, default is 256) for components. That means that regular entities will start after this number. This number can be further specified via the `range` member function.
-
-::: code-group
-```luau [luau]
-world:range(1000, 5000) -- Defines the lower and upper bounds of the entity range respectively
-
-local e = world:entity()
-print(e)
--- Output:
---  1000
-```
-```typescript [typescript]
-world.range(1000, 5000) // Defines the lower and upper bounds of the entity range respectively
-
-const e = world.entity()
-print(e)
-// Output:
-//  1000
-```
-:::
-
-### Hooks
-
-Component data generally need to adhere to a specific interface, and sometimes requires side effects to run upon certain lifetime cycles. In `jecs`, there are hooks which are `component traits`, that can define the behaviour of a component and enforce invariants, but can only be invoked through mutations on the component data. You can only configure a single `OnAdd`, `OnRemove` and `OnChange` hook per component, just like you can only have a single constructor and destructor.
-
-::: code-group
-```luau [luau]
-local Transform = world:component()
-world:set(Transform, OnAdd, function(entity, id, data)
-    -- A transform component `id` has been added with `data` to `entity`
-end)
-world:set(Transform, OnRemove, function(entity, id)
-    -- A transform component `id` has been removed from `entity`
-end)
-world:set(Transform, OnChange, function(entity, id, data)
-    -- A transform component `id` has been changed to `data` on `entity`
-end)
-```
-```typescript [typescript]
-const Transform = world.component();
-world.set(Transform, OnAdd, (entity, id, data) => {
-	// A transform component `id` has been added with `data` to `entity`
-});
-world.set(Transform, OnRemove, (entity, id) => {
-	// A transform component `id` has been removed from `entity`
-});
-world.set(Transform, OnChange, (entity, id, data) => {
-	// A transform component `id` has been changed to `data` on `entity`
-});
-```
-:::
-
-:::info
-Children are cleaned up before parents
-When a parent and its children are deleted, OnRemove hooks will be invoked for children first, under the condition that there are no cycles in the relationship graph of the deleted entities. This order is maintained for any relationship that has the (OnDeleteTarget, Delete) trait (see Component Traits for more details).
-
-When an entity graph contains cycles, order is undefined. This includes cycles that can be formed using different relationships.
-:::
-
-### Cleanup Traits
-
-When entities that are used as tags, components, relationships or relationship targets are deleted, cleanup traits ensure that the store does not contain any dangling references. Any cleanup policy provides this guarantee, so while they are configurable, games cannot configure traits that allows for dangling references.
-
-We also want to specify this per relationship. If an entity has `(Likes, parent)` we may not want to delete that entity, meaning the cleanup we want to perform for `Likes` and `ChildOf` may not be the same.
-
-This is what cleanup traits are for: to specify which action needs to be executed under which condition. They are applied to entities that have a reference to the entity being deleted: if I delete the `Archer` tag I remove the tag from all entities that have it.
-
-To configure a cleanup policy for an entity, a `(Condition, Action)` pair can be added to it. If no policy is specified, the default cleanup action (`Remove`) is performed.
-
-#### Cleanup Traits Summary
-
-| Condition | Action | Description | Use Case |
-|-----------|--------|-------------|----------|
-| `OnDelete` | `Remove` | Removes the component from all entities when the component is deleted | Default behavior, safe cleanup |
-| `OnDelete` | `Delete` | Deletes all entities that have the component when the component is deleted | Cascading deletion, dangerous |
-| `OnDeleteTarget` | `Remove` | Removes the relationship from all entities when the target is deleted | Safe relationship cleanup |
-| `OnDeleteTarget` | `Delete` | Deletes all entities that have the relationship when the target is deleted | Hierarchical deletion (e.g., parent-child) |
-
-**Cleanup Actions:**
-- `Remove`: removes instances of the specified (component) id from all entities (default)
-- `Delete`: deletes all entities with specified id
-
-**Cleanup Conditions:**
-- `OnDelete`: the component, tag or relationship is deleted
-- `OnDeleteTarget`: a target used with the relationship is deleted
-
-#### (OnDelete, Remove)
-::: code-group
-```luau [luau]
-local Archer = world:component()
-world:add(Archer, pair(jecs.OnDelete, jecs.Remove))
-
-local e = world:entity()
-world:add(e, Archer)
-
--- This will remove Archer from e
-world:delete(Archer)
-```
-```typescript [typescript]
-const Archer = world.component();
-world.add(Archer, pair(jecs.OnDelete, jecs.Remove));
-
-const e = world.entity();
-world.add(e, Archer);
-
-// This will remove Archer from e
-world.delete(Archer);
-```
-:::
-
-#### (OnDelete, Delete)
-::: code-group
-```luau [luau]
-local Archer = world:component()
-world:add(Archer, pair(jecs.OnDelete, jecs.Delete))
-
-local e = world:entity()
-world:add(e, Archer)
-
--- This will delete entity e because the Archer component has a (OnDelete, Delete) cleanup trait
-world:delete(Archer)
-```
-```typescript [typescript]
-const Archer = world.component();
-world.add(Archer, pair(jecs.OnDelete, jecs.Delete));
-
-const e = world.entity();
-world.add(e, Archer);
-
-// This will delete entity e because the Archer component has a (OnDelete, Delete) cleanup trait
-world.delete(Archer);
-```
-:::
-
-#### (OnDeleteTarget, Remove)
-::: code-group
-```luau [luau]
-local OwnedBy = world:component()
-world:add(OwnedBy, pair(jecs.OnDeleteTarget, jecs.Remove))
-local loot = world:entity()
-local player = world:entity()
-world:add(loot, pair(OwnedBy, player))
-
--- This will remove (OwnedBy, player) from loot
-world:delete(player)
-```
-```typescript [typescript]
-const OwnedBy = world.component();
-world.add(OwnedBy, pair(jecs.OnDeleteTarget, jecs.Remove));
-const loot = world.entity();
-const player = world.entity();
-world.add(loot, pair(OwnedBy, player));
-
-// This will remove (OwnedBy, player) from loot
-world.delete(player);
-```
-:::
-#### (OnDeleteTarget, Delete)
-::: code-group
-```luau [luau]
-local ChildOf = world:component()
-world:add(ChildOf, pair(jecs.OnDeleteTarget, jecs.Delete))
-
-local parent = world:entity()
-local child = world:entity()
-world:add(child, pair(ChildOf, parent))
-
--- This will delete both parent and child
-world:delete(parent)
-```
-```typescript [typescript]
-const ChildOf = world.component();
-world.add(ChildOf, pair(jecs.OnDeleteTarget, jecs.Delete));
-
-const parent = world.entity();
-const child = world.entity();
-world.add(child, pair(ChildOf, parent));
-
-// This will delete both parent and child
-world.delete(parent);
-```
-:::
-
-## Preregistration
-
-By default, components being registered on runtime is useful for how dynamic it can be. But, sometimes being able to register components without having the world instance is useful.
-
-::: code-group
-```luau [luau]
-local Position = jecs.component() :: jecs.Entity<Vector3>
-
-jecs.world() -- Position gets registered here
-```
-
-```typescript [typescript]
-import { world } from "@rbxts/jecs"
-const Position = jecs.component<Vector3>();
-
-world() // Position gets registered here
-```
-:::
-
-However, if you try to set metadata, you will find that this doesn't work without the world instance. Instead, jecs offers a `meta` member function that can forward declare its metadata.
-
-::: code-group
-```luau [luau]
-jecs.meta(Position, jecs.Name, "Position")
-
-jecs.world() -- Position gets registered here with its name "Position"
-```
-
-```typescript [typescript]
-import { world } from "@rbxts/jecs"
-
-jecs.meta(Position, jecs.Name, "Position")
-
-world() // Position gets registered here with its name "Position"
-```
-:::
-
-### Singletons
-
-Singletons are components for which only a single instance
-exists on the world. They can be accessed on the
-world directly and do not require providing an entity.
-Singletons are useful for global game resources, such as
-game state, a handle to a physics engine or a network socket. An example:
-
-::: code-group
-```luau [luau]
-local TimeOfDay = world:component() :: jecs.Entity<number>
-world:set(TimeOfDay, TimeOfDay, 0.5)
-local t = world:get(TimeOfDay, TimeOfDay)
-```
-
-```typescript [typescript]
-const TimeOfDay = world.component<number>();
-world.set(TimeOfDay, TimeOfDay, 0.5);
-const t = world.get(TimeOfDay, TimeOfDay);
-```
-:::
-
-# Queries
-
-Queries enable games to quickly find entities that satifies provided conditions.
-:::code-group
-
-```luau [luau]
-for _ in world:query(Position, Velocity) do end
-```
-
-```typescript [typescript]
-for (const [_] of world.query(Position, Velocity)) {
-}
-```
-:::
-
-In `jecs`, queries can do anything from returning entities that match a simple list of components, to matching against entity graphs.
-
-This manual contains a full overview of the query features available in Jecs. Some of the features of Jecs queries are:
-
--   Queries have support for relationships pairs which allow for matching against entity graphs without having to build complex data structures for it.
--   Queries support filters such as [`query:with(...)`](../api/query.md#with) if entities are required to have the components but you don’t actually care about components value. And [`query:without(...)`](../api/query.md#without) which selects entities without the components.
--   Queries can be drained or reset on when called, which lets you choose iterator behaviour.
--   Queries can be called with any ID, including entities created dynamically, this is useful for pairs.
--   Queries are already fast but can be futher inlined via [`query:archetypes()`](../api/query.md#archetypes) for maximum performance to eliminate function call overhead which is roughly 60-80% of the cost for iteration.
-
-## Performance and Caching
-
-Understanding the basic architecture of queries helps to make the right tradeoffs when using queries in games.
-The biggest impact on query performance is whether a query is cached or not.
-This section goes over what caching is, how it can be used and when it makes sense to use it.
-
-### Caching: what is it?
-
-Jecs is an archetype ECS, which means that entities with exactly the same components are
-grouped together in an "archetype". Archetypes are created on the fly
-whenever a new component combination is created in the ECS. For example:
-
-:::code-group
-
-```luau [luau]
-local e1 = world:entity()
-world:set(e1, Position, Vector3.new(10, 20, 30)) -- create archetype [Position]
-world:set(e1, Velocity, Vector3.new(1, 2, 3))    -- create archetype [Position, Velocity]
-
-local e2 = world:entity()
-world:set(e2, Position, Vector3.new(10, 20, 30)) -- archetype [Position] already exists
-world:set(e2, Velocity, Vector3.new(1, 2, 3)) 	 -- archetype [Position, Velocity] already exists
-world:set(e3, Mass, 100) 						 -- create archetype [Position, Velocity, Mass]
-
--- e1 is now in archetype [Position, Velocity]
--- e2 is now in archetype [Position, Velocity, Mass]
-```
-
-```typescript [typescript]
-const e1 = world.entity();
-world.set(e1, Position, new Vector3(10, 20, 30)); // create archetype [Position]
-world.set(e1, Velocity, new Vector3(1, 2, 3)); // create archetype [Position, Velocity]
-
-const e2 = world.entity();
-world.set(e2, Position, new Vector3(10, 20, 30)); // archetype [Position] already exists
-world.set(e2, Velocity, new Vector3(1, 2, 3)); // archetype [Position, Velocity] already exists
-world.set(e3, Mass, 100); // create archetype [Position, Velocity, Mass]
-
-// e1 is now in archetype [Position, Velocity]
-// e2 is now in archetype [Position, Velocity, Mass]
-```
-
-:::
-
-Archetypes are important for queries. Since all entities in an archetype have the same components, and a query matches entities with specific components, a query can often match entire archetypes instead of individual entities. This is one of the main reasons why queries in an archetype ECS are fast.
-
-The second reason that queries in an archetype ECS are fast is that they are cheap to cache. While an archetype is created for each unique component combination, games typically only use a finite set of component combinations which are created quickly after game assets are loaded.
-
-This means that instead of searching for archetypes each time a query is evaluated, a query can instead cache the list of matching archetypes. This is a cheap cache to maintain: even though entities can move in and out of archetypes, the archetypes themselves are often stable.
-
-If none of that made sense, the main thing to remember is that a cached query does not actually have to search for entities. Iterating a cached query just means iterating a list of prematched results, and this is really, really fast.
-
-### Tradeoffs
-
-Jecs has both cached and uncached queries. If cached queries are so fast, why even bother with uncached queries? There are four main reasons:
-
--   Cached queries are really fast to iterate, but take more time to create because the cache must be initialized first.
--   Cached queries add overhead to archetype creation/deletion, as these changes have to get propagated to caches.
--   While caching archetypes is fast, some query features require matching individual entities, which are not efficient to cache (and aren't cached).
-
-As a rule of thumb, if you have a query that is evaluated each frame (as is typically the case with systems), they will benefit from being cached. If you need to create a query ad-hoc, an uncached query makes more sense.
-
-Ad-hoc queries are often necessary when a game needs to find entities that match a condition that is only known at runtime, for example to find all child entities for a specific parent.
-
-### Components
-
-A component is any single ID that can be added to an entity. This includes tags and regular entities, which are IDs that do not have the builtin `Component` component. To match a query, an entity must have all the requested components. An example:
-
-```luau
-local e1 = world:entity()
-world:add(e1, Position)
-
-local e2 = world:entity()
-world:add(e2, Position)
-world:add(e2, Velocity)
-
-local e3 = world:entity()
-world:add(e3, Position)
-world:add(e3, Velocity)
-world:add(e3, Mass)
-
-```
-
-Only entities `e2` and `e3` match the query Position, Velocity.
-
-### Wildcards
-
-Jecs currently only supports the `Any` type of wildcards which a single result for the first component that it matches.
-
-When using the `Any` type wildcard it is undefined which component will be matched, as this can be influenced by other parts of the query. It is guaranteed that iterating the same query twice on the same dataset will produce the same result.
-
-If you want to iterate multiple targets for the same relation on a pair, then use [`world:target`](../api/world.md#target)
-
-Wildcards are particularly useful when used in combination with pairs (next section).
-
-### Pairs
-
-A pair is an ID that encodes two elements. Pairs, like components, can be added to entities and are the foundation for [`Relationships`](#relationships).
-
-The elements of a pair are allowed to be wildcards. When a query pair returns an `Any` type wildcard, the query returns at most a single matching pair on an entity.
-
-The following sections describe how to create queries for pairs in the different language bindings.
-
-:::code-group
-
-```luau [luau]
-local Likes = world:entity()
-local bob = world:entity()
-for _ in world:query(pair(Likes, bob)) do end
-```
-
-```typescript [typescript]
-const Likes = world.entity();
-const bob = world.entity();
-for (const [_] of world.query(pair(Likes, bob))) {
-}
-```
-
-:::
-
-When a query pair contains a wildcard, the `world:target()` function can be used to determine the target of the pair element that matched the query:
-
-:::code-group
-
-```luau [luau]
-for id in world:query(pair(Likes, jecs.Wildcard)) do
-    print(`entity {getName(id)} likes {getName(world, world:target(id, Likes))}`)
-end
-```
-
-```typescript [typescript]
-const Likes = world.entity();
-const bob = world.entity();
-for (const [_] of world.query(pair(Likes, jecs.Wildcard))) {
-	print(`entity ${getName(id)} likes ${getName(world.target(id, Likes))}`);
-}
-```
-
-:::
-
-### Filters
-
-Filters are extensions to queries which allow you to select entities from a more complex pattern but you don't actually care about the component values.
-
-The following filters are supported by queries:
-
-| Identifier | Description                         |
-| ---------- | ----------------------------------- |
-| With       | Must match with all terms.          |
-| Without    | Must not match with provided terms. |
-
-## Relationships
-Relationships makes it possible to describe entity graphs natively in ECS.
-
-Adding/removing relationships is similar to adding/removing regular components, with as difference that instead of a single component id, a relationship adds a pair of two things to an entity. In this pair, the first element represents the relationship (e.g. "Eats"), and the second element represents the relationship target (e.g. "Apples").
-
-Relationships can be used to describe many things, from hierarchies to inventory systems to trade relationships between players in a game. The following sections go over how to use relationships, and what features they support.
-
-### Definitions
-
-Name      | Description
-----------|------------
-Id	      | An id that can be added and removed
-Component | Id with a single element (same as an entity id)
-Relationship | Used to refer to first element of a pair
-Target    | Used to refer to second element of a pair
-Source    | Entity to which an id is added
-
-### Relationship queries
-There are a number of ways a game can query for relationships. The following kinds of queries are available for all (unidirectional) relationships, and are all constant time:
-
-Test if entity has a relationship pair
-
-:::code-group
-```luau [luau]
-world:has(bob, pair(Eats, Apples))
-```
-```typescript [typescript]
-world.has(bob, pair(Eats, Apples))
-```
-:::
-
-Test if entity has a relationship wildcard
-
-:::code-group
-```luau [luau]
-world:has(bob, pair(Eats, jecs.Wildcard))
-```
-```typescript [typescript]
-world.has(bob, pair(Eats, jecs.Wildcard))
-```
-:::
-
-Get parent for entity
-
-:::code-group
-```luau [luau]
-world:parent(bob)
-```
-```typescript [typescript]
-world.parent(bob)
-```
-:::
-
-Find first target of a relationship for entity
-
-:::code-group
-```luau [luau]
-world:target(bob, Eats)
-```
-```typescript [typescript]
-world.target(bob, Eats)
-```
-:::
-
-Find all entities with a pair
-
-:::code-group
-```luau [luau]
-for id in world:query(pair(Eats, Apples)) do
-    -- ...
-end
-```
-```typescript [typescript]
-for (const [id] of world.query(pair(Eats, Apples))) {
-    // ...
-}
-```
-:::
-
-Find all entities with a pair wildcard
-
-:::code-group
-```luau [luau]
-for id in world:query(pair(Eats, jecs.Wildcard)) do
-    local food = world:target(id, Eats) -- Apples, ...
-end
-```
-```typescript [typescript]
-for (const [id] of world.query(pair(Eats, jecs.Wildcard))) {
-    const food = world.target(id, Eats) // Apples, ...
-}
-```
-:::
-
-Iterate all children for a parent
-
-:::code-group
-```luau [luau]
-for child in world:query(pair(jecs.ChildOf, parent)) do
-    -- ...
-end
-```
-```typescript [typescript]
-for (const [child] of world.query(pair(jecs.ChildOf, parent))) {
-    // ...
-}
-```
-:::
-
-### Relationship components
-
-Relationship pairs, just like regular component, can be associated with data.
-
-:::code-group
-```luau [luau]
-local Position = world:component()
-local Eats = world:component()
-local Apples = world:entity()
-local Begin = world:entity()
-local End = world:entity()
-
-local e = world:entity()
-world:set(e, pair(Eats, Apples), { amount = 1 })
-
-world:set(e, pair(Begin, Position), Vector3.new(0, 0, 0))
-world:set(e, pair(End, Position), Vector3.new(10, 20, 30))
-
-world:add(e, pair(jecs.ChildOf, Position))
-
-```
-```typescript [typescript]
-const Position = world.component()
-const Eats = world.component()
-const Apples = world.entity()
-const Begin = world.entity()
-const End = world.entity()
-
-const e = world.entity()
-world.set(e, pair(Eats, Apples), { amount: 1 })
-
-world.set(e, pair(Begin, Position), new Vector3(0, 0, 0))
-world.set(e, pair(End, Position), new Vector3(10, 20, 30))
-
-world.add(e, pair(jecs.ChildOf, Position))
-```
-:::
-
-### Relationship wildcards
-
-When querying for relationship pairs, it is often useful to be able to find all instances for a given relationship or target. To accomplish this, an game can use wildcard expressions.
-
-Wildcards may used for the relationship or target part of a pair
-
-```luau
-pair(Likes, jecs.Wildcard) -- Matches all Likes relationships
-pair(jecs.Wildcard, Alice) -- Matches all relationships with Alice as target
-```
-
-### Relationship performance
-The ECS storage needs to know two things in order to store components for entities:
-- Which IDs are associated with an entity
-- Which types are associated with those ids
-Ids represent anything that can be added to an entity. An ID that is not associated with a type is called a tag. An ID associated with a type is a component. For regular components, the ID is a regular entity that has the builtin `Component` component.
-
-### Storing relationships
-Relationships do not fundamentally change or extend the capabilities of the storage. Relationship pairs are two elements encoded into a single 53-bit ID, which means that on the storage level they are treated the same way as regular component IDs. What changes is the function that determines which type is associated with an id. For regular components this is simply a check on whether an entity has `Component`. To support relationships, new rules are added to determine the type of an id.
-
-Because of this, adding/removing relationships to entities has the same performance as adding/removing regular components. This becomes more obvious when looking more closely at a function that adds a relationship pair.
-
-### Fragmentation
-Fragmentation is a property of archetype-based ECS implementations where entities are spread out over more archetypes as the number of different component combinations increases. The overhead of fragmentation is visible in two areas:
-- Archetype creation
-- Queries (queries have to match & iterate more archetypes)
-Games that make extensive use of relationships might observe high levels of fragmentation, as relationships can introduce many different combinations of components. While the Jecs storage is optimized for supporting large amounts (hundreds of thousands) of archetypes, fragmentation is a factor to consider when using relationships.
-
-Union relationships are planned along with other improvements to decrease the overhead of fragmentation introduced by relationships.
-
-### Archetype Creation
-
-When an ID added to an entity is deleted, all references to that ID are deleted from the storage. For example, when the component Position is deleted it is removed from all entities, and all archetypes with the Position component are deleted. While not unique to relationships, it is more common for relationships to trigger cleanup actions, as relationship pairs contain regular entities.
-
-The opposite is also true. Because relationship pairs can contain regular entities which can be created on the fly, archetype creation is more common than in games that do not use relationships. While Jecs is optimized for fast archetypes creation, creating and cleaning up archetypes is inherently more expensive than creating/deleting an entity. Therefore archetypes creation is a factor to consider, especially for games that make extensive use of relationships.
-
-### Indexing
-
-To improve the speed of evaluating queries, Jecs has indices that store all archetypes for a given component ID. Whenever a new archetype is created, it is registered with the indices for the IDs the archetype has, including IDs for relationship pairs.
-
-While registering an archetype for a relationship index is not more expensive than registering an archetype for a regular index, an archetype with relationships has to also register itself with the appropriate wildcard indices for its relationships. For example, an archetype with relationship `pair(Likes, Apples)` registers itself with the `pair(Likes, Apples)`, `pair(Likes, jecs.Wildcard)` and `pair(jecs.Wildcard, Apples)` indices. For this reason, creating new archetypes with relationships has a higher overhead than an archetype without relationships.
-
-This page takes wording and terminology directly from Flecs, the first ECS with full support for [Entity Relationships](https://www.flecs.dev/flecs/md_docs_2Relationships.html).
-
-## Next Steps
-
-- [API Reference](../api/jecs.md) - Complete API documentation

docs/learn/overview/first-jecs-project.md

@@ -0,0 +1,71 @@
+# First Jecs project
+
+Now that you have installed Jecs, you can create your [World](https://ukendio.github.io/jecs/api/world.html).
+
+:::code-group
+```luau [luau]
+local jecs = require(path/to/jecs)
+local world = jecs.World.new()
+```
+```typescript [typescript]
+import { World } from "@rbxts/jecs"
+const world = new World()
+```
+:::
+
+Let's create a couple components.
+
+:::code-group
+```luau [luau]
+local jecs = require(path/to/jecs)
+local world = jecs.World.new()
+
+local Position = world:component()
+local Velocity = world:component()
+```
+
+```typescript [typescript]
+import { World } from "@rbxts/jecs"
+const world = new World()
+
+const Position = world.component()
+const Velocity = world.component()
+```
+:::
+
+Systems can be as simple as a query in a function or a more contextualized construct. Let's make a system that moves an entity and decelerates over time.
+
+:::code-group
+```luau [luau]
+local jecs = require(path/to/jecs)
+local world = jecs.World.new()
+
+local Position = world:component()
+local Velocity = world:component()
+
+for id, position, velocity in world:query(Position, Velocity) do
+    world:set(id, Position, position + velocity)
+    world:set(id, Velocity, velocity * 0.9)
+end
+```
+
+```typescript [typescript]
+import { World } from "@rbxts/jecs"
+const world = new World()
+
+const Position = world.component()
+const Velocity = world.component()
+
+for (const [id, position, velocity] of world.query(Position, Velocity)) {
+    world.set(id, Position, position.add(velocity))
+    world.set(id, Velocity, velocity.mul(0.9))
+}
+```
+:::
+
+## Where To Get Help
+
+If you are encounting problems, there are resources for you to get help:
+- [Roblox OSS Discord server](https://discord.gg/h2NV8PqhAD) has a [#jecs](https://discord.com/channels/385151591524597761/1248734074940559511) thread under the [#projects](https://discord.com/channels/385151591524597761/1019724676265676930) channel
+- [Open an issue](https://github.com/ukendio/jecs/issues) if you run into bugs or have feature requests
+- Dive into the nitty gritty in the [thesis paper](https://raw.githubusercontent.com/Ukendio/jecs/main/thesis/drafts/1/paper.pdf)

docs/learn/overview/get-started.md

@@ -0,0 +1,130 @@
+# Getting Started
+
+## Installation
+
+### Installing Standalone
+
+Navigate to the [releases page](https://github.com/Ukendio/jecs/releases) and download `jecs.rbxm` from the assets.
+
+![jecs.rbxm](rbxm.png)
+
+### Using Wally
+
+Add the following to your wally configuration:
+
+::: code-group
+
+```toml [wally.toml]
+jecs = "ukendio/jecs@0.2.3"
+```
+
+:::
+
+### Using npm (roblox-ts)
+
+Use one of the following commands on your root project directory:
+
+::: code-group
+```bash [npm]
+npm i https://github.com/Ukendio/jecs.git
+```
+```bash [yarn]
+yarn add https://github.com/Ukendio/jecs.git
+```
+```bash [pnpm]
+pnpm add https://github.com/Ukendio/jecs.git
+```
+
+:::
+
+## Example Usage
+
+::: code-group
+
+```luau [Luau]
+local world = jecs.World.new()
+local pair = jecs.pair
+local Wildcard = jecs.Wildcard
+
+local Name = world:component()
+
+local function getName(e)
+    return world:get(e, Name)
+end
+
+local Eats = world:component()
+
+-- Relationship objects
+local Apples = world:component()
+-- components are entities, so you can add components to components
+world:set(Apples, Name, "apples")
+local Oranges = world:component()
+world:set(Oranges, Name, "oranges")
+
+local bob = world:entity()
+-- Pairs can be constructed from two entities
+
+world:set(bob, pair(Eats, Apples), 10)
+world:set(bob, pair(Eats, Oranges), 5)
+world:set(bob, Name, "bob")
+
+local alice = world:entity()
+world:set(alice, pair(Eats, Apples), 4)
+world:set(alice, Name, "alice")
+
+for id, amount in world:query(pair(Eats, Wildcard)) do
+    -- get the second target of the pair
+    local food = world:target(id, Eats)
+    print(string.format("%s eats %d %s", getName(id), amount, getName(food)))
+end
+
+-- Output:
+--   bob eats 10 apples
+--   bob eats 5 pears
+--   alice eats 4 apples  
+```
+
+
+```ts [Typescript]
+import { Wildcard, pair, World } from "@rbxts/jecs"
+
+
+const world = new World()
+const Name = world.component()
+function getName(e) {
+  return world.get(e, Name)
+}
+
+const Eats = world.component()
+
+// Relationship objects
+const Apples = world.component()
+// components are entities, so you can add components to components
+world.set(Apples, Name, "apples")
+const Oranges = world.component()
+world.set(Oranges, Name, "oranges")
+
+const bob = world.entity()
+// Pairs can be constructed from two entities
+
+world.set(bob, pair(Eats, Apples), 10)
+world.set(bob, pair(Eats, Oranges), 5)
+world.set(bob, Name, "bob")
+
+const alice = world.entity()
+world.set(alice, pair(Eats, Apples), 4)
+world.set(alice, Name, "alice")
+
+for (const [id, amount] of world.query(pair(Eats, Wildcard))) {
+  // get the second target of the pair
+  const food = world:target(id, Eats)
+  print(string.format("%s eats %d %s", getName(id), amount, getName(food)))
+}
+
+// Output:
+//   bob eats 10 apples
+//   bob eats 5 pears
+//   alice eats 4 apples   
+
+```
+

docs/public/coverage/ansi.luau.html

@@ -1,69 +0,0 @@
-<html><head>
-<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/css/bootstrap.min.css">
-<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/js/bootstrap.bundle.min.js"></script>
-<style>
-body { font-family: monospace; text-align: center; }
-#funcTable table { margin: 0 auto; width: auto; max-width: 300px; font-size: 14px; border-collapse: collapse; }
-#funcTable th, #funcTable td { padding: 2px 6px; text-align: left; white-space: nowrap; }
-#funcTable th { background-color: #ddd; }
-#funcTable td:nth-child(2) { text-align: right; min-width: 50px; }
-.zero-hits { background-color: #fcc; font-weight: bold; color: red; }
-.nonzero-hits { color: green; font-weight: bold; }
-.low-hits { background-color: #ffe6b3; }
-.high-hits { background-color: #cfc; }
-.source-code-table { margin-left: 10px; }th, td { padding: 0px; font-size: 12px; }
-table.table { font-size: 14px; border-collapse: collapse; }
-table.table th, table.table td { padding: 1px; font-size: 12px; line-height: 1.2; }
-table.table tr { height: auto; }
-</style></head><body>
-<h1 class="text-center">ansi.luau Coverage</h1>
-<h2>Total Execution Hits: 1</h2>
-<h2>Function Coverage Overview: 11.11%</h2>
-<button class="btn btn-primary mb-2" type="button" data-bs-toggle="collapse" data-bs-target="#funcTable">Toggle Function Coverage</button>
-<div class="collapse show" id="funcTable">
-<h2>Function Coverage:</h2><table class="table table-bordered"><thead><tr><th>Function</th><th>Hits</th></tr></thead><tbody>
-<tr><td style="padding: 1px; min-width: 18ch;"><main></td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
-<tr><td style="padding: 1px; min-width: 18ch;">white_underline:2</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
-<tr><td style="padding: 1px; min-width: 18ch;">white:6</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
-<tr><td style="padding: 1px; min-width: 18ch;">green:10</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
-<tr><td style="padding: 1px; min-width: 18ch;">red:14</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
-<tr><td style="padding: 1px; min-width: 18ch;">yellow:18</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
-<tr><td style="padding: 1px; min-width: 18ch;">red_highlight:22</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
-<tr><td style="padding: 1px; min-width: 18ch;">green_highlight:26</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
-<tr><td style="padding: 1px; min-width: 18ch;">gray:30</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
-</tbody></table></div>
-<h2>Source Code:</h2><table class="table table-bordered source-code-table "><thead><tr><th>Line</th><th>Hits</th><th>Code</th></tr></thead><tbody>
-<tr><td>1</td><td>1</td><td><span class=high-hits>return {</span></td></tr>
-<tr><td>2</td><td>1</td><td><span class=high-hits>white_underline = function(s: any)</span></td></tr>
-<tr><td>3</td><td>0</td><td><span class=zero-hits>return `\27[1;4m{s}\27[0m`</span></td></tr>
-<tr><td>4</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
-<tr><td>5</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
-<tr><td>6</td><td>1</td><td><span class=high-hits>white = function(s: any)</span></td></tr>
-<tr><td>7</td><td>0</td><td><span class=zero-hits>return `\27[37;1m{s}\27[0m`</span></td></tr>
-<tr><td>8</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
-<tr><td>9</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
-<tr><td>10</td><td>1</td><td><span class=high-hits>green = function(s: any)</span></td></tr>
-<tr><td>11</td><td>0</td><td><span class=zero-hits>return `\27[32;1m{s}\27[0m`</span></td></tr>
-<tr><td>12</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
-<tr><td>13</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
-<tr><td>14</td><td>1</td><td><span class=high-hits>red = function(s: any)</span></td></tr>
-<tr><td>15</td><td>0</td><td><span class=zero-hits>return `\27[31;1m{s}\27[0m`</span></td></tr>
-<tr><td>16</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
-<tr><td>17</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
-<tr><td>18</td><td>1</td><td><span class=high-hits>yellow = function(s: any)</span></td></tr>
-<tr><td>19</td><td>0</td><td><span class=zero-hits>return `\27[33;1m{s}\27[0m`</span></td></tr>
-<tr><td>20</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
-<tr><td>21</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
-<tr><td>22</td><td>1</td><td><span class=high-hits>red_highlight = function(s: any)</span></td></tr>
-<tr><td>23</td><td>0</td><td><span class=zero-hits>return `\27[41;1;30m{s}\27[0m`</span></td></tr>
-<tr><td>24</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
-<tr><td>25</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
-<tr><td>26</td><td>1</td><td><span class=high-hits>green_highlight = function(s: any)</span></td></tr>
-<tr><td>27</td><td>0</td><td><span class=zero-hits>return `\27[42;1;30m{s}\27[0m`</span></td></tr>
-<tr><td>28</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
-<tr><td>29</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
-<tr><td>30</td><td>1</td><td><span class=high-hits>gray = function(s: any)</span></td></tr>
-<tr><td>31</td><td>0</td><td><span class=zero-hits>return `\27[30;1m{s}\27[0m`</span></td></tr>
-<tr><td>32</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
-<tr><td>33</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
-</tbody></table></body></html>