Docs Static Site

.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Build documentation and deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Cancel previous run (see: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#concurrency)
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    uses: pmndrs/docs/.github/workflows/build.yml@v2
+    with:
+      mdx: 'docs'
+      libname: 'Koota'
+      home_redirect: '/getting-started/introduction'
+      icon: '🌎'
+      logo: '/logo.svg'
+      github: 'https://github.com/pmndrs/koota'
+      discord: 'https://discord.com/channels/740090768164651008/1282082309335552043'
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -1,6 +1,6 @@
 [![Discord Shield](https://img.shields.io/discord/740090768164651008?style=flat&colorA=000000&colorB=000000&label=&logo=discord&logoColor=ffffff)](https://discord.gg/poimandres)
 
-<img src="logo.svg" alt="Koota" width="100%" />
+<img src="docs/logo.svg" alt="Koota" width="100%" />
 
 Koota is an ECS-based state management library optimized for real-time apps, games, and XR experiences. Use as much or as little as you need.
 

docs/advanced/change-detection.md

@@ -0,0 +1,39 @@
+---
+title: Change detection
+description: Propagating and detecting changes
+nav: 11
+---
+
+## `updateEach`
+
+By default, `updateEach` will automatically turn on change detection for traits that are being tracked via `onChange` or the `Changed` modifier. If you want to silence change detection for a loop or force it to always run, you can do so with an options config.
+
+```js
+// Setting changeDetection to 'never' will silence it, triggering no change events
+world.query(Position, Velocity).updateEach(([position, velocity]) => {}, { changeDetection: 'never' })
+
+// Setting changeDetection to 'always' will ignore selective tracking and always emit change events for all traits that are mutated
+world
+  .query(Position, Velocity)
+  .updateEach(([position, velocity]) => {}, { changeDetection: 'always' })
+```
+
+Changed detection shallowly compares the scalar values just like React. This means objects and arrays will only be detected as changed if a new object or array is committed to the store. While immutable state is a great design pattern, it creates memory pressure and reduces performance so instead you can mutate and manually flag that a changed has occured.
+
+```js
+// ❌ This change will not be detected since the array is mutated and will pass the comparison
+world.query(Inventory).updateEach(([inventory]) => {
+  inventory.items.push(item)
+})
+
+// ✅ This change will be detected since a new array is created and the comparison will fail
+world.query(Inventory).updateEach(([inventory]) => {
+  inventory.items = [...inventory.items, item]
+})
+
+// ✅ This change is manually flagged and we still get to mutate for performance
+world.query(Inventory).updateEach(([inventory], entity) => {
+  inventory.items.push(item)
+  entity.changed()
+})
+```

docs/advanced/performance.md

@@ -0,0 +1,60 @@
+---
+title: Performance
+description: Tips and options for added performance. 
+nav: 10
+---
+
+Performance, safety and readability are all tradeoffs. The standard patterns are plenty fast, but if you are interested in diving deeper here are some quick tips and patterns.
+
+- [Modifying trait stores directly](#modifying-trait-stores-directly)
+- [Query optimization](#query-optimization)
+
+## Modifying trait stores directly
+
+For performance-critical operations, you can modify trait stores directly using the `useStores` hook. This approach bypasses some of the safety checks and event triggers, so use it with caution. All stores are structure of arrays for performance purposes.
+
+```js
+// Returns the SoA stores
+world.query(Position, Velocity).useStores(([position, velocity], entities) => {
+  // Write our own loop over the stores
+  for (let i = 0; i < entities.length; i++) {
+    // Get the entity ID to use as the array index
+    const eid = entities[i].id()
+    // Write to each array in the store
+    position.x[eid] += velocity.x[eid] * delta
+    position.y[eid] += velocity.y[eid] * delta
+  }
+})
+```
+## Query optimization
+
+Consider these tips to optimize query performance.
+
+### Create update functions once
+
+The standard pattern for `updateEach`, and handlers in general, uses an arrow function. This has great readability since the function logic is colocated with with query, but it comes at the cost of creating a new function for every entity being updated. This can be mitigated by creating the update function once in module scope.
+
+```js
+// Create the function once
+const handleMove = ([position, velocity]) => {}
+
+function updateMovement(world) {
+  // Use it for the updateEach
+  world.query(Position, Velocity).updateEach(handleMove)
+}
+```
+
+### You can use `for of` instead of `forEach` on query results
+
+A query result is just an array of entities with some extra methods. This means you can use `for of` instead of `forEach` to get a nice iterator. Additionally, this will save a little performance since `forEach` calls a function on each member, while `for of` will compile down to what is basically a for loop.
+
+```js
+// This is nice and ergonomic but will cost some overhead since we are
+// creating a fresh function for each entity and then calling it
+world.query().forEach((entity) => {})
+
+// By contrast, this compiles down to a for loop and will have a
+// single block of code executed for each entity
+for (const entity of world.query()) {
+}
+```

docs/api/entity.md

@@ -0,0 +1,55 @@
+---
+title: Entity
+description: Entity API
+nav: 3
+---
+
+An entity is a number encoded with a world, generation and ID. Every entity is unique even if they have the same ID since they will have different generations. This makes automatic-recycling possible without reference errors. Because of this, the number of an entity won't give you its ID but will have to instead be decoded with `entity.id()`.
+
+```js
+// Add a trait to the entity
+entity.add(Position)
+
+// Remove a trait from the entity
+entity.remove(Position)
+
+// Checks if the entity has the trait
+// Return boolean
+const result = entity.has(Position)
+
+// Gets the trait record for an entity
+// Return TraitRecord
+const position = entity.get(Position)
+
+// Sets the trait and triggers a change event
+entity.set(Position, { x: 10, y: 10 })
+// Can take a callback with the previous state passed in
+entity.set(Position, (prev) => ({
+  x: prev + 1,
+  y: prev + 1,
+}))
+
+// Get the targets for a relation
+// Return Entity[]
+const targets = entity.targetsFor(Contains)
+
+// Get the first target for a relation
+// Return Entity
+const target = entity.targetFor(Contains)
+
+// Get the entity ID
+// Return number
+const id = entity.id()
+
+// Get the entity generation
+// Return number
+const generation = entity.generation()
+
+// Destroys the entity making its number no longer valid
+entity.destroy()
+```
+
+For introspection, `unpackEntity` can be used to get all of the encoded values. This can be useful for debugging.
+
+```js
+const { entityId, generation, worldId } = unpackEntity(entity)

docs/api/query-modifiers.md

@@ -0,0 +1,121 @@
+---
+title: Query Modifiers
+description: Using modifiers with queries
+nav: 6
+---
+
+Modifiers are used to filter query results enabling powerful patterns. All modifiers can be mixed together.
+
+## Not
+
+The `Not` modifier excludes entities that have specific traits from the query results.
+
+```js
+import { Not } from 'koota'
+
+const staticEntities = world.query(Position, Not(Velocity))
+```
+
+## Or
+
+By default all query parameters are combined with logical AND. The `Or` modifier enables using logical OR instead.
+
+```js
+import { Or } from 'koota'
+
+const movingOrVisible = world.query(Or(Velocity, Renderable))
+```
+
+## Added
+
+The `Added` modifier tracks all entities that have added the specified traits or relations since the last time the query was run. A new instance of the modifier must be created for tracking to be unique.
+
+```js
+import { createAdded } from 'koota'
+
+const Added = createAdded()
+
+// Track entities that added the Position trait
+const newPositions = world.query(Added(Position))
+
+// Track entities that added a ChildOf relation
+const newChildren = world.query(Added(ChildOf))
+
+// After running the query, the Added modifier is reset
+```
+
+## Removed
+
+The `Removed` modifier tracks all entities that have removed the specified traits or relations since the last time the query was run. This includes entities that have been destroyed. A new instance of the modifier must be created for tracking to be unique.
+
+```js
+import { createRemoved } from 'koota'
+
+const Removed = createRemoved()
+
+// Track entities that removed the Velocity trait
+const stoppedEntities = world.query(Removed(Velocity))
+
+// Track entities that removed a ChildOf relation
+const orphaned = world.query(Removed(ChildOf))
+
+// After running the query, the Removed modifier is reset
+```
+
+## Changed
+
+The `Changed` modifier tracks all entities that have had the specified traits or relation stores change since the last time the query was run. A new instance of the modifier must be created for tracking to be unique.
+
+```js
+import { createChanged } from 'koota'
+
+const Changed = createChanged()
+
+// Track entities whose Position has changed
+const movedEntities = world.query(Changed(Position))
+
+// Track entities whose ChildOf relation data has changed
+const updatedChildren = world.query(Changed(ChildOf))
+
+// After running the query, the Changed modifier is reset
+```
+
+## Add, remove and change events
+
+Koota allows you to subscribe to add, remove, and change events for specific traits.
+
+- `onAdd` triggers when `entity.add()` is called after the initial value has been set on the trait.
+- `onRemove` triggers when `entity.remove()` is called, but before any data has been removed.
+- `onChange` triggers when an entity's trait value has been set with `entity.set()` or when it is manually flagged with `entity.changed()`.
+
+```js
+// Subscribe to Position changes
+const unsub = world.onChange(Position, (entity) => {
+  console.log(`Entity ${entity} changed position`)
+})
+
+// Subscribe to Position additions
+const unsub = world.onAdd(Position, (entity) => {
+  console.log(`Entity ${entity} added position`)
+})
+
+// Subscribe to Position removals
+const unsub = world.onRemove(Position, (entity) => {
+  console.log(`Entity ${entity} removed position`)
+})
+
+// Trigger events
+const entity = world.spawn(Position)
+entity.set(Position, { x: 10, y: 20 })
+entity.remove(Position)
+```
+
+When subscribing to relations, callbacks receive `(entity, target)` so you know which relation pair changed. Relation `onChange` events are triggered by `entity.set(Relation(target), data)` and only on relations with data via the store prop.
+
+```js
+const Likes = relation()
+
+const unsub = world.onAdd(Likes, (entity, target) => {
+  console.log(`Entity ${entity} likes ${target}`)
+})
+```