koota

Traits are the fundamental building blocks of state in Koota. They represent specific slices of data. You can define traits with default values, initial value callbacks, or as empty tags.

• Basic Trait: Define a schema with default values.
• Callback Trait: Use a function to provide an initial value (the return value must be an object).
• Tag Trait: A trait with no data, used for marking entities (e.g., IsActive).

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 return an object)
const Mesh = trait(() => new THREE.Mesh())

// Tag trait (no data)
const IsActive = trait()

Traits are the building blocks of your state, representing slices of data with specific meanings. You can define basic traits with default values, traits with initial value callbacks (must return an object), or tag traits which contain no data.

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()

The World is the central data store in Koota. While entities appear to have methods, they are actually proxies that operate on the connected World. Each World maintains its own isolated set of entities. In most applications, you only need a single World instance.

Key characteristics:

• Isolation: Entities in one world do not overlap with entities in another.
• Singletons: Worlds can host 'World Traits', which act as singletons for global resources (e.g., a clock or global configuration).
• Lifecycle: A world can be reset() (clearing data while preserving the ID) or destroy() (nuking the world and releasing its ID).

When designing your application with Koota, avoid using large, monolithic classes. Instead, follow the core principle of decomposing logic into:

1. Traits: Pure data structures.
2. Actions: Behaviors that modify state.

This separation allows for better composability and aligns with the Entity Component System (ECS) pattern used by Koota.

Koota entities are managed outside of React's state. Because entities can be destroyed by systems at any time, never store entities in useState or useRef, as these will hold stale references to destroyed entities.

Recommended Patterns

• Startup Component: Use a dedicated component to spawn initial entities and clean them up in a useEffect return function.
• Querying: To access an entity within a component, use useQueryFirst or pass the entity as a prop from a parent renderer.
• Effects: If spawning inside a standard component, always return a cleanup function that calls entity.destroy().

// ✅ Correct: Effect with cleanup
useEffect(() => {
  const entity = world.spawn(Foo)
  return () => entity.destroy()
}, [world])

// ✅ Correct: Querying for an entity
const player = useQueryFirst(IsPlayer)

Choosing between an Action and a System depends on the intent of the logic:

• Actions: Discrete, synchronous data mutations (create, read, update, destroy). They are reusable from any context (systems, UI handlers, tests). Use them for direct mutations like createEnemy or applyDamage.
• Systems: Reactive orchestrators. They observe state changes (using createAdded, createChanged, etc.) and coordinate behavior. Use them for "when X happens, do Y" logic, such as reacting to a Poisoned trait change to apply damage over time.

Queries are used to find and process entities in batches.

• Inline Queries: world.query(TraitA, TraitB) is convenient but incurs a small hashing overhead each time it is called.
• Cached Queries: For performance-critical loops, use createQuery(TraitA, TraitB) to create a query reference once, then pass that reference to world.query(queryRef).
• Excluding Entities: To prevent an entity from appearing in any query, add the built-in IsExcluded tag to it.
• Querying All: world.query() returns all queryable entities (excluding internal system entities).

// Fast cached query
const movementQuery = createQuery(Position, Velocity);

function update(world) {
  world.query(movementQuery).updateEach(([pos, vel]) => {
    // update logic
  });
}

// Excluding an entity
entity.add(IsExcluded);

An entity is a number encoded with a world, generation, and ID.

Every entity is unique even if they share the same ID because they will have different generations. This mechanism allows for automatic recycling of IDs without causing reference errors (stale references to a previous entity with the same ID will fail because the generation won't match).

Important: Because the entity is an encoded number, the raw number itself is not the ID. To retrieve the actual ID, you must use entity.id().