Koota ECS

Koota manages state using entities with composable traits.

Glossary

• Entity - A unique identifier pointing to data defined by traits. Spawned from a world.
• Trait - A reusable data definition. Can be schema-based (SoA), callback-based (AoS), or a tag.
• Relation - A directional connection between entities to build graphs.
• World - The context for all entities and their data (traits).
• Archetype - A unique combination of traits that entities share.
• Query - Fetches entities matching an archetype. The primary way to batch update state.
• Action - A discrete, synchronous data mutation (create, update, destroy). Reusable from any call site.
• System - A reactive orchestrator that observes state changes and coordinates work, including async workflows. Runs in the frame loop or event callbacks.

Design Principles

Data-oriented

Behavior is separated from data. Data is defined as traits, entities compose traits, and systems mutate data on traits via queries. See Basic usage for a complete example.

Composable systems

Design systems as small, single-purpose units rather than monolithic functions that do everything in sequence. Each system should handle one concern so that behaviors can be toggled on/off independently.

typescript
1// Good: Composable systems - each can be enabled/disabled independently
2function applyVelocity(world: World) {}
3function applyGravity(world: World) {}
4function applyFriction(world: World) {}
5function syncToDOM(world: World) {}
6
7// Bad: Monolithic system - can't disable gravity without disabling everything
8function updatePhysicsAndRender(world: World) {
9  // velocity, gravity, friction, DOM sync all in one function
10}

This enables feature flags, debugging (disable one system to isolate issues), and flexible runtime configurations.

Decouple view from logic

Separate core state and logic (the "core") from the view ("app"):

• Run logic independent of rendering
• Swap views while keeping state (2D ↔ 3D)
• Run logic in a worker or on a server

Prefer traits + actions over classes

Prefer not to use classes to encapsulate data and behavior. Use traits for data and actions for behavior. Only use classes when required by external libraries (e.g., THREE.js objects) or the user prefers it.

Directory structure

If the user has a preferred structure, follow it. Otherwise, use this guidance: the directory structure should mirror how the app's data model is organized. Separate core state/logic from the view layer:

• Core - Pure TypeScript. Traits, systems, actions, world. No view imports.
• View - Reads from world, mutates via actions. Organized by domain/feature.

src/
├── core/              # Pure TypeScript, no view imports
│   ├── traits/
│   ├── systems/
│   ├── actions/
│   └── world.ts
└── features/          # View layer, organized by domain

Files are organized by role, not by feature slice. Traits and systems are composable and don't map cleanly to features.

For detailed patterns and monorepo structures, see references/architecture.md.

Trait types

Trait naming conventions

Relations

Relations build graphs between entities such as hierarchies, inventories, targeting.

typescript
1import { relation } from 'koota'
2
3const ChildOf = relation({ autoDestroy: 'orphan' }) // Hierarchy
4const Contains = relation({ store: { amount: 0 } }) // With data
5const Targeting = relation({ exclusive: true }) // One target only
6
7// Build graph
8const parent = world.spawn()
9const child = world.spawn(ChildOf(parent))
10
11// Query children of parent
12const children = world.query(ChildOf(parent))
13
14// Query all entities with any ChildOf relation
15const allChildren = world.query(ChildOf('*'))
16
17// Get targets from entity
18const items = entity.targetsFor(Contains) // Entity[]
19const target = entity.targetFor(Targeting) // Entity | undefined

For detailed patterns, traversal, ordered relations, and anti-patterns, see references/relations.md.

Basic usage

typescript
1import { trait, createWorld } from 'koota'
2
3// 1. Define traits
4const Position = trait({ x: 0, y: 0 })
5const Velocity = trait({ x: 0, y: 0 })
6const IsPlayer = trait()
7
8// 2. Create world and spawn entities
9const world = createWorld()
10const player = world.spawn(Position({ x: 100, y: 50 }), Velocity, IsPlayer)
11
12// 3. Query and update
13world.query(Position, Velocity).updateEach(([pos, vel]) => {
14  pos.x += vel.x
15  pos.y += vel.y
16})

Entities

Entities are unique identifiers that compose traits. Spawned from a world.

typescript
1// Spawn
2const entity = world.spawn(Position, Velocity)
3
4// Read/write traits
5entity.get(Position) // Read trait data
6entity.set(Position, { x: 10 }) // Write (triggers change events)
7entity.add(IsPlayer) // Add trait
8entity.remove(Velocity) // Remove trait
9entity.has(Position) // Check if has trait
10
11// Destroy
12entity.destroy()

Entity IDs

An entity is internally a number packed with entity ID, generation ID (for recycling), and world ID. Safe to store directly for persistence or networking.

typescript
1entity.id() // Just the entity ID (reused after destroy)
2entity // Full packed number (unique forever)

Typing

Use TraitRecord to get the type that entity.get() returns

typescript
1type PositionRecord = TraitRecord<typeof Position>

Queries

Queries fetch entities matching an archetype and are the primary way to batch update state.

typescript
1// Query and update
2world.query(Position, Velocity).updateEach(([pos, vel]) => {
3  pos.x += vel.x
4  pos.y += vel.y
5})
6
7// Read-only iteration (no write-back)
8const data: Array<{ x: number; y: number }> = []
9world.query(Position, Velocity).readEach(([pos, vel]) => {
10  data.push({ x: pos.x, y: pos.y })
11})
12
13// Get first match
14const player = world.queryFirst(IsPlayer, Position)
15
16// Filter with modifiers
17world.query(Position, Not(Velocity)) // Has Position but not Velocity
18world.query(Or(IsPlayer, IsEnemy)) // Has either trait

Note: updateEach/readEach only return data-bearing traits (SoA/AoS). Tags, Not(), and relation filters are excluded:

typescript
1world.query(IsPlayer, Position, Velocity).updateEach(([pos, vel]) => {
2  // Array has 2 elements - IsPlayer (tag) excluded
3})

For tracking changes, caching queries, and advanced patterns, see references/queries.md.

React integration

Imports: Core types (World, Entity) from 'koota'. React hooks from 'koota/react'.

Change detection: entity.set() and world.set() trigger change events that cause hooks like useTrait to rerender. For AoS traits where you mutate objects directly, manually signal with entity.changed(Trait).

For React hooks and actions, see references/react-hooks.md.

For component patterns (App, Startup, Renderer, view sync, input), see references/react-patterns.md.

Runtime

Systems query the world and update entities. Run them via frameloop (continuous) or event handlers (discrete).

For systems, frameloop, event-driven patterns, and time management, see references/runtime.md.