>({
continueCombo: null,
currentStageIndex: null,
stages: null,
startedAt: null,
})
```
#### Accessing the store directly
The store can be accessed with `getStore`, but this low-level access is risky as it bypasses Koota's guard rails. However, this can be useful for debugging where direct introspection of the store is needed. For direct store mutations, use the [`useStores` API](#modifying-trait-stores-direclty) instead.
```js
// Returns SoA or AoS depending on the trait
const positions = getStore(world, Position)
```
### Query
A Koota query is a lot like a database query. Parameters define how to find entities and efficiently process them in batches. Queries are the primary way to update and transform your app state, similar to how you'd use SQL to filter and modify database records.
#### Defining queries
Inline queries are great for readability and are optimized to be as fast as possible, but there is still some small overhead in hashing the query each time it is called.
```js
// Every time this query runs a hash for the query parameters (Position, Velocity)
// is created and then used to get the cached query internally
function updateMovement(world) {
world.query(Position, Velocity).updateEach(([pos, vel]) => {})
}
```
While this is not likely to be a bottleneck in your code compared to the actual update function, if you want to save these CPU cycles you can cache the query ahead of time and use the returned ref. This will have the additional effect of creating the internal query immediately on all worlds, otherwise it will get created the first time it is run.
```js
// The internal query is created immediately before it is invoked
const movementQuery = defineQuery(Position, Velocity)
// The query ref is used for fast array-based lookup
function updateMovement(world) {
world.query(movementQuery).updateEach(([pos, vel]) => {})
}
```
#### Query all entities
To get all queryable entities you simply query the world with no parameters.
```js
const allEntities = world.query()
```
This differs from `world.entities` which includes all entities, even system ones. Koota excludes its internal system entities from queries to keep userland queries from being polluted.
#### Excluding entities from queries
Any entity can be excluded from queries by adding the built-in tag `IsExcluded` to it. System entities get this tag added to them so that they do not interfere with the app.
```js
const entity = world.spawn(Position)
// This entity can no longer be queried
entity.add(IsExcluded)
const entities = world.query(Position)
entities.includes(entity) // This will always be false
```
### React
### `useQuery`
Reactively updates when entities matching the query changes. Returns a `QueryResult`, which is like an array of entities.
```js
// Get all entities with Position and Velocity traits
const entities = useQuery(Position, Velocity)
// Render a view
return (
<>
{entities.map((entity) => (
))}
)
```
### `useQueryFirst`
Works like `useQuery` but only returns the first result. Can either be an entity of undefined.
```js
// Get the first entity with Player and Position traits
const player = useQueryFirst(Player, Position)
// Render a view if an entity is found
return player ? : null
```
### `useWorld`
Returns the world held in context via `WorldProvider`.
```js
// Get the default world
const world = useWorld();
// Use the world to create an entity on mount
useEffect(() => {
const entity = world.spawn()
return => entity.destroy()
}, [])
```
### `WorldProvider`
The provider for the world context. A world must be created and passed in.
```js
// Create a world and pass it to the provider
const world = createWorld()
// All hooks will now use this world instead of the default
function App() {
return (
)
}
```
### `useTrait`
Observes an entity, or world, for a given trait and reactively updates when it is added, removed or changes value. The returned trait snapshot maybe `undefined` if the trait is no longer on the target. This can be used to conditionally render.
```js
// Get the position trait from an entity and reactively updates when it changes
const position = useTrait(entity, Position)
// If position is removed from entity then it will be undefined
if (!position) return null
// Render the position
return (
Position: {position.x}, {position.y}
)
```
The entity passed into `useTrait` can be `undefined` or `null`. This helps with situations where `useTrait` is combined with queries in the same component since hooks cannot be conditionally called. However, this means that result can be `undefined` if the trait is not on the entity or if the target is itself `undefined`. In most cases the distinction will not matter, but if it does you can disambiguate by testing the target.
```js
// The entity may be undefined if there is no valid result
const entity = useQueryFirst(Position, Velocity)
// useTrait handles this by returned undefined if the target passed in does not exist
const position = useTrait(entity, Position)
// However, undefined here can mean no entity or no component on entity
// To make the outcome no longer ambiguous you have to test the entity
if (!entity) return No entity found!
// Now this is narrowed to Position no longer being on the component
if (!position) return null
return (
Position: {position.x}, {position.y}
)
```
### `useTag`
Observes an entity, or world, for a tag and reactively updates when it is added or removed. Returns `true` when the tag is present or `false` when absent. Use this instead of `useTrait` for tags. For tracking the presence of non-tag traits, use `useHas`.
```js
const IsActive = trait()
function ActiveIndicator({ entity }) {
// Returns true if the entity has the tag, false otherwise
const isActive = useTag(entity, IsActive)
if (!isActive) return null
return đĸ Active
}
```
### `useHas`
Observes an entity, or world, for any trait and reactively updates when it is added or removed. Returns `true` when the trait is present or `false` when absent. Unlike `useTrait`, this only tracks presence and not the trait's value.
```js
const Health = trait({ amount: 100 })
function HealthIndicator({ entity }) {
// Returns true if the entity has the trait, false otherwise
const hasHealth = useHas(entity, Health)
if (!hasHealth) return null
return â¤ī¸ Has Health
}
```
### `useTraitEffect`
Subscribes a callback to a trait on an entity. This callback fires as an effect whenever it is added, removed or changes value without rerendering.
```js
// Subscribe to position changes on an entity and update a ref without causing a rerender
useTraitEffect(entity, Position, (position) => {
if (!position) return
meshRef.current.position.copy(position)
})
// Subscribe to world-level traits
useTraitEffect(world, GameState, (state) => {
if (!state) return
console.log('Game state changed:', state)
})
```
### `useTarget`
Observes an entity, or world, for a relation and reactively returns the first target entity. Returns `undefined` if no target exists.
```js
const ChildOf = relation()
function ParentDisplay({ entity }) {
// Returns the first target of the ChildOf relation
const parent = useTarget(entity, ChildOf)
if (!parent) return No parent
return Parent: {parent.id()}
}
```
### `useTargets`
Observes an entity, or world, for a relation and reactively returns all target entities as an array. Returns an empty array if no targets exist.
```js
const Contains = relation()
function InventoryDisplay({ entity }) {
// Returns all targets of the Contains relation
const items = useTargets(entity, Contains)
return (
{items.map((item) => (
- Item {item.id()}
))}
)
}
```
### `useActions`
Returns actions bound to the world that is in context. Use actions created by `createActions`.
```js
// Create actions
const actions = createActions((world) => ({
spawnPlayer: () => world.spawn(IsPlayer).
destroyAllPlayers: () => {
world.query(IsPlayer).forEach((player) => {
player.destroy()
})
}
}))
// Get actions bound to the world in context
const { spawnPlayer, destroyAllPlayers } = useActions();
// Call actions to modify the world in an effect or handlers
useEffect(() => {
spawnPlayer()
return () => destroyAllPlayers()
}, [])
```
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.
```bash
npm i koota
```
đ [Try the starter template](https://github.com/Ctrlmonster/r3f-koota-starter)
### First, define traits
Traits are the building blocks of your state. They represent slices of data with specific meanings.
```js
import { trait } from 'koota'
// Basic trait with default values
const Position = trait({ x: 0, y: 0 })
const Velocity = trait({ x: 0, y: 0 })
// Trait with a callback for initial value
// â ī¸ Must be an object
const Mesh = trait(() => new THREE.Mesh())
// Tag trait (no data)
const IsActive = trait()
```
### Spawn entities
Entities are spawned in a world. By adding traits to an entity they gain content.
```js
import { createWorld } from 'koota'
const world = createWorld()
const player = world.spawn(Position, Velocity)
// Initial values can be passed in to the trait by using it as a function
const goblin = world.spawn(Position({ x: 10, y: 10 }), Velocity, Mesh)
```
### Query and update data
Queries fetch entities sharing traits (archetypes). Use them to batch update entities efficiently.
```js
// updateEach mutates and writes back to stores
// Run this in a loop
world.query(Position, Velocity).updateEach(([position, velocity]) => {
position.x += velocity.x * delta
position.y += velocity.y * delta
})
// For read-only operations with no mutation, use readEach
const data = []
world.query(Position, Velocity).readEach(([position, velocity]) => {
data.push({ x: position.x, y: position.y })
})
```
### Use in your React components
Traits can be used reactively inside of React components.
```js
import { WorldProvider, useQuery, useTrait } from 'koota/react'
// Wrap your app in WorldProvider
createRoot(document.getElementById('root')!).render(